Zdarzenia niestandardowe w scenariuszach - ExpertSender Centrum pomocy

API zdarzeń niestandardowych pozwala wywoływać zdarzenia scenariuszowe dla pojedynczych klientów lub całych segmentów.

POST – wywołanie zdarzenia dla pojedynczego klienta

Ta metoda wywołuje zdarzenie dla pojedynczego klienta, identyfikowanego na podstawie ID, adresu e-mail, numeru telefonu lub CRM ID.

Endpoint

Endpoint, czyli adres serwera dla tego zapytania to https://api.ecdp.app/scenariocustomevents

Parametry zapytania

Parametr	Lokalizacja	Typ	Wymagany	Opis	Dozwolone wartości / Uwagi
x-api-key	header	string	tak	Twój klucz API z Ustawienia > API.	–
customEventId	body	integer($int32)	tak	Unikalny identyfikator zdarzenia niestandardowego do wywołania.	Musi być prawidłowym ID zdarzenia skonfigurowanego w Twojej jednostce biznesowej w Automatyzacja > Scenariusze > zakładka Zdarzenia.
customerId	body	string	nie	Wewnętrzny identyfikator klienta w ECDP.	Wymagany co najmniej jeden identyfikator klienta.
customerEmail	body	string	nie	Adres e-mail klienta.	Maks. 320 znaków.
customerEmailMd5	body	string	nie	Adres e-mail klienta zahashowany algorytmem MD5.	Maks. 32 znaki.
customerEmailSha256	body	string	nie	Adres e-mail klienta zahashowany algorytmem SHA-256.	Maks. 64 znaki.
customerPhone	body	string	nie	Numer telefonu klienta.	Maks. 20 znaków..
customerCrmId	body	string	nie	Identyfikator CRM klienta z Twojego systemu zewnętrznego.	Maks. 128 znaków.
dataFields	body	array	nie	Dodatkowe dane opisujące zdarzenie niestandardowe.	Zobacz parametry data fields

Data fields

Tablica dataFields pozwala przekazać dodatkowe dane kontekstowe wraz ze zdarzeniem niestandardowym. Każde pole w tablicy zawiera:

Parametr	Typ	Wymagany	Opis	Dozwolone wartości
name	string	tak	Nazwa pola danych.	Dowolny prawidłowy identyfikator tekstowy.
type	string	tak	Typ danych wartości pola.	String, Text, Number, Money, Date, DateTime, Boolean, URL
value	string	tak	Wartość pola danych.	Musi odpowiadać formatowi określonego typu.

Kody odpowiedzi

Kod	Status	Opis
201	Created	Zdarzenie niestandardowe zostało pomyślnie wywołane.
400	Bad Request	Żądanie nie zostało przetworzone z powodu brakujących lub nieprawidłowych parametrów.
401	Unauthorized	Brak klucza API lub klucz jest nieprawidłowy.
404	Not Found	Nie znaleziono określonego ID zdarzenia niestandardowego lub klienta.
500	Internal Server Error	Wystąpił nieoczekiwany błąd serwera.

Przykładowe zapytania i odpowiedzi

Wywołanie zdarzenia dla klienta z wybranym adresem mailowym

{
  "customEventId": 42,
  "customerEmail": "jan.kowalski@poczta.pl"
}

Odpowiedź:

HTTP/1.1 201 Created

Wywołanie zdarzenia dla klienta spełniającego wybrane kryteria:

{
  "customEventId": 42,
  "customerEmail": "anna.nowak@poczta.pl",
  "customerCrmId": "CRM-2024-00158",
  "dataFields": [
    {
      "name": "Kategoria produktu",
      "type": "String",
      "value": "Elektronika"
    },
    {
      "name": "Cena",
      "type": "Money",
      "value": "299.99"
    },
    {
      "name": "Data zakupu",
      "type": "DateTime",
      "value": "2024-12-15T14:30:00Z"
    }
  ]
}

Odpowiedź:

HTTP/1.1 201 Created

POST – wywołanie zdarzenia dla segmentów

Ta metoda wywołuje wskazane zdarzenie dla wszystkich klientów w określonym segmencie.

Endpoint

Endpoint, czyli adres serwera dla tego zapytania to https://api.ecdp.app/scenariocustomevents/withsegments

Parametry zapytania#

Parametr	Lokalizacja	Typ	Wymagany	Opis	Dozwolone wartości / Uwagi
x-api-key	header	string	tak	Twój klucz API z Ustawienia > API.	–
customEventId	body	integer($int32)	tak	Unikalny identyfikator zdarzenia niestandardowego do wywołania.	Musi być prawidłowym ID zdarzenia skonfigurowanego w Twojej jednostce biznesowej.
segments	body	array of integers	tak	Lista identyfikatorów segmentów do uwzględnienia.	Wymagany co najmniej jeden ID segmentu.
dataFields	body	array	nie	Dodatkowe dane opisujące zdarzenie niestandardowe.	Tablica obiektów pól danych. Szczegóły w sekcji Data fields powyżej.

Kody odpowiedzi

Kod	Status	Opis
201	Created	Zdarzenie niestandardowe zostało wywołane dla wszystkich klientów w określonych segmentach.
400	Bad Request	Żądanie nie zostało przetworzone z powodu brakujących lub nieprawidłowych parametrów.
401	Unauthorized	Brak klucza API lub klucz jest nieprawidłowy.
404	Not Found	Nie znaleziono określonego ID zdarzenia niestandardowego lub jednego z segmentów.
500	Internal Server Error	Wystąpił nieoczekiwany błąd serwera.

Przykładowe zapytania i odpowiedzi

Wywołanie zdarzenia dla wybranego segmentu klientów

{
  "customEventId": 42,
  "segments": [15]
}

Odpowiedź:

HTTP/1.1 201 Created

Wywołanie zdarzenia dla klientów spełniających wybrane warunki w danym segmencie

{
  "customEventId": 42,
  "segments": [1, 5, 15],
  "dataFields": [
    {
      "name": "Nazwa kampanii",
      "type": "String",
      "value": "Zimowa wyprzedaż 2024"
    },
    {
      "name": "Rabat proc.",
      "type": "Number",
      "value": "25"
    },
    {
      "name": "Rabat ważny do",
      "type": "Date",
      "value": "2024-12-31"
    }
  ]
}

Odpowiedź:

HTTP/1.1 201 Created

Walidacja i zasady działania#

Dla endpointu pojedynczego klienta wymagany jest co najmniej jeden identyfikator klienta (customerId, customerEmail, customerEmailMd5, customerEmailSha256, customerPhone lub customerCrmId).
Wartość customEventId musi wskazywać na istniejące zdarzenie niestandardowe skonfigurowane w Twojej jednostce biznesowej.
W przypadku wywoływania dla segmentów wymagany jest co najmniej jeden prawidłowy ID segmentu.
Tablica dataFields jest opcjonalna – jeśli ją pominiesz, zdarzenie niestandardowe zostanie wywołane bez dodatkowych danych kontekstowych.
Przetwarzanie zdarzeń dla segmentów odbywa się asynchronicznie – duże segmenty mogą wymagać więcej czasu na pełne przetworzenie.

Dokumentacja referencyjna#

Swagger – sekcja Scenario custom events https://api.ecdp.app/swagger/index.html