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.

Assegna un nome
Inserisci un nome in Name, per esempio il sistema che la userà.
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.
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.
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.
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. |