Klienci - metody API - ExpertSender Help Center

Za pomocą API zautomatyzujesz dodawanie, pozyskiwanie i zmienianie danych dotyczących Twoich klientów. Służą do tego trzy metody HTTP:

POST – dodawanie informacji o nowym kliencie oraz aktualizacja danych istniejącego klienta.
GET – pozyskiwanie informacji o kliencie:
- {id} – po przypisanym do niego numerze ID.
- {email} – po przypisanym do niego adresie e-mail.
- {phone} – po przypisanym do niego numerze telefonu.
- {crmId} – po przypisanym do niego numerze CRM ID.
DELETE – usuwanie danych klienta, z możliwością ich anonimizacji:
- {id} – po przypisanym do niego numerze ID.
- {email} – po przypisanym do niego adresie e-mail.
- {phone} – po przypisanym do niego numerze telefonu.
- {crmId} – po przypisanym do niego numerze CRM ID.

Metoda POST – dodawanie informacji o kliencie

Jakie działania na danych możesz przeprowadzić z tą metodą?

Add – stworzenie klienta w platformie ExpertSender i dodanie zestawu danych o nim.
Update – aktualizacja zestawu danych klienta, który już znajduje się w platformie.
AddOrUpdate – stworzenie klienta w platformie ExpertSender lub aktualizacja jego danych, gdy są już obecne w platformie.

Metoda POST – zapytanie

Żeby wysłać zapytanie z użyciem tej metody, musi ono zawierać:

Adres serwera (endpoint): https://api.ecdp.app/customers
Parametry:

Parametr	Typ	Kategoria	Opis
x-api-key	string	header	twój klucz API, który znajdziesz w Ustawienia > API
mode	string	body	Add, Update, AddOrUpdate – wybierz jedno z działań, jakie chcesz przeprowadzić na danych:
matchBy	string	body	Email, PhoneNumber, CrmId, GUID, VisitorId; wybierz, według jakiej danej ma być identyfikowany klient, według informacji w Ustawienia > Klienci > Domyślne pole identyfikujące.

Pozostałe parametry, które możesz dodać do zapytania:

Parametr	Typ	Maksymalna liczba znaków	Opis
email*	string	320	adres e-mail klienta
phone*	string	20	numer telefonu klienta; ciąg znaków bez spacji
crmId*	string	128	numer CRM ID klienta
visitorId	string	38	uniklny numer przypisyway każdemu odwiedzjącemu Twoja stronę
firstName	string	256	imię klienta
lastName	string	256	nazwisko klienta
dateOfBirth	string($date-time)	–	data urodzenia klienta w formacie: 2023-07-25T12:35:54.712Z, gdzie T oddziela datę od czasu i oznacza format długiego czasu, zawierający sekundy, a Z oznacza czas UTC
gender	string	–	płeć klienta: Male, Female, NotSpecified
customAttributes			cechy klienta; obejmuje dodatkowy zestaw parametrów >>> zobacz tabelę poniżej
consentsData			dane dotyczące zgód; obejmuje dodatkowy zestaw parametrów >>> zobacz tabelę poniżej

Parametry customAttributes oraz consentsData posiadają jeszcze własne parametry, które pozwolą Ci na dodanie lub uzyskanie bardziej szczegółowych informacji.

Dla customAttributes (cechy klienta) są to:

Parametr	Typ	Maksymalna liczba znaków	Opis
name*	string	256	nazwa cechy klienta; parametr obowiązkowy, gdy chcesz dodać informację o cechach niestandardowych; minimalna ilość znaków: 1
value	string	–	wartość cechy klienta

Dla consentsData (dane dotyczące zgód) są to:

Parametr	Typ	Opis
consents		szczegółowe dane dotyczące zgód; obejmuje dodatkowy zestaw parametrów >>> zobacz tabelę poniżej
force	boolean	wskazuje, czy dla zgód oznaczonych jako „AwaitingConfirmation” ma być wysłany kolejny link potwierdzający, bez względu na to, czy był wysłany wcześniej
confirmationMessageId	integer($int32)	ID wiadomości potwierdzającej

Dla consents są to:

Parametr	Typ	Opis
id*	integer($int32)	ID pojedynczej zgody; parametr obowiązkowy, gdy chcesz dodać lub pozyskać informację o zgodzie
value*	string	status potwierdzenia zgody; możliwe wartości zgód to „False”, „AwaitingConfirmation”, „True”; parametr obowiązkowy, gdy chcesz dodać lub pozyskać informację o zgodzie. Gdy wybierzesz „AwaitingConfirmation”, zostanie wysłany do klienta e-mail potwierdzający udzielenie zgody.

Metoda POST – składnia zapytania

Poniżej widzisz przykładową składnię zapytania, za pomocą którego chcesz dodać (Add) klienta do bazy.

{
  "mode": "Add",
  "matchBy": "Email",
  "data": [
    {
      "email": "string",
      "phone": "string",
      "crmId": "string",
      "firstName": "string",
      "lastName": "string",
      "dateOfBirth": "2023-07-26T12:28:33.490Z",
      "gender": "Female",
      "customAttributes": [
        {
          "name": "string",
          "value": "string"
        }
      ],
      "consentsData": {
        "consents": [
          {
            "id": 0,
            "value": "False"
          }
        ],
        "force": true,
        "confirmationMessageId": 0
      }
    }
  ]
}

W przypadku aktualizacji danych klienta zmień parametr „mode” na „Update”. Jeśli nie wiesz, czy dany klient jest już w bazie, a chcesz dodać jego dane, zmień parametr „mode” na „AddOrUpdate”.

Kody odpowiedzi na zapytanie metodą POST

201: Created

Żądanie zostało utworzone.

400: Bad request

Żądanie nie zostało przetworzone. Powodem jest zwykle brakujący lub nieprawidłowy parametr, jak email, phone itp.
Przykładowa składania odpowiedzi:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string",
  "errors": [
    "string"
  ]
}

401: Unauthorized

W żądaniu brakowało klucza API lub prosisz o dostęp do informacji, do których nie masz uprawnień.

Przykładowa składania odpowiedzi:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Metoda GET – pozyskiwanie informacji o kliencie

Metoda GET służy do pozyskiwania informacji o kliencie z platformy ExpertSender. Na prawidłowo sformułowane zapytanie API otrzymasz odpowiedź o statusie ‘tylko do odczytu’

Masz do dyspozycji cztery rodzaje metody GET, które różnią się jedynie informacjami wymaganymi do wysłania zapytania.

Metoda GET{id} z użyciem numeru ID klienta

Metoda służy do pozyskania informacji o kliencie po przypisanym do niego numerze ID. Żeby wysłać zapytanie z użyciem tej metody, musi ono zawierać:

Adres serwera (endpoint): https://api.ecdp.app/customers/id/{id}
Parametry:

Parametr	Typ	Kategoria	Opis
x-api-key	string	header	klucz API, który znajdziesz w Ustawienia > API
id	string	path	numer ID klienta

Prawidłowe zapytanie API o klienta o numerze ID 12 będzie wyglądało następująco: https://api.ecdp.app/customers/id/12

Kody odpowiedzi na zapytanie metodą GET{id}

200: Success

Żądanie zostało utworzone.

Przykładowa składania odpowiedzi:

{
  "status": 0,
  "data": {
    "email": "string",
    "phone": "string",
    "crmId": "string",
    "firstName": "string",
    "lastName": "string",
    "dateOfBirth": "2023-07-25T13:58:16.339Z",
    "gender": "Female",
    "rfmSegment": "string",
    "totalSpent": 0,
    "totalOrders": 0,
    "totalOrderReturns": 0,
    "avgOrder": 0,
    "avgPricePoint": 0,
    "lastOrder": "2023-07-25T13:58:16.339Z",
    "avgTimeBetweenOrdersInDays": 0,
    "currencySymbol": "string",
    "customAttributes": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "consentsData": {
      "consents": [
        {
          "id": 0,
          "value": "False"
        }
      ]
    }
  }
}

401: Unauthorized

W żądaniu brakowało klucza API lub prosisz o dostęp do informacji, do których nie masz uprawnień. Przykładowa składania odpowiedzi:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

404: Not found

Na serwerze nie ma danych, których szukasz.

Przykładowa składania odpowiedzi:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Metoda GET{email} z użyciem adresu e-mail klienta

Metoda służy do pozyskania informacji o kliencie po przypisanym do niego adresie e-mail. Żeby wysłać zapytanie z użyciem tej metody, musi ono zawierać:

Adres serwera (endpoint): https://api.ecdp.app/customers/email/{email}
Parametry:

Parametr	Typ	Kategoria	Opis
x-api-key	string	header	klucz API, który znajdziesz w Ustawienia > API
email	string	path	adres e-mail klienta

Wzór zapytania API o klienta o adresie e-mail adam@poczta.pl będzie wyglądało następująco: https://api.ecdp.app/customers/email/adam@poczta.pl

Kody odpowiedzi na zapytanie metodą GET{email}

200: Success

Zapytanie zostało przetworzone, serwer zwrócił odpowiedź.

Przykładowa składania odpowiedzi:

{
  "status": 0,
  "data": {
    "email": "string",
    "phone": "string",
    "crmId": "string",
    "firstName": "string",
    "lastName": "string",
    "dateOfBirth": "2023-07-25T14:02:39.444Z",
    "gender": "Female",
    "rfmSegment": "string",
    "totalSpent": 0,
    "totalOrders": 0,
    "totalOrderReturns": 0,
    "avgOrder": 0,
    "avgPricePoint": 0,
    "lastOrder": "2023-07-25T14:02:39.444Z",
    "avgTimeBetweenOrdersInDays": 0,
    "currencySymbol": "string",
    "customAttributes": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "consentsData": {
      "consents": [
        {
          "id": 0,
          "value": "False"
        }
      ]
}

401: Unauthorized

W żądaniu brakowało klucza API lub prosisz o dostęp do informacji, do których nie masz uprawnień. Przykładowa składania odpowiedzi:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

404: Not found

Na serwerze nie ma danych, których szukasz.

Przykładowa składania odpowiedzi:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Metoda GET{phone} z użyciem numeru telefonu klienta

Metoda służy do pozyskania informacji o kliencie po przypisanym do niego numerze telefonu. Żeby wysłać zapytanie z użyciem tej metody, musi ono zawierać:

Adres serwera (endpoint): https://api.ecdp.app/customers/phone/{phone}
Parametry:

Parametr	Typ	Kategoria	Opis
x-api-key	string	header	klucz API, który znajdziesz w Ustawienia > API
phone	string	path	numer telefonu klienta

Prawidłowe zapytanie API o klienta o numerze telefonu 123 456 789 będzie następujące: https://api.ecdp.app/customers/phone/123456789

Kody odpowiedzi na zapytanie metodą GET{phone}

200: Success

Zapytanie zostało przetworzone, serwer zwrócił odpowiedź.

Przykładowa składania odpowiedzi:


{
  "status": 0,
  "data": {
    "email": "string",
    "phone": "string",
    "crmId": "string",
    "firstName": "string",
    "lastName": "string",
    "dateOfBirth": "2023-07-26T07:02:46.313Z",
    "gender": "Female",
    "rfmSegment": "string",
    "totalSpent": 0,
    "totalOrders": 0,
    "totalOrderReturns": 0,
    "avgOrder": 0,
    "avgPricePoint": 0,
    "lastOrder": "2023-07-26T07:02:46.313Z",
    "avgTimeBetweenOrdersInDays": 0,
    "currencySymbol": "string",
    "customAttributes": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "consentsData": {
      "consents": [
        {
          "id": 0,
          "value": "False"
        }
      ]
    }
  }
}

401: Unauthorized

W żądaniu brakowało klucza API lub prosisz o dostęp do informacji, do których nie masz uprawnień. Przykładowa składania odpowiedzi:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

404: Not found

Na serwerze nie ma danych, których szukasz.

Przykładowa składania odpowiedzi:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Metoda GET{crmId} z użyciem numeru CRM ID klienta

Metoda służy do pozyskania informacji o kliencie po przypisanym do niego numerze ID w Twoim systemie CRM. Żeby wysłać zapytanie z użyciem tej metody, musi ono zawierać:

Adres serwera (endpoint): https://api.ecdp.app/customers/crmId/{crmId}
Parametry:

Parametr	Typ	Kategoria	Opis
x-api-key	string	header	klucz API, który znajdziesz w Ustawienia > API
crmId	string	path	numer identyfikacyjny klienta, który ma przypisany w Twoim systemie CRM

Zapytanie API o klienta o numerze CRM ID 57 będzie wyglądało tak: https://api.ecdp.app/customers/crmId/57

Kody odpowiedzi na zapytanie metodą GET{crmId}

200: Success

Zapytanie zostało przetworzone, serwer zwrócił odpowiedź.

Przykładowa składania odpowiedzi:

{
  "status": 0,
  "data": {
    "email": "string",
    "phone": "string",
    "crmId": "string",
    "firstName": "string",
    "lastName": "string",
    "dateOfBirth": "2023-07-26T07:07:53.146Z",
    "gender": "Female",
    "rfmSegment": "string",
    "totalSpent": 0,
    "totalOrders": 0,
    "totalOrderReturns": 0,
    "avgOrder": 0,
    "avgPricePoint": 0,
    "lastOrder": "2023-07-26T07:07:53.146Z",
    "avgTimeBetweenOrdersInDays": 0,
    "currencySymbol": "string",
    "customAttributes": [
      {
        "name": "string",
        "value": "string"
      }
    ],
    "consentsData": {
      "consents": [
        {
          "id": 0,
          "value": "False"
        }
      ]
    }
  }
}

401: Unauthorized

W żądaniu brakowało klucza API lub prosisz o dostęp do informacji, do których nie masz uprawnień. Przykładowa składania odpowiedzi:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

404: Not found

Na serwerze nie ma danych, których szukasz.

Przykładowa składania odpowiedzi:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "detail": "string",
  "instance": "string"
}

Metoda DELETE – usuwanie danych klienta

Metoda DELETE służy do usuwania informacji o kliencie z platformy ExpertSender CDP.

Masz do dyspozycji cztery rodzaje metody DELETE, które różnią się jedynie informacjami wymaganymi do wysłania zapytania.

Każda metoda zawiera parametr „withAnonymization” umożliwiający anonimizację danych usuwanego klienta. Domyślnie parametr ten jest ustawiony na 'false’.

Metoda DELETE{id} z użyciem numeru ID klienta

Metoda służy do usunięcia informacji o kliencie z użyciem przypisanego do niego numeru ID. Żeby wysłać zapytanie z użyciem tej metody, musi ono zawierać:

Adres serwera (endpoint): https://api.ecdp.app/customers/id/{id}
Parametry:

Parametr	Typ	Kategoria	Opis
x-api-key	string	header	klucz API, który znajdziesz w Ustawienia > API
id	integer($int32)	path	numer ID klienta

Kody odpowiedzi na zapytanie metodą DELETE{id}

200: Success

Przykładowa składania odpowiedzi:

401: Unauthorized

W żądaniu brakowało klucza API lub prosisz o dostęp do informacji, do których nie masz uprawnień. Przykładowa składania odpowiedzi:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "substatus": "CustomerInvalidModelState",
  "detail": "string",
  "instance": "string"
}

404: Not found

Na serwerze nie ma danych, których szukasz. Przykładowa składania odpowiedzi:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "substatus": "CustomerInvalidModelState",
  "detail": "string",
  "instance": "string"
}

Metoda DELETE{email} z użyciem adresu e-mail klienta

Metoda służy do usunięcia informacji o kliencie z użyciem przypisanego do niego adresu e-mail. Żeby wysłać zapytanie z użyciem tej metody, musi ono zawierać:

Adres serwera (endpoint): https://api.ecdp.app/customers/email/{email}
Parametry:

Parametr	Typ	Kategoria	Opis
x-api-key	string	header	klucz API, który znajdziesz w Ustawienia > API
email	string	path	adres e-mail klienta

Kody odpowiedzi na zapytanie metodą DELETE{email}

200: Success

Przykładowa składania odpowiedzi:

401: Unauthorized

W żądaniu brakowało klucza API lub prosisz o dostęp do informacji, do których nie masz uprawnień. Przykładowa składania odpowiedzi:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "substatus": "CustomerInvalidModelState",
  "detail": "string",
  "instance": "string"
}

404: Not found

Na serwerze nie ma danych, których szukasz. Przykładowa składania odpowiedzi:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "substatus": "CustomerInvalidModelState",
  "detail": "string",
  "instance": "string"
}

Metoda DELETE{phone} z użyciem numeru telefonu klienta

Metoda służy do usunięcia informacji o kliencie z użyciem przypisanego do niego adresu e-mail. Żeby wysłać zapytanie z użyciem tej metody, musi ono zawierać:

Adres serwera (endpoint): https://api.ecdp.app/customers/phone/{phone}
Parametry:

Parametr	Typ	Kategoria	Opis
x-api-key	string	header	klucz API, który znajdziesz w Ustawienia > API
phone	string	path	numer telefonu klienta

Kody odpowiedzi na zapytanie metodą DELETE{phone}

200: Success

Przykładowa składania odpowiedzi:

401: Unauthorized

W żądaniu brakowało klucza API lub prosisz o dostęp do in

{
  "type": "string",
  "title": "string",
  "status": 0,
  "substatus": "CustomerInvalidModelState",
  "detail": "string",
  "instance": "string"
}

404: Not found

Na serwerze nie ma danych, których szukasz. Przykładowa składania odpowiedzi:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "substatus": "CustomerInvalidModelState",
  "detail": "string",
  "instance": "string"
}

Metoda DELETE{crmId} z użyciem numeru CRM ID klienta

Metoda służy do usunięcia informacji o kliencie z użyciem przypisanego do niego numeru CRM ID. Żeby wysłać zapytanie z użyciem tej metody, musi ono zawierać:

Adres serwera (endpoint): https://api.ecdp.app/customers/crmid/{crmId}
Parametry:

Parametr	Typ	Kategoria	Opis
x-api-key	string	header	klucz API, który znajdziesz w Ustawienia > APIcrm
crmId	string	path	numer CRM ID klienta

Kody odpowiedzi na zapytanie metodą DELETE{crmId}

200: Success

Przykładowa składania odpowiedzi:

401: Unauthorized

W żądaniu brakowało klucza API lub prosisz o dostęp do informacji, do których nie masz uprawnień. Przykładowa składania odpowiedzi:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "substatus": "CustomerInvalidModelState",
  "detail": "string",
  "instance": "string"
}

404: Not found

Na serwerze nie ma danych, których szukasz. Przykładowa składania odpowiedzi:

{
  "type": "string",
  "title": "string",
  "status": 0,
  "substatus": "CustomerInvalidModelState",
  "detail": "string",
  "instance": "string"
}

Klienci – metody API

Metoda POST – dodawanie informacji o kliencie

Metoda POST – zapytanie

Metoda POST – składnia zapytania

Kody odpowiedzi na zapytanie metodą POST

201: Created

400: Bad request

401: Unauthorized

Metoda GET – pozyskiwanie informacji o kliencie

Metoda GET{id} z użyciem numeru ID klienta

Kody odpowiedzi na zapytanie metodą GET{id}

200: Success

401: Unauthorized

404: Not found

Metoda GET{email} z użyciem adresu e-mail klienta

Kody odpowiedzi na zapytanie metodą GET{email}

200: Success

401: Unauthorized

404: Not found

Metoda GET{phone} z użyciem numeru telefonu klienta

Kody odpowiedzi na zapytanie metodą GET{phone}

200: Success

401: Unauthorized

404: Not found

Metoda GET{crmId} z użyciem numeru CRM ID klienta

Kody odpowiedzi na zapytanie metodą GET{crmId}

200: Success

401: Unauthorized

404: Not found

Metoda DELETE – usuwanie danych klienta

Metoda DELETE{id} z użyciem numeru ID klienta

Kody odpowiedzi na zapytanie metodą DELETE{id}

200: Success

401: Unauthorized

404: Not found

Metoda DELETE{email} z użyciem adresu e-mail klienta

Kody odpowiedzi na zapytanie metodą DELETE{email}

200: Success

401: Unauthorized

404: Not found

Metoda DELETE{phone} z użyciem numeru telefonu klienta

Kody odpowiedzi na zapytanie metodą DELETE{phone}

200: Success

401: Unauthorized

404: Not found

Metoda DELETE{crmId} z użyciem numeru CRM ID klienta

Kody odpowiedzi na zapytanie metodą DELETE{crmId}

200: Success

401: Unauthorized

404: Not found