Ogni richiesta API deve includere la tua chiave API nell'header api-key. Se la chiave manca o non appartiene al programma indicato nell'URL, l'API risponde 403.

Ogni chiave appartiene a un solo programma. Puoi creare più chiavi, per esempio una per ogni sistema che si collega a JeriCommerce, dare a ciascuna solo l'accesso che le serve ed eliminarne una qualsiasi senza toccare le altre.

Ottieni una chiave API

Per creare una chiave, vai a Settings > Technical > API keys e fai clic su Add API key. Si apre una pagina con queste impostazioni.

Pagina Add API key con Name, Expiration, Restrict key, Permissions, Restrict by IP e Status
La pagina Add API key, con Restrict key selezionato
1

Assegna un nome

Inserisci un nome in Name, per esempio il sistema che la userà.

2

Scegli quando scade

In Expiration, scegli 15 minutes, 1 hour, 1 day, 7 days, 30 days o Never. Le nuove chiavi partono da Never. Il tempo decorre dal salvataggio.

3

Scegli a cosa può accedere

Nelle nuove chiavi Restrict key è selezionato. In Permissions, seleziona almeno un'opzione. La tabella più in basso indica cosa consente ciascuna.

4

Limita gli indirizzi IP, se vuoi

Seleziona Restrict by IP per accettare richieste solo da determinati indirizzi. Inseriscine uno in IP address or CIDR range, per esempio 203.0.113.7 o 203.0.113.0/24, e fai clic su Add. Puoi aggiungere fino a 100 voci, IPv4 o IPv6.

5

Salva e copia la chiave

Fai clic su Save. La finestra API key created mostra la chiave. Copiala e conservala in un posto sicuro, perché non potrai più vederla.

Se deselezioni Restrict key, la chiave può chiamare tutta l'API e una fuga di dati è molto più rischiosa. Lascialo selezionato, a meno che un sistema non abbia davvero bisogno di accesso completo.

Includi il token nelle richieste API

Per accedere agli endpoint API, usa come valore dell'header api-key la chiave ottenuta nel passaggio precedente.

Ecco un esempio con cURL che legge un cliente:

curl --request GET \
  --url https://api.jericommerce.com/v1/programs/{program_slug}/customers/customer@example.com \
  --header 'api-key: {{ apiKey }}'

Tieni la chiave sul tuo server. Chiunque la possieda può modificare i dati dei tuoi clienti, quindi non inserirla mai in un sito web, in un'app o in qualsiasi codice che gira sul dispositivo del cliente.

Gli endpoint Anteprima del saldo ed Elenco premi sono pubblici e funzionano senza chiave.

Cosa consente ogni permesso

Una chiave con restrizioni può fare solo ciò che selezioni in Permissions. Anche i webhook di Klaviyo sono chiamate API, quindi la loro chiave ha bisogno del permesso per quell'azione.

Permesso Cosa può fare la chiave
Customers Leggere i dati del cliente
Customer tokens Ottenere un link di download e token cliente
Balance Aumentare e ridurre il saldo
Coupons and rewards Assegnare un coupon e riscattare un premio
Campaigns Inviare una Gift Card e assegnare campagne
Push Inviare una notifica push
Earning flows Eseguire un flusso di accumulo personalizzato
Subscriptions Creare o annullare l'abbonamento del programma a JeriCommerce
API integration Sincronizzare clienti e dati fedeltà tramite la Custom API Integration
VTAP Collegare un lettore NFC VTAP
MCP Usare questa chiave con il MCP di JeriCommerce: No access, Read o Write. Write include la lettura

Modifica una chiave

In Settings > Technical > API keys, fai clic sui tre puntini di una chiave e scegli Edit API key. Puoi cambiare tutto tranne il valore della chiave.

  • Expiration offre Don't change quando la chiave ha una data di scadenza, così salvare un'altra impostazione non la sposta.
  • Status, nella colonna laterale, ferma una chiave quando lo imposti su Inactive. Reimpostalo su Active per riattivarla.
  • Delete API key, nello stesso menu, rimuove la chiave. Le app che la usano smetteranno di funzionare.

L'elenco mostra un badge per ogni chiave: Active, Inactive o Expired. Le chiavi create prima di queste impostazioni non hanno restrizioni né scadenza e mostrano Unrestricted finché non le limiti.

Errori della chiave API

Questi errori arrivano nel campo message della risposta.

Stato message Cosa significa
401 API_KEY_INACTIVE La chiave non è attiva. Controlla il suo Status.
401 API_KEY_EXPIRED La Expiration della chiave è passata.
403 API_KEY_IP_NOT_ALLOWED La richiesta arriva da un indirizzo esterno a Restrict by IP.
403 API_KEY_PERMISSION_DENIED La chiave non ha il permesso per questa richiesta.