Ereignisse

Übermitteln Sie Aktionen Ihrer Kontakte aus eigenen Systemen: eine aufgegebene oder bezahlte Bestellung, einen verlassenen Warenkorb oder einen Produktaufruf. Jedes Ereignis wird einmal gespeichert, im Standardarbeitsbereich Ihrer Organisation anhand von E-Mail-Adresse oder Telefonnummer zugeordnet und in der Kontaktchronik angezeigt. Diese Route verlangt einen Schlüssel mit events:write; vor Einführung der Berechtigungsbereiche erstellte Schlüssel besitzen diesen Bereich nicht.


POST/external/v1/events

Ereignisse erfassen

Der Anfragetext enthält events, ein Array mit 1 bis 100 Ereignissen. Vor dem Speichern werden alle geprüft: Wird eines abgelehnt, wird die gesamte Anfrage abgelehnt und nichts gespeichert.

  • Name
    id
    Typ
    string
    Beschreibung

    Erforderlich: Ihre eigene Ereigniskennung mit 1 bis 128 Zeichen ohne Leerzeichen, etwa order-1001-paid. Ein erneut mit derselben Kennung gesendetes Ereignis wird nur einmal gespeichert; Sie können die Anfrage daher ohne Duplikat wiederholen.

  • Name
    type
    Typ
    string
    Beschreibung

    Erforderlich: der Vorgang, als einer der unten genannten Typen.

  • Name
    occurredAt
    Typ
    string
    Beschreibung

    Erforderlich: der Zeitpunkt in ISO 8601, etwa 2026-10-20T10:00:00Z. Er darf höchstens fünf Minuten in der Zukunft und höchstens 3650 Tage zurückliegen.

  • Name
    email
    Typ
    string
    Beschreibung

    Die E-Mail-Adresse der Person. Geben Sie diese, die Telefonnummer oder beides an.

  • Name
    phone
    Typ
    string
    Beschreibung

    Die Telefonnummer mit Landesvorwahl, etwa +919812345678.

  • Name
    value
    Typ
    number
    Beschreibung

    Der Ereigniswert ab 0, mit höchstens 14 Vorkommastellen und vier Nachkommastellen, etwa 1299.50. Geben Sie die zugehörige currency an. Ein Ereignis customer.created besitzt keinen Wert.

  • Name
    currency
    Typ
    string
    Beschreibung

    Die Währung des Werts als ISO-4217-Code, etwa INR.

  • Name
    properties
    Typ
    object
    Beschreibung

    Die laut folgender Tabelle erlaubten Angaben dieses Typs. Andere Eigenschaften werden abgelehnt.

EreignistypWas geschehen istErlaubte Eigenschaften
order.placedEine Bestellung wurde aufgegebenorderNumber, itemCount, productIds
order.paidEine Bestellung wurde bezahltorderNumber, itemCount, productIds
order.fulfilledEine Bestellung wurde ausgeführtorderNumber, itemCount, productIds
order.cancelledEine Bestellung wurde storniertorderNumber, itemCount, productIds
order.refundedEine Bestellung wurde erstattetorderNumber, itemCount, productIds
checkout.startedEin Bezahlvorgang wurde begonnenitemCount, productIds
cart.abandonedEin Warenkorb mit Artikeln wurde verlassenitemCount, productIds
product.viewedEin Produkt wurde angesehenproductId
customer.createdDie Person wurde KundeKeine
  • orderNumber, productId und jede Kennung in productIds bestehen aus 1 bis 64 ASCII-Zeichen. Das erste Zeichen muss ein Buchstabe, eine Ziffer oder # sein; danach sind auch . _ : / - erlaubt, etwa #1001 oder gid://shopify/Product/2.
  • itemCount ist eine ganze Zahl von 0 bis 10000; productIds enthält 1 bis 50 Kennungen.
  • Eigenschaften belegen höchstens 4 KB und erlauben nur die genannten Kennungen und Anzahlen. Tragen Sie dort keine Zahlungskartendaten, Anschriften oder Freitexte ein; verwenden Sie zur Personenidentifikation email und phone.

Eine bezahlte Bestellung und ein verlassener Warenkorb

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"] }
      }
    ]
  }'

Antwort

{
  "status": "success",
  "data": { "received": 2, "stored": 2, "duplicates": 0, "unmatched": 1 },
  "errors": null
}

Die Antwort hat den Status 202:

  • stored zählt neue gespeicherte Ereignisse; duplicates zählt anhand ihrer id bereits gespeicherte Ereignisse, die nicht erneut gespeichert werden.
  • unmatched zählt gespeicherte Ereignisse ohne zugeordneten Kontakt. Gewählt wird der älteste Kontakt im Standardarbeitsbereich mit dieser E-Mail-Adresse, ersatzweise mit dieser Telefon- oder WhatsApp-Nummer. Ohne Treffer wartet das Ereignis. Der aktivierte Zuordnungsdienst läuft normalerweise alle zehn Minuten; Rückstau oder Fehler können die Zuordnung verzögern. Nach 30 Tagen seit Empfang löscht dieser Dienst weiterhin nicht zugeordnete Ereignisse. Ein Ereignis legt niemals einen Kontakt an.
  • Ereignisse eines Unterkontos verwenden wie dessen Nachrichten X-Oblic-On-Behalf-Of (siehe Unterkonten).
AblehnungcdUrsache
400UNKNOWN_EVENT_TYPEDer type des Ereignisses ist nicht bekannt
400PERSON_REQUIREDDas Ereignis enthält weder email noch phone
400INVALID_VALUEEine value ohne currency oder eine currency ohne Wert, ein negativer Wert, mehr als 14 Vor- oder vier Nachkommastellen oder ein Wert für customer.created
400INVALID_PROPERTIESEine für diesen Typ unzulässige Eigenschaft oder ein falsches Format
400INVALID_OCCURRED_AToccurredAt liegt mehr als fünf Minuten in der Zukunft oder mehr als 3650 Tage zurück
400das betroffene Feld, etwa EVENTS[0].IDevents fehlt, ist leer oder enthält mehr als 100 Einträge; alternativ fehlt ein Feld oder hat ein falsches Format
403INSUFFICIENT_SCOPEDer Schlüssel besitzt events:write nicht

Ablehnungen nennen das Feld oder die Arrayposition, etwa events[2].type, statt E-Mail-Adresse, Telefonnummer oder Eigenschaftswerte zu wiederholen. Unbekannte Eigenschaftsnamen können in der Erklärung erscheinen; verwenden Sie auch dort keine sensiblen Angaben. Die Formatprüfung erfolgt vor den typspezifischen Prüfungen; die Antwort nennt die in dieser Prüfphase gefundenen Probleme.


Eine Journey starten

Eine in Journeys angelegte Journey kann durch die Aktion eines Kontakts starten, wenn die Laufzeit für Ihren Arbeitsbereich aktiviert ist. Wählen Sie im Editor Tut etwas in Ihrem Shop und anschließend den Ereignistyp. Zur Eingrenzung geben Sie die vom Shop gesendeten Produktkennungen sowie den Mindestwert mit Währung an.

  • Einmal je Ereignis: Bezahlt ein Kontakt zwei Bestellungen, startet er die Journey zweimal. Ein erneut mit derselben id gesendetes Ereignis startet sie nur einmal.
  • Nur ein aktuelles Ereignis: Journeys starten, wenn das Ereignis innerhalb von 24 Stunden nach occurredAt mit Kontakt gespeichert oder später zugeordnet wird. Ältere Ereignisse, etwa nachgeladene historische Bestellungen, erscheinen in der Chronik und zählen für Segmente, starten aber keine Journey.
  • Produkte und Wert: Produkte werden mit den productIds einer Bestellung, eines Bezahlvorgangs oder Warenkorbs beziehungsweise der angesehenen productId abgeglichen. Der Wert muss den Mindestbetrag in dieser Währung erreichen. customer.created enthält beides nicht und wird dadurch nicht eingegrenzt.

Aus Shopify

Sind Shopify-Integration und Installationslink eingerichtet, verbinden Sie einen Shop unter Einstellungen → Integrationen → Shopify-Shop: Installieren Sie Oblic in Shopify und verbinden Sie den Shop mit Ihrer Organisation. Ist die Integration nicht verfügbar, bitten Sie zuerst Ihren Administrator um Einrichtung. Bestellungen werden dann zu den oben genannten Ereignissen und wie selbst gesendete Ereignisse anhand von E-Mail oder Telefonnummer zugeordnet. Kunden mit Einwilligung in Ihr E-Mail- oder SMS-Marketing werden mit dieser Einwilligung zu Kontakten.

Shopify-UrsprungResultierendes Ereignis
Eine aufgegebene, bezahlte, ausgeführte oder stornierte Bestellungorder.placed, order.paid, order.fulfilled, order.cancelled
Eine Erstattungorder.refunded für die bestellende Person, mit dem erstatteten Betrag
Ein Bezahlvorgang mit E-Mail-Adresse oder Telefonnummercheckout.started
Ein seit einer Stunde inaktiver Bezahlvorgang ohne Bestellungcart.abandoned, einmal je Bezahlvorgang
Ein für Ihr Marketing angemeldeter Kunde, der noch kein Kontakt istcustomer.created, wenn Oblic den Kontakt anlegt
  • Ereignisinhalt: Bestellwert in Shop-Währung, Bestellnummer, Artikelanzahl und Produkte anhand ihrer Shopify-Kennungen. Weitere Bestelldetails werden im Ereignis nicht gespeichert.
  • Angemeldete Kunden: Ein Kunde mit E-Mail- oder SMS-Marketing-Einwilligung in Shopify wird nach den Ereignisregeln unter Ihren Kontakten gesucht. Andernfalls entsteht im Standardarbeitsbereich ein Kontakt, benannt nach Adresse oder Nummer; dort wird die Einwilligung erfasst. Ohne Anmeldung wird kein Kontakt angelegt.
  • Abmeldung: Ein in Shopify abgemeldeter Kunde erhält keine E-Mails beziehungsweise keine SMS aus Kampagnen, Automatisierungen und Journeys mehr, bis er sich dort erneut anmeldet. Shopify hebt eine in Oblic erfolgte E-Mail-Abmeldung, etwa über einen Nachrichtenlink, niemals auf.
  • Trennen: Trennen Sie den Shop auf derselben Seite und deinstallieren Sie Oblic anschließend in Shopify. Beim Trennen bleiben Ereignisse erhalten. Shop und Ereignisse werden erst bei Verarbeitung von Shopifys späterer shop/redact-Anfrage gelöscht, nicht allein durch das Trennen.
  • Kundendatenschutz: Fordert Shopify die Löschung von Kundendaten, werden deren Ereignisse aus diesem Shop gelöscht. War die Einwilligung an einem Kontakt erfasst, werden die Organisationsinhaber in Oblic zur Kontaktlöschung benachrichtigt. Auch eine Datenauskunftsanfrage des Kunden wird den Inhabern in Oblic gemeldet.
War diese Seite hilfreich?