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.


POST/external/v1/events

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 sua currency. Un evento customer.created non 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 eventoAccadutoProprietà ammesse
order.placedÈ stato effettuato un ordineorderNumber, itemCount, productIds
order.paidÈ stato pagato un ordineorderNumber, itemCount, productIds
order.fulfilledÈ stato evaso un ordineorderNumber, itemCount, productIds
order.cancelledÈ stato annullato un ordineorderNumber, itemCount, productIds
order.refundedÈ stato rimborsato un ordineorderNumber, itemCount, productIds
checkout.startedÈ iniziata una procedura di acquistoitemCount, productIds
cart.abandonedÈ stato abbandonato un carrello con articoliitemCount, productIds
product.viewedÈ stato visualizzato un prodottoproductId
customer.createdLa persona è diventata clienteNessuna
  • orderNumber, productId e ogni identificatore in productIds contengono da 1 a 64 caratteri ASCII. Il primo deve essere una lettera, una cifra o #; i successivi possono contenere anche . _ : / -, come #1001 o gid://shopify/Product/2.
  • itemCount è un intero da 0 a 10000; productIds contiene 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 email e phone.

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:

  • stored conta gli eventi nuovi salvati e duplicates quelli già salvati secondo il loro id, quindi non salvati nuovamente.
  • unmatched conta 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).
RifiutocdCausa
400UNKNOWN_EVENT_TYPEIl type dell’evento non è tra quelli ammessi
400PERSON_REQUIREDL’evento non indica né email né phone
400INVALID_VALUEUna value senza currency o una currency senza valore, un valore negativo, oltre 14 cifre intere o quattro decimali, oppure un valore per customer.created
400INVALID_PROPERTIESUna proprietà non ammessa dal tipo o con formato errato
400INVALID_OCCURRED_AToccurredAt supera di cinque minuti l’ora corrente o risale a oltre 3650 giorni fa
400il campo interessato, come EVENTS[0].IDevents manca, è vuoto o supera 100 elementi, oppure un campo manca o ha formato errato
403INSUFFICIENT_SCOPELa 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 id lo 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 productIds dell’ordine, della procedura di acquisto o del carrello, oppure al productId visualizzato. Il valore deve raggiungere la soglia nella valuta indicata. Un evento customer.created non 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 ShopifyEvento risultante
Un ordine effettuato, pagato, evaso o annullatoorder.placed, order.paid, order.fulfilled, order.cancelled
Un rimborsoorder.refunded, per chi ha effettuato l’ordine, con l’importo rimborsato
Una procedura di acquisto con e-mail o telefonocheckout.started
Una procedura di acquisto inattiva da un’ora senza ordinecart.abandoned, una volta per procedura di acquisto
Un cliente iscritto al marketing che non è ancora un contattocustomer.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/redact di 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.
Questa pagina è stata utile?