Klienci – metody API
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:
- DELETE – usuwanie danych klienta, z możliwością ich anonimizacji:
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 |
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 |
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"
}