Questa checklist descrive tutto ciò che ti serve prima di attivare JeriCommerce tramite integrazione API. È pensata per i team che gestiscono clienti e dati loyalty sulla propria piattaforma e vogliono sincronizzarli con JeriCommerce per usare wallet pass, notifiche push e campagne.

Scegli questo percorso quando il provider loyalty o la piattaforma esistente rimane la fonte dei dati di clienti e punti. L'opzione Shopify per un programma esistente è pensata specificamente per LoyaltyLion. Se usi un altro provider, segui questa checklist API invece di creare un secondo programma punti JeriCommerce.

1. Panoramica dello stack

Prima di iniziare, verifica quali strumenti userai:

  • La tua piattaforma — Il sistema che contiene i dati cliente e loyalty (CRM, backend personalizzato, ERP e così via).
  • JeriCommerce Wallet (installato dal Shopify App Store o configurato in modalità standalone).
  • Uno sviluppatore o un team tecnico in grado di inviare richieste HTTP all'API JeriCommerce.

L'integrazione API è progettata per i team che dispongono già di un sistema loyalty o di un database clienti e vogliono collegarlo al wallet e alle notifiche JeriCommerce.

2. Genera le credenziali API

Crea una chiave API

  • Nella dashboard JeriCommerce, vai a Settings > Technical > API Keys.
  • Fai clic su Create API Key, assegnale un nome e copia il valore: potrai visualizzarlo una sola volta.

Scopri come funziona l'autenticazione API

Trova lo slug del programma

  • Vai a Settings > Technical > Program Information.
  • Copia il Program Slug: lo userai in tutti gli URL degli endpoint API.

Tutte le richieste API vanno a:

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

3. Sincronizza i clienti

Invia i dati cliente a JeriCommerce affinché possa generare una wallet pass per ciascun cliente.

  • Usa l'endpoint POST con feature: "users" per creare o aggiornare i clienti.
  • Puoi inviare fino a 250 clienti per richiesta.
  • Campo obbligatorio: email. Campi facoltativi: firstName, lastName, phone, externalCustomerId, emailVerified.

Documentazione API clienti

Se gestisci anche i dati loyalty, puoi inviare i payload cliente e loyalty nella stessa richiesta. Assicurati che la voce del cliente preceda quella loyalty.

4. Sincronizza i dati loyalty

Se la tua piattaforma monitora punti, livelli o stato di iscrizione, sincronizza i dati con JeriCommerce affinché appaiano sulla wallet pass.

  • Usa l'endpoint POST con feature: "loyalty" per inviare saldo, stato del livello e data di iscrizione.
  • Campi obbligatori: loyaltyCustomerId, balance, memberSince.
  • Campo facoltativo: tierStatus (il nome del livello mostrato sulla wallet pass).

Documentazione API loyalty

Il cliente deve esistere in JeriCommerce prima che tu possa aggiungere i dati loyalty. Se sincronizzi entrambi nella stessa richiesta, inserisci il payload cliente prima di quello loyalty.

5. Configura i webhook (sottoscrizioni agli eventi)

Sottoscrivi gli eventi JeriCommerce per mantenere sincronizzata la tua piattaforma quando si verificano attività relative al wallet.

  • Vai a Settings > Integrations > API e inserisci il Webhook URL.
  • JeriCommerce invierà richieste HTTP POST al tuo URL per tutti i 19 eventi.
  • Ogni richiesta include una firma HMAC-SHA256 nell'header x-jericommerce-hmac-sha256 per la verifica.

Tra gli eventi ricevuti: installazione o rimozione di una wallet pass, modifica del saldo, cambio di livello, riscatto di un premio, scansione cliente al POS e altri.

Elenco completo degli eventi

6. Progetta e configura la wallet pass

Personalizza la carta loyalty

  • Apri Customize → Loyalty card, quindi scegli Apple o Google.
  • In Card, personalizza la grafica e i colori del brand. Apri Details per modificare le sezioni sul retro della pass.

Configura sezioni e link sul retro della wallet pass per accedere rapidamente a:

  • Il tuo sito web o portale clienti
  • Pagine dei premi, account o portale clienti
  • Pagine di prodotti o landing page

Genera link di download per consentire ai clienti di installare la wallet pass.

  • Usa la Customer Tokens API per generare token download per ogni cliente.
  • Il formato dell'URL di download è: https://jeri.link/{slug}/download?token={base64Token}
  • Puoi generare anche token auth per l'accesso diretto all'app cliente (premi, profilo e così via).

Opzioni di distribuzione:

  • Inserisci i link di download nelle email o negli SMS.
  • Aggiungili alle pagine account, profilo o app web.
  • Includili nei flussi successivi all'acquisto.

8. Configurazione dettagliata dello storefront e dell'account Shopify

Se usi Shopify con un'integrazione API personalizzata, di solito è meglio aggiungere le singole interfacce in punti specifici dello storefront e dell'account, invece di usare un unico hub predefinito. Scegli le soluzioni che corrispondono al percorso cliente che già gestisci:

9. Campagne e notifiche

Dopo che i clienti hanno installato le wallet pass, puoi coinvolgerli con notifiche push:

Notifiche push

  • Annuncia saldi, nuovi arrivi o offerte a tempo.

Scopri come funzionano le notifiche push

Campagne basate sulla posizione

  • Attiva una notifica push quando i clienti sono vicino a un negozio.

Scopri come funzionano le notifiche basate sulla posizione

10. Omnicanale: Shopify POS

Se hai negozi che usano Shopify POS:

La configurazione è completa: puoi lanciare JeriCommerce con l'integrazione API.