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 {id} – pozyskiwanie informacji o kliencie po przypisanym do niego numerze ID.
GET {email} – pozyskiwanie informacji o kliencie po przypisanym do niego adresie e-mail.
GET {phone} – pozyskiwanie informacji o kliencie po przypisanym do niego numerze telefonu.
GET {crmId} – pozyskiwanie informacji o kliencie 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	Opis
email*	string	adres e-mail klienta
phone*	string	numer telefonu klienta; ciąg znaków bez spacji
crmId*	string	numer CRM ID klienta
firstName	string	imię klienta
lastName	string	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	Opis
name*	string	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"
}

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