La nostra API include un endpoint specifico per gestire la creazione e la modifica dei dati cliente e fedeltà. Permette di effettuare diverse modifiche nella stessa chiamata API.
Usa l'email come identificativo principale del cliente e il campo feature per specificare quale parte delle sue informazioni aggiornare.
Prima di iniziare ¶
Questo endpoint fa parte della Custom API Integration. Funziona solo quando l'integrazione è attiva in JeriCommerce in Settings > Integrations > API, con la funzionalità Customer attivata. Altrimenti risponde 403 con API_INTEGRATION_REQUIRED o API_USERS_REQUIRED.
L'endpoint è protetto dall'header api-key. Consulta la documentazione sull'autenticazione.
Crea e aggiorna ¶
POST https://api.jericommerce.com/v1/programs/{program_slug}/integrations/api
Sostituisci {program_slug} con lo slug effettivo del programma. Puoi trovarlo in JeriCommerce in Settings > Technical > Program Information.
Il corpo della richiesta è un array di oggetti, quindi puoi inviare fino a 250 clienti in una sola chiamata API.
Ogni oggetto contiene l'email del cliente, il nome della funzionalità, che per i dati cliente è sempre users, e il payload con le informazioni da aggiungere o aggiornare. Se nessun cliente ha ancora quell'email, JeriCommerce ne crea uno.
Ecco la struttura JSON:
[
{
"email": "string",
"feature": "users",
"payload": {
"externalCustomerId": "string",
"firstName": "string",
"lastName": "string",
"phone": "string",
"emailVerified": boolean,
"email": "string"
}
}
]
Vediamo una per una le proprietà del payload.
email ¶
Invia questo campo solo quando l'email del cliente deve cambiare. Usa l'email attuale come email dell'oggetto e la nuova email nel payload.
Dopo la modifica, la richiesta API successiva deve usare la nuova email come identificativo.
externalCustomerId ¶
È l'identificativo del cliente esterno a JeriCommerce, di solito quello del database esterno. È obbligatorio per ogni creazione o aggiornamento.
firstName ¶
Il nome del cliente viene mostrato sulla carta fedeltà. Può avere valore nullo.
lastName ¶
Il cognome del cliente viene mostrato sulla carta fedeltà. Può avere valore nullo.
phone ¶
Numero di telefono del cliente. Per impostazione predefinita il valore è null. Se non invii un dato, il campo non viene modificato.
emailVerified ¶
Indica se l'indirizzo email del cliente è stato convalidato. Per impostazione predefinita il valore è false. Per aggiornarlo, invia il valore corretto. Se non occorre modificarlo, puoi ometterlo.
Risposta ¶
Gli elementi vengono elaborati in ordine, mentre la richiesta è aperta. Una risposta 201 con corpo vuoto significa che ogni elemento è stato salvato.
Se un elemento fallisce, la richiesta si ferma lì e restituisce l'errore. Gli elementi precedenti sono già salvati e quelli successivi non vengono elaborati, quindi correggi l'elemento che ha fallito e invia di nuovo quelli rimanenti.
Elimina un cliente ¶
Per eliminare un cliente, usa lo stesso endpoint API con il verbo HTTP DELETE e l'email del cliente nel parametro di query email. I clienti vengono eliminati uno alla volta.
DELETE https://api.jericommerce.com/v1/programs/{program_slug}/integrations/api?email={customerEmail}
Questo elimina l'intero cliente da JeriCommerce, comprese le sue informazioni fedeltà, e non si può annullare. Se tutto va a buon fine, riceverai una risposta 200. Se nessun cliente ha quell'email, riceverai un 404 con CUSTOMER_NOT_FOUND.
Errori ¶
| Codice | Stato | Significato |
|---|---|---|
API_INTEGRATION_REQUIRED |
403 |
L'integrazione API non è attiva per questo programma. |
API_USERS_REQUIRED |
403 |
La funzionalità Customer è disattivata nell'integrazione API. |
FEATURE_NOT_ENABLED |
400 |
Il valore di feature non è users né loyalty. |
MAX_OBJECTS_PER_REQUEST_EXCEEDED |
400 |
L'array ha più di 250 elementi. |
CUSTOMER_NOT_FOUND |
404 |
Solo per DELETE. Nessun cliente ha quell'email. |