Przejdź do treści

Klienci – metody API

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

  1. POST – dodawanie informacji o nowym kliencie oraz aktualizacja danych istniejącego klienta.
  2. 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.
  3. 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ć:

  1. Adres serwera (endpoint): https://api.ecdp.app/customers
  2. Parametry:
ParametrTypKategoriaOpis
x-api-keystringheadertwój klucz API, który znajdziesz w Ustawienia > API
modestringbodyAdd, Update, AddOrUpdate – wybierz jedno z działań, jakie chcesz przeprowadzić na danych:
matchBystringbodyEmail, 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:

ParametrTypOpis
email*stringadres e-mail klienta
phone*stringnumer telefonu klienta;  ciąg znaków bez spacji
crmId*stringnumer CRM ID klienta
firstNamestringimię klienta
lastNamestringnazwisko klienta
dateOfBirthstring($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
genderstringpł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:

ParametrTypOpis
name*stringnazwa cechy klienta; parametr obowiązkowy, gdy chcesz dodać informację o cechach niestandardowych; minimalna ilość znaków: 1
valuestringwartość cechy klienta

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

ParametrTypOpis
consentsszczegółowe dane dotyczące zgód; obejmuje dodatkowy zestaw parametrów >>> zobacz tabelę poniżej
forcebooleanwskazuje, 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
confirmationMessageIdinteger($int32)ID wiadomości potwierdzającej

Dla consents są to:

ParametrTypOpis
id*integer($int32)ID pojedynczej zgody; parametr obowiązkowy, gdy chcesz dodać lub pozyskać informację o zgodzie
value*stringstatus 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ć:

  1. Adres serwera (endpoint): https://api.ecdp.app/customers/id/{id}
  2. Parametry:
ParametrTypKategoriaOpis
x-api-keystringheaderklucz API, który znajdziesz w Ustawienia > API
idstringpathnumer 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ć:

  1. Adres serwera (endpoint): https://api.ecdp.app/customers/email/{email}
  2. Parametry:
ParametrTypKategoriaOpis
x-api-keystringheaderklucz API, który znajdziesz w Ustawienia > API
emailstringpathadres 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ć:

  1. Adres serwera (endpoint): https://api.ecdp.app/customers/phone/{phone}
  2. Parametry:
ParametrTypKategoriaOpis
x-api-keystringheaderklucz API, który znajdziesz w Ustawienia > API
phonestringpathnumer 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ć:

  1. Adres serwera (endpoint): https://api.ecdp.app/customers/crmId/{crmId}
  2. Parametry:
ParametrTypKategoriaOpis
x-api-keystringheaderklucz API, który znajdziesz w Ustawienia > API
crmIdstringpathnumer 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ć:

  1. Adres serwera (endpoint): https://api.ecdp.app/customers/id/{id}
  2. Parametry:
ParametrTypKategoriaOpis
x-api-keystringheaderklucz API, który znajdziesz w Ustawienia > API
idinteger($int32)pathnumer 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ć:

  1. Adres serwera (endpoint): https://api.ecdp.app/customers/email/{email}
  2. Parametry:
ParametrTypKategoriaOpis
x-api-keystringheaderklucz API, który znajdziesz w Ustawienia > API
emailstringpathadres 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ć:

  1. Adres serwera (endpoint): https://api.ecdp.app/customers/phone/{phone}
  2. Parametry:
ParametrTypKategoriaOpis
x-api-keystringheaderklucz API, który znajdziesz w Ustawienia > API
phonestringpathnumer 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ć:

  1. Adres serwera (endpoint): https://api.ecdp.app/customers/crmid/{crmId}
  2. Parametry:
ParametrTypKategoriaOpis
x-api-keystringheaderklucz API, który znajdziesz w Ustawienia > APIcrm
crmIdstringpathnumer 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"
}
Na tej stronie
Do góry