Eventi
Invia le azioni dei contatti nei tuoi sistemi: un ordine effettuato o pagato, un carrello abbandonato, un prodotto visualizzato. Ogni evento viene salvato una volta, associato al contatto tramite e-mail o telefono nello spazio di lavoro predefinito dell’organizzazione e mostrato nella sua cronologia. La rotta richiede una chiave con events:write, assente nelle chiavi create prima dell’introduzione degli ambiti.
Registrare eventi
Il corpo contiene events, un array di 1–100 eventi. Vengono controllati tutti prima di salvarne uno: se uno viene rifiutato, viene rifiutata l’intera richiesta e non si salva nulla.
- Nome
id- Tipo
- string
- Descrizione
Obbligatorio: il tuo identificatore dell’evento, da 1 a 128 caratteri senza spazi, come
order-1001-paid. Rinviarlo con lo stesso identificatore lo salva una sola volta: puoi quindi ritentare la richiesta senza duplicarlo.
- Nome
type- Tipo
- string
- Descrizione
Obbligatorio: l’accaduto, tra i tipi elencati sotto.
- Nome
occurredAt- Tipo
- string
- Descrizione
Obbligatorio: quando è accaduto, in ISO 8601, come
2026-10-20T10:00:00Z. Al massimo cinque minuti nel futuro e 3650 giorni nel passato.
- Nome
email- Tipo
- string
- Descrizione
L’indirizzo e-mail della persona. Fornisci l’indirizzo, il numero di telefono o entrambi.
- Nome
phone- Tipo
- string
- Descrizione
Il numero di telefono con prefisso internazionale, come
+919812345678.
- Nome
value- Tipo
- number
- Descrizione
Il valore dell’evento, da 0, con al massimo 14 cifre intere e quattro decimali, come
1299.50. Indica anche la suacurrency. Un eventocustomer.creatednon ha valore.
- Nome
currency- Tipo
- string
- Descrizione
La valuta del valore, con codice ISO 4217, come
INR.
- Nome
properties- Tipo
- object
- Descrizione
I dettagli del tipo ammessi dalla tabella seguente. Ogni altra proprietà viene rifiutata.
| Tipo di evento | Accaduto | Proprietà ammesse |
|---|---|---|
order.placed | È stato effettuato un ordine | orderNumber, itemCount, productIds |
order.paid | È stato pagato un ordine | orderNumber, itemCount, productIds |
order.fulfilled | È stato evaso un ordine | orderNumber, itemCount, productIds |
order.cancelled | È stato annullato un ordine | orderNumber, itemCount, productIds |
order.refunded | È stato rimborsato un ordine | orderNumber, itemCount, productIds |
checkout.started | È iniziata una procedura di acquisto | itemCount, productIds |
cart.abandoned | È stato abbandonato un carrello con articoli | itemCount, productIds |
product.viewed | È stato visualizzato un prodotto | productId |
customer.created | La persona è diventata cliente | Nessuna |
orderNumber,productIde ogni identificatore inproductIdscontengono da 1 a 64 caratteri ASCII. Il primo deve essere una lettera, una cifra o#; i successivi possono contenere anche. _ : / -, come#1001ogid://shopify/Product/2.itemCountè un intero da 0 a 10000;productIdscontiene da 1 a 50 identificatori.- Le proprietà occupano al massimo 4 KB e ammettono solo gli identificatori e i conteggi indicati. Non inserire dati di carte, indirizzi o testo libero; identifica la persona tramite
emailephone.
Un ordine pagato e un carrello abbandonato
curl -X POST https://api.oblic.app/external/v1/events \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{
"events": [
{
"id": "order-1001-paid",
"type": "order.paid",
"occurredAt": "2026-10-20T10:00:00Z",
"email": "asha@example.org",
"value": 1299.50,
"currency": "INR",
"properties": { "orderNumber": "#1001", "itemCount": 2, "productIds": ["SKU-1", "SKU-2"] }
},
{
"id": "cart-7781",
"type": "cart.abandoned",
"occurredAt": "2026-10-20T11:30:00Z",
"phone": "+919812345678",
"properties": { "itemCount": 1, "productIds": ["SKU-3"] }
}
]
}'
Risposta
{
"status": "success",
"data": { "received": 2, "stored": 2, "duplicates": 0, "unmatched": 1 },
"errors": null
}
Lo stato della risposta è 202:
storedconta gli eventi nuovi salvati eduplicatesquelli già salvati secondo il loroid, quindi non salvati nuovamente.unmatchedconta gli eventi salvati senza un contatto associato. Si sceglie il contatto più vecchio nello spazio predefinito con quell’e-mail, altrimenti con quel numero telefonico o WhatsApp. Senza corrispondenza, l’evento attende. Quando il servizio di associazione è attivo, normalmente viene eseguito ogni dieci minuti; arretrati o errori possono ritardarlo. Il servizio elimina gli eventi ancora non associati 30 giorni dopo la ricezione. Un evento non crea mai un contatto.- Gli eventi di un sottoaccount usano il relativo
X-Oblic-On-Behalf-Of, come i suoi messaggi (vedi Sottoaccount).
| Rifiuto | cd | Causa |
|---|---|---|
| 400 | UNKNOWN_EVENT_TYPE | Il type dell’evento non è tra quelli ammessi |
| 400 | PERSON_REQUIRED | L’evento non indica né email né phone |
| 400 | INVALID_VALUE | Una value senza currency o una currency senza valore, un valore negativo, oltre 14 cifre intere o quattro decimali, oppure un valore per customer.created |
| 400 | INVALID_PROPERTIES | Una proprietà non ammessa dal tipo o con formato errato |
| 400 | INVALID_OCCURRED_AT | occurredAt supera di cinque minuti l’ora corrente o risale a oltre 3650 giorni fa |
| 400 | il campo interessato, come EVENTS[0].ID | events manca, è vuoto o supera 100 elementi, oppure un campo manca o ha formato errato |
| 403 | INSUFFICIENT_SCOPE | La chiave non possiede events:write |
I rifiuti indicano il campo o la posizione dell’evento, come events[2].type, senza ripetere e-mail, telefono o valori delle proprietà. La spiegazione può includere nomi di proprietà sconosciute: non inserire informazioni sensibili neppure nei nomi. La validazione del formato precede i controlli specifici del tipo; la risposta elenca i problemi rilevati in quella fase.
Avviare un percorso
Un percorso creato in Journeys può iniziare con un’azione del contatto quando il motore dei percorsi è attivo per lo spazio. Nell’editor scegli Fa qualcosa nel tuo negozio, poi il tipo di evento. Per restringere il criterio, aggiungi gli identificatori prodotto inviati dal negozio e il valore minimo richiesto, con la valuta.
- Una volta per evento: un contatto che paga due ordini avvia il percorso due volte; un evento rinviato con lo stesso
idlo avvia una sola volta. - Solo eventi recenti: un evento avvia percorsi se viene salvato con il contatto, o associato successivamente, entro 24 ore da
occurredAt. Uno più vecchio, come il caricamento di ordini storici, appare nella cronologia e conta per i segmenti, ma non avvia percorsi. - Prodotti e valore: i prodotti corrispondono ai
productIdsdell’ordine, della procedura di acquisto o del carrello, oppure alproductIdvisualizzato. Il valore deve raggiungere la soglia nella valuta indicata. Un eventocustomer.creatednon ha nessuno dei due dati e non viene limitato da tali criteri.
Da Shopify
Quando l’integrazione Shopify e il link di installazione sono configurati, collega un negozio da Impostazioni → Integrazioni → Negozio Shopify: installa Oblic in Shopify, quindi collega il negozio all’organizzazione. Se l’integrazione non è disponibile, chiedi prima all’amministratore di configurarla. Gli ordini diventano gli eventi sopra indicati, associati tramite e-mail o telefono come quelli inviati direttamente. I clienti iscritti al marketing e-mail o SMS diventano contatti con quel consenso.
| Origine Shopify | Evento risultante |
|---|---|
| Un ordine effettuato, pagato, evaso o annullato | order.placed, order.paid, order.fulfilled, order.cancelled |
| Un rimborso | order.refunded, per chi ha effettuato l’ordine, con l’importo rimborsato |
| Una procedura di acquisto con e-mail o telefono | checkout.started |
| Una procedura di acquisto inattiva da un’ora senza ordine | cart.abandoned, una volta per procedura di acquisto |
| Un cliente iscritto al marketing che non è ancora un contatto | customer.created, quando Oblic crea il contatto |
- Contenuto dell’evento: il valore dell’ordine nella valuta del negozio, il numero, il conteggio articoli e i prodotti con gli identificatori Shopify. L’evento non conserva altri dettagli dell’ordine.
- Clienti iscritti: un cliente iscritto al marketing e-mail o SMS in Shopify viene cercato tra i contatti con le regole degli eventi. Se non esiste, si crea un contatto nello spazio predefinito, con e-mail o numero come nome, e vi si registra il consenso. Un cliente non iscritto non viene mai creato come contatto.
- Disiscrizione: un cliente disiscritto in Shopify non riceve più le tue e-mail o gli SMS di campagne, automazioni e percorsi finché non si iscrive nuovamente lì. Shopify non annulla mai una disiscrizione e-mail effettuata in Oblic, ad esempio dal link di un messaggio.
- Disconnessione: scollega il negozio dalla stessa pagina e disinstalla Oblic in Shopify. La disconnessione conserva gli eventi. Negozio ed eventi vengono eliminati quando viene elaborata la successiva richiesta
shop/redactdi Shopify, non per la sola disconnessione. - Privacy dei clienti: quando Shopify richiede di eliminare i dati di un cliente, vengono eliminati i suoi eventi del negozio. Se il consenso era registrato su un contatto, i proprietari dell’organizzazione vengono avvisati in Oblic affinché eliminino il contatto. Sono avvisati anche quando il cliente richiede i propri dati.