Installazione passo passo
- Crea campagna e chiave API
Nella dashboard Zefirox crea una campagna e, in Impostazioni > Altri CMS, premi Genera chiave API. La chiave va usata solo lato server, mai nel browser.
- Collega i prodotti alle campagne
Salva l'ID (UUID) della campagna sui prodotti o sulle varianti del tuo catalogo, ad esempio come attributo o metadato.
- Mostra il widget nella pagina prodotto
Inserisci un elemento `<div data-dms-campaign>`, carica lo script `dms-widget.js` dalla dashboard e chiama `window.DMSWidget.init({ campaignId, apiBase })` con l'URL API indicato nella dashboard.
- Invia gli ordini pagati
Quando il pagamento è autorizzato o incassato, invia una richiesta `POST /webhooks/order` per ogni campagna presente nell'ordine, con `campaignId`, `externalId`, `qty`, `amountAuthorized` (in centesimi) e `currency`. L'SDK JS (`sendOrderLines`) raggruppa le righe per campagna al posto tuo.
- Firma le richieste
Aggiungi `Authorization: Bearer <chiave API>`, `X-Zefirox-Timestamp` (secondi Unix), `X-Zefirox-Signature` (HMAC SHA-256) e `Idempotency-Key: <piattaforma>:<externalId>`. Gli SDK lo fanno in automatico.
- Gestisci risposte e ritentativi
Considera riuscite le risposte 2xx e 409 (ordine già registrato). Su errori di rete, 429 o 5xx ritenta con backoff generando una nuova firma a ogni tentativo.
Cosa ottieni su Headless e API
- API REST per registrare gli ordini pagati: `POST /webhooks/order`.
- SDK JavaScript ESM senza dipendenze (Node 18+ o runtime con fetch e WebCrypto), con ritentativi e gestione del 409.
- SDK PHP senza dipendenze (curl e json) con firma, conversione in centesimi e raggruppamento per campagna.
- Firma HMAC SHA-256 con timestamp e chiave di idempotenza su ogni richiesta.
- Stato pubblico della campagna (`GET /campaigns/:id/status`) per costruire interfacce personalizzate.
- Widget JavaScript installabile con uno snippet su qualsiasi sito.
Come funziona la firma
Il segreto di firma è l'hash SHA-256 (esadecimale) della chiave API. La firma è un HMAC SHA-256 calcolato su `<timestamp>.<corpo della richiesta>` e inviato come `sha256=<hex>`.
Zefirox rifiuta le richieste con firma non valida o con un timestamp che si discosta di oltre 5 minuti. La chiave di idempotenza evita ordini duplicati anche se la stessa richiesta viene ripetuta.
- `Authorization: Bearer <chiave API>`
- `X-Zefirox-Timestamp: <secondi Unix>`
- `X-Zefirox-Signature: sha256=<hex>`
- `Idempotency-Key: <piattaforma>:<externalId>`
Ordini con più campagne
Ogni richiesta riguarda una sola campagna. Se un ordine contiene prodotti di più campagne, invia una richiesta per ciascuna usando come `externalId` l'ID ordine seguito dai primi 8 caratteri dell'ID campagna. Gli SDK applicano questa regola automaticamente.
Altre piattaforme
Per piattaforme senza connettore dedicato, come Shopware, BigCommerce o Wix, si usa lo stesso schema: widget nel template della pagina prodotto e invio degli ordini pagati da un servizio o una funzione serverless con l'SDK.
Domande frequenti
Posso usare la chiave API nel frontend?
No. La chiave serve a firmare gli ordini e deve restare sul server. Nel browser si usa solo il widget, che legge lo stato pubblico della campagna.
Quando devo inviare l'ordine?
Solo quando il pagamento è autorizzato o incassato, mai all'avvio del carrello o del checkout.
Cosa significa la risposta 409?
Che l'ordine era già stato registrato: va trattata come un successo.
Gli SDK sono pubblicati su npm o Packagist?
Non ancora: i file degli SDK vengono forniti e si includono direttamente nel progetto.