L'API pubblica di JeriCommerce permette ai tuoi sistemi di lavorare con il programma fedeltà. È disponibile per ogni programma: ti basta una chiave API.

L'API copre due tipi di lavoro:

  • Azioni fedeltà: assegnare punti, assegnare coupon, riscattare premi, inviare notifiche push al wallet e leggere i dati dei clienti. Ogni azione è descritta in Automazioni, con una scheda API accanto alle opzioni Shopify Flow e Klaviyo, così puoi confrontare i canali e costruire la tua richiesta.
  • Endpoint di riferimento: quelli elencati in questa pagina, come il catalogo premi o l'anteprima del saldo.

Se vuoi che il tuo sistema sia la fonte di verità per clienti e saldi, e che riceva ogni evento dei clienti, configura invece la Custom API Integration. Va attivata in JeriCommerce e funziona insieme a questa API.

URL di base

Tutti gli endpoint si trovano sotto il tuo programma:

https://api.jericommerce.com/v1/programs/{program_slug}

Sostituisci {program_slug} con lo slug o l'ID del programma. Vanno bene entrambi. Li trovi in JeriCommerce in Settings > Technical > Program Information.

Autenticazione

Invia la tua chiave API nell'header api-key a ogni richiesta. Ogni chiave appartiene a un solo programma e funziona solo con quello. Per crearne una, consulta Autenticazione tramite API.

Convenzioni delle richieste

  • Il corpo di richieste e risposte è in JSON. Invia Content-Type: application/json.
  • I clienti sono identificati dal loro indirizzo email. Le email non distinguono tra maiuscole e minuscole.
  • La maggior parte degli endpoint di scrittura accetta un array di elementi, così puoi agire su molti clienti in una sola chiamata. Il limite è 100 elementi per richiesta, o 250 quando sincronizzi i clienti o le informazioni fedeltà tramite la Custom API Integration.

Endpoint in coda

Increase balance, Decrease balance, Redeem a reward, Assign a coupon e Send a push notification mettono ogni elemento in coda e rispondono subito 201. Un 201 significa che la richiesta era valida, non che ogni elemento sia andato a buon fine. Se un elemento fallisce in seguito (per esempio perché il cliente non esiste o non ha abbastanza punti), l'API non te lo comunica. Per verificare il risultato, ascolta il webhook degli eventi oppure leggi il cliente con Dettagli cliente.

Gli altri endpoint vengono eseguiti subito e restituiscono nella risposta il risultato o un errore.

Errori

Gli errori restituiscono un codice di stato HTTP e un corpo JSON. Il campo message contiene un codice che puoi usare nella tua integrazione:

{
  "statusCode": 404,
  "message": "CUSTOMER_NOT_FOUND",
  "path": "/v1/programs/your-program/customers/someone@example.com",
  "timestamp": "2026-10-11T09:00:00.000Z"
}

Quando il corpo della richiesta non è valido, lo stato è 400 e message è l'elenco dei campi che non hanno superato la validazione.

Stato Significato
400 La richiesta non è valida: un campo mancante o errato, oppure troppi elementi.
403 La chiave API manca o non appartiene a questo programma, oppure l'integrazione API non è attiva.
404 Il programma o il cliente non esiste.
412 Al cliente manca qualcosa che l'azione richiede, per esempio una carta fedeltà.

Endpoint

Endpoint Cosa fa
Dettagli cliente Legge profilo, saldo e livello di un cliente.
Aumenta e riduci il saldo Aggiunge o toglie punti.
Esegui un flusso di accumulo personalizzato Assegna punti tramite uno dei tuoi modi personalizzati per accumulare.
Riscatta un premio Scambia i punti di un cliente con un premio.
Assegna un coupon Assegna un coupon a un cliente.
Invia una notifica push Invia a un cliente una notifica push sul wallet.
Ottieni un link di download Crea il link per scaricare la carta fedeltà.
Anteprima del saldo Calcola i punti che un importo d'ordine farebbe guadagnare.
Elenco premi Restituisce il catalogo premi del programma.
Token cliente Crea token per i link di download e per i link di sessione della Customer App.

La Custom API Integration aggiunge gli endpoint per sincronizzare clienti e informazioni fedeltà, e il webhook degli eventi.