FileMaker, collegato
a Lakshmi Courses.

Prima connessione

1. Partire dagli esempi proposti. Usare i JSON sintetici di questa guida per il primo test tecnico. Il developer FileMaker mappa i campi sorgente su questo contratto; successivamente verifica la mappatura con esempi anonimizzati. I valori DEMO-* e demo_* sono fittizi, non fasce commerciali approvate.
2. Ricevere le credenziali tecniche. Richiedere username e Application Password dedicati tramite un canale sicuro. Nessuna credenziale è inclusa in questa pagina; la loro emissione è un passaggio separato.
3. Inviare un centro sintetico dalla rete aziendale. Usare l’URL HTTPS esatto riportato sotto e verificare la risposta per elemento. Ripetere lo stesso invio: deve risultare unchanged.

https://staging-corsi.lakshmi.it/wp-json/lakshmi/v1/sync/customers

Il dominio definitivo di produzione non è ancora attivo per questa integrazione. La raggiungibilità dall’installazione FileMaker aziendale deve ancora essere collaudata.

Autenticazione e sicurezza

Utilizzare HTTP Basic su HTTPS: username tecnico e WordPress Application Password, distinta dalla password ordinaria dell’account. L’utente deve avere il ruolo ristretto lakshmi_integrator e il permesso lakshmi_sync.

• Cookie WordPress, sessioni dell’amministratore e nonce REST non autorizzano la sincronizzazione.
• Verificare sempre il certificato TLS. Non usare opzioni che disabilitano la verifica e non inviare credenziali a URL HTTP.
• Non inserire password in URL, script condivisi, log o schermate diagnostiche. Non seguire automaticamente redirect verso altri indirizzi.
• Le credenziali possono essere revocate e sostituite. Un errore 401 richiede di controllarle, non di riprovare senza limiti.

La documentazione è pubblicamente raggiungibile tramite il link, ma non invia richieste API, non raccoglie credenziali e non contiene dati reali. L’indicizzazione è disabilitata; questo non equivale a una protezione tramite password.

Sincronizzare i centri

Inviare Content-Type: application/json. Il corpo contiene una sola proprietà, customers: un array di 1–100 record completi, per un massimo complessivo di 256 KiB / 262144 byte, inclusi spazi e codifica JSON.

{
  "customers": [
    {
      "filemaker_code": "DEMO-FM-000123",
      "name": "DEMO Centro Aurora",
      "email": "aurora@example.test",
      "price_tier": "demo_contracted",
      "is_contractor": true,
      "enabled": true,
      "revision": 1
    }
  ]
}

Non sono ammessi campi aggiuntivi, record parziali, user_id, ruoli o credenziali. Per modificare un centro, inviare di nuovo tutti i campi con una revisione maggiore. Non esistono ancora operazioni di eliminazione o cambio codice.

enabled=false blocca nuovi acquisti e pagamenti di ordini ancora aperti, senza eliminare l’account o lo storico. Il prezzo è cercato nella fascia esatta price_tier: nessun fallback, nessuna deduzione dal solo is_contractor. Una modifica dell’email FileMaker non cambia quella dell’account WordPress: l’incongruenza blocca gli acquisti fino alla verifica amministrativa.

Sincronizzare le edizioni dei corsi

La proprietà radice è courses: array JSON di 1–100 record completi, massimo 256 KiB. Stessa autenticazione dei centri. Ogni codice identifica un’edizione, anche se comprende più giornate; course_code raggruppa le edizioni dello stesso corso.

{
  "courses": [
    {
      "filemaker_code": "DEMO-ED-000001",
      "course_code": "DEMO-COURSE-001",
      "title": "DEMO Rituale viso",
      "dates": ["2026-11-09", "2026-11-10"],
      "location": "DEMO Training Centre",
      "enabled": true,
      "revision": 1
    }
  ]
}

Il corpo contiene esattamente questi sette campi per edizione. Prezzi, quantità, capienza, ID prodotto, descrizioni e immagini non fanno parte di questa API. Non esistono eliminazione o cambio codice: una modifica del codice creerebbe un’altra edizione.

{
    "results": [
        {
            "index": 0,
            "filemaker_code": "DEMO-ED-000001",
            "outcome": "created",
            "edition": {
                "id": 12,
                "filemaker_code": "DEMO-ED-000001",
                "course_code": "DEMO-COURSE-001",
                "title": "DEMO Rituale viso",
                "dates": [
                    "2026-11-09",
                    "2026-11-10"
                ],
                "location": "DEMO Training Centre",
                "enabled": true,
                "revision": 1,
                "created_at": "2026-09-10 12:00:00",
                "updated_at": "2026-09-10 12:00:00"
            }
        }
    ]
}

Il risultato usa edition, non centre. edition.id è l’ID locale dell’archivio, non un ID prodotto WooCommerce. Questo endpoint non crea prodotti WooCommerce né account o ordini. La proiezione dei prodotti è separata: viene eseguita dopo un listino valido o dalla riprova amministrativa in WooCommerce → Lakshmi Integration. Solo edizioni abilitate con almeno un’offerta vengono pubblicate. Dopo una modifica alle edizioni, ritrasmettere il listino corrente per aggiornare anche la proiezione.

Le regole di revisione e retry sono identiche a quelle dei centri, ma il contatore appartiene all’edizione. Errori 409: lakshmi_course_revision_conflict e lakshmi_course_stale_revision. Date non valide: lakshmi_course_invalid_dates, status 400 per elemento. Archivio temporaneamente non disponibile: lakshmi_course_storage_unavailable, status 503 per elemento.

Listini: una versione completa, attivata insieme

POST /sync/price-lists riceve un singolo oggetto, non un lotto: list_code, revision, currency, enabled, offers. Il primo codice di listino accettato diventa quello del catalogo; non si cambia codice tramite upsert. Una revisione maggiore sostituisce tutte le offerte attive, conservando le versioni precedenti.

Ogni offerta contiene esattamente edition_code, price_tier, ticket_type, amount_minor, included_participants e extra_participant_minor. Importi interi in centesimi di EUR; massimo 500 offerte e 256 KiB. Le edizioni devono esistere prima del listino. Tupla edizione/fascia/formula univoca; un errore rifiuta l’intera versione.

enabled=false o offers: [] ritirano le offerte. Una fascia sconosciuta non eredita altri prezzi. Non sono previsti date di validità futura, sconti cumulabili, coupon, kit, spedizioni o IVA reale in questa demo: tutti i totali sono importi di prova senza imposte. La fiscalità va definita prima della produzione.

La risposta contiene price_list.outcome (created|updated|unchanged) e catalogue.outcome (synchronized|pending). Se la proiezione è pending, il listino è già salvato: ripetere la stessa versione per ritentare i prodotti, senza incrementare la revisione. I controlli di acquisto usano sempre i dati correnti.

Scarica un listino sintetico · Campi, limiti e risposte OpenAPI

Account, partecipanti e acquisto demo

1. L’amministratore verifica il referente e crea il link privato da WooCommerce → Lakshmi Centres. Il link usa il reset password nativo WordPress, monouso e con scadenza normalmente di 24 ore. Non viene inviato da staging: si condivide separatamente con il solo referente verificato.
2. Il centro accede, sceglie edizione e formula e indica nome e cognome di ogni partecipante. Nessun account aggiuntivo per le partecipanti, nessuna richiesta di dati sanitari.
3. Carrello e checkout ricontrollano collegamento, abilitazione, fascia, edizione e listino. Se cambia un dato confermato, la formula va rimossa e aggiunta di nuovo: nessun aumento di prezzo silenzioso.
4. Pagamento demo — nessun addebito registra l’ordine simulato. Il gateway esiste solo con la modalità demo esplicitamente abilitata in locale o staging HTTPS; non funziona in produzione e non contatta Stripe o PayPal.

Una riga carrello è una formula con quantità sempre 1, separata dal numero di persone. Massimo 20 persone per formula, 10 formule e 100 partecipazioni per ordine; snapshot massimo 180 KiB per mantenere esportabile l’evento. Checkout WooCommerce classico: blocchi Checkout/Store API non sono supportati. Non mischiare corsi e prodotti estranei.

Ogni ordine conserva una copia immutabile del centro, delle edizioni, delle condizioni di listino e dei nominativi. Aggiornare FileMaker non modifica lo storico acquistato. L’area account mostra ordini e partecipanti; gli amministratori gestiscono gli ordini e i rimborsi simulati da WooCommerce.

Recuperare gli ordini, poi confermare l’acquisizione

GET /events?limit=100 restituisce {"events": [...], "count": n} con i più vecchi eventi non acquisiti; limit da 1 a 100, nessun cursore. Un secondo GET senza ACK restituisce ancora gli stessi eventi. Elaborare e confermare la pagina, poi richiedere la successiva; fermarsi quando events è vuoto. Un errore 503 non equivale a una coda vuota.

Ogni evento contiene un event_id UUID stabile, un numero sequence, tipo, ID ordine, payload immutabile, data UTC e stato di acquisizione. I tipi disponibili sono order.paid e order.refunded. Gli importi nel payload sono centesimi interi; demo: true e money_moved: false distinguono le simulazioni.

1. FileMaker cerca event_id nel proprio registro. Se presente, non crea una seconda iscrizione.
2. Se nuovo, salva ordine, righe, nominativi e ricevuta evento in una transazione locale. Conserva gli identificativi WooCommerce, non soltanto i titoli.
3. Solo dopo il salvataggio invia POST /events/ack con {"acknowledgements":[{"event_id":"…","filemaker_id":"FM-ORDER-001"}]}, massimo 100 elementi.
4. Se si perde la risposta ACK, ripete lo stesso evento e riferimento: unchanged. Lo stesso evento con un riferimento diverso produce conflitto 409. HTTP 200 del lotto non elimina la necessità di controllare ogni risultato.

Rimborsi

Un rimborso totale o parziale genera un nuovo evento con proprio UUID, refund_id, paid_event_id e importo positivo. Può non contenere righe quando è solo economico. participant_cancellations: [] è intenzionale: rimborsare un importo non identifica quali persone annullare. Modifiche nominativi, annullamenti d’iscrizione e ricalcolo commerciale post-acquisto richiedono un contratto successivo.

Esempi pagamento e rimborso · Esempio ACK

Leggere gli esiti

HTTP 200 ≠ tutti i record acquisiti.

Un lotto valido produce un risultato per ciascun elemento, nello stesso ordine. Usare index e il codice per la correlazione. Marcare un record come sincronizzato solo con outcome uguale a created, updated o unchanged.

{
    "results": [
        {
            "index": 0,
            "filemaker_code": "DEMO-FM-000123",
            "outcome": "created",
            "centre": {
                "id": 42,
                "filemaker_code": "DEMO-FM-000123",
                "user_id": null,
                "name": "DEMO Centro Aurora",
                "email": "aurora@example.test",
                "price_tier": "demo_contracted",
                "is_contractor": true,
                "enabled": true,
                "revision": 1,
                "created_at": "2026-09-10 12:00:00",
                "updated_at": "2026-09-10 12:00:00"
            }
        }
    ]
}

id è l’identificatore locale del centro; user_id: null significa che l’account non è ancora collegato. created_at e updated_at sono UTC nel formato YYYY-MM-DD HH:mm:ss, non RFC3339.

{
    "results": [
        {
            "index": 0,
            "filemaker_code": "DEMO-FM-000123",
            "outcome": "error",
            "error": {
                "code": "lakshmi_stale_revision",
                "message": "A newer centre revision is already stored.",
                "status": 409
            }
        }
    ]
}

In un lotto misto, i record validi restano salvati anche se altri falliscono. Il codice restituito per un elemento invalido è solo diagnostico: può essere troncato o null. Per questi casi usare sempre index.

Errori dell’intera richiesta

Gli errori globali non contengono results: hanno la struttura WordPress code, message, data.status. Interpretare codice e stato, non il testo del messaggio.

Distinguere il 503 globale dal singolo error.status: 503 con codice lakshmi_storage_unavailable (centri) o lakshmi_course_storage_unavailable (edizioni) dentro una risposta HTTP 200.

Revisioni, tentativi ripetuti e recupero

Il confronto usa nome trimmato, email trimmata e minuscola; l’ordine delle proprietà JSON non conta. La revisione appartiene a FileMaker ed è distinta da updated_at, che può cambiare anche per un collegamento account.

• Timeout, errore di rete o risposta incompleta: non segnare l’acquisizione. Riprovare lo stesso contenuto e la stessa revisione: il precedente invio potrebbe essere già riuscito.
• 503: usare tentativi limitati con attesa crescente e una coda persistente lato FileMaker.
• 400/409: correggere il dato o risolvere il conflitto alla fonte. Non incrementare ciecamente la revisione per forzare la scrittura.
• Lotti: consigliato un solo record aggiornato per codice. I duplicati nello stesso lotto vengono comunque elaborati in ordine, con transazioni indipendenti.

La coda e la pianificazione degli invii nel gestionale sono responsabilità dello sviluppo FileMaker. Sul sito, WooCommerce → Lakshmi Integration mostra listino, eventi e acquisizioni e consente la riprova di catalogo ed eventi senza acquisirli al posto di FileMaker.

Esempio pratico per FileMaker

Il riferimento scaricabile mostra la costruzione JSON, la chiamata Insert from URL, la lettura degli header HTTP e il controllo degli esiti. Usa esclusivamente variabili per le credenziali.

Scarica lo schema dello script FileMaker (.txt)

Tipi JSON e versione

Usare JSONString per il codice, JSONBoolean per i flag e JSONNumber per la revisione intera. La validazione della risposta proposta usa JSONGetElementType, disponibile da FileMaker 19.5; verificare la versione installata e i nomi delle funzioni correnti prima del collaudo. Fonti: JSONSetElement e JSONGetElementType.

Trasporto ed errori

--data @$requestBody legge il corpo da una variabile FileMaker; --dump-header $responseHeaders raccoglie gli header in un’altra variabile. Leggere l’ultimo stato HTTP: possono esserci più blocchi. Non usare --write-out, che non compare tra le opzioni supportate. Opzioni cURL supportate da Claris.

Catturare errore e dettaglio immediatamente dopo Insert from URL, prima di altri passi. Lasciare attiva la verifica del certificato. Controllare sia l’errore FileMaker sia lo stato HTTP e poi ogni outcome. Fonti: Get(LastErrorDetail), Set Error Capture, Insert from URL.

Checklist del collaudo congiunto

1. Confermare versione FileMaker/Server, processo pianificato e possibilità di connessioni HTTPS in uscita.
2. Concordare codici, fasce ed email di prova, senza dati personali reali. Ricevere la credenziale tecnica separatamente.
3. Inviare un centro sintetico: created. Ripetere senza modifiche: unchanged.
4. Inviare un’edizione sintetica con due giornate. Ripetere le stesse date in ordine diverso: unchanged. Verificare che una data impossibile venga rifiutata e che non compaiano prodotti nel negozio.
5. Aggiornare la fascia con revisione maggiore: updated. Ripetere una revisione vecchia: errore 409.
6. Provare un lotto misto valido/invalido: acquisire solo i risultati riusciti.
7. Simulare timeout e retry senza duplicare centri. Provare revoca delle credenziali e gestione del 401.
8. Inviare un listino completo dopo le edizioni, ripeterlo e verificare prezzi diversi per i due centri demo. Una versione invalida non deve attivare prezzi parziali.
9. Acquistare un singolo e un pacchetto con partecipante extra; verificare nominativi, totale e storico nell’account.
10. Recuperare l’evento, simulare un’interruzione dopo il salvataggio FileMaker ma prima dell’ACK, riprendere senza duplicati e confermare.
11. Creare un rimborso parziale e verificarne l’evento distinto senza dedurre cancellazioni dei nominativi.
12. Disabilitare un centro o aggiornare un listino con un carrello aperto; il nuovo acquisto deve essere bloccato o richiedere nuova conferma.

Già verificato sul lato WordPress: validazione, autenticazione, idempotenza e richieste concorrenti con test automatici. Ancora da verificare: chiamate dalla rete aziendale e funzionamento dello script nella versione FileMaker installata.

Proposta di integrazione e punti da confermare

Happy Brain propone il contratto tecnico; il developer FileMaker realizza la mappatura; Lakshmi conferma le regole commerciali. La demo procede con ipotesi dichiarate. Le conferme riguardano l’avvio reale e le estensioni commerciali, non bloccano il collaudo tecnico con dati fittizi.

Sono già concordati: WooCommerce, connessioni avviate solo da FileMaker, codice riferito al centro, un account per centro e nessun limite di posti. Campi, formati e regole di revisione riportati nelle sezioni API sono invece la nostra proposta tecnica, già applicata sul sito per i test.

Su cosa possiamo procedere

Il percorso demo è disponibile dal catalogo fino al pagamento simulato e all’acquisizione dell’ordine. Il prossimo passo con il developer è eseguire questi stessi scenari dalla rete aziendale, usando la mappatura FileMaker. Prima di attivare vendite reali servono prezzi e condizioni approvati, fiscalità, gateway reali e collaudo congiunto.

Al developer FileMaker chiediamo di confermare la fattibilità di questa proposta e segnalare eventuali adattamenti, non di progettare al posto nostro il contratto del sito. Una conferma non ricevuta rimane aperta; non viene interpretata come approvazione.

Prima della produzione

Il completamento della demo non autorizza vendite reali. Restano da completare i seguenti passaggi, senza interpretarli come approvati.