Zamówienia – metody API
API umożliwi Ci automatyzację działań związanych z zamówieniami składanymi przez Twoich klientów. Udostępniamy trzy metody HTTP:
- POST – dodawanie nowego zamówienia lub aktualizacja danych o zamówieniu.
- GET – pozyskiwanie informacji o zamówieniu.
- PUT – zmiana statusu zamówienia.
- DELETE – usuwanie zamówienia.
Metoda POST – dodawanie informacji o zamówieniu
Działania, jakie przeprowadzisz tą metodą, to dodawanie danych o nowych zamówieniach oraz aktualizacja danych już złożonych zamówień. Służą do tego trzy tryby (modes):
- Add – dodanie zamówienia w platformie ExpertSender.
- AddOrReplace – dodanie nowego zamówienia od platformy lub wymiana jego danych, jeśli zamówienie już znajduje się w platformie.
- Replace – zmiana zestawu danych w zamówieniu.
Metoda POST – zapytanie
Żeby wysłać zapytanie z użyciem tej metody, potrzebujesz następujących informacji:
- Adres serwera (endpoint): https://api.ecdp.app/orders
- Parametry:
Parametr | Typ | Kategoria | Opis |
x-api-key* | string | header | klucz API |
id* | string | body | numer ID zamówienia, minimalna ilość znaków: 1 |
date* | string($date-time) | body | data złożenia zamówienia |
totalValue* | number($double) | body | całkowita wartość zamówienia, minimalna ilość znaków: 0 |
customer* | body | dane klienta; obejmuje dodatkowy zestaw parametrów >>> zobacz tabele poniżej | |
products* | body | dane produktu; obejmuje dodatkowy zestaw parametrów >>> zobacz tabele poniżej |
Parametry customer oraz products, oraz orderAttributes posiadają jeszcze własne parametry, które pozwolą Ci na dodanie lub uzyskanie bardziej szczegółowych informacji na temat zamówień. Parametry oznaczone gwiazdką muszą znaleźć się w zapytaniu.
Dla customer są to:
Parametr | Typ | Opis |
string | adres e-mail klienta, który złożył zamówienie | |
phone | string | numer telefonu klienta, który złożył zamówienie |
crmId | string | numer ID CRM klienta, który złożył zamówienie |
Dla products są to:
Parametr | Typ | Opis |
id* | string | numer ID zakupionego produktu; minimalna ilość znaków: 1 |
name* | string | nazwa produktu; minimalna ilość znaków: 1 |
price* | number($double) | cena produktu; minimalna ilość znaków: 0 |
quantity* | integer($int32) | ilość zakupionego produktu; minimalna ilość znaków: 1, maksymalna ilość znaków: 2147483647 |
returned | integer($int32) | ilość zwróconych produktów; minimalna ilość znaków: 0, maksymalna ilość znaków: 2147483647 |
url | string | adres URL zakupionego produktu |
imageUrl | string | adres URL obrazka zakupionego produktu |
category | string | kategoria zakupionego produktu |
productAttributes | Cechy produktu; obejmuje dodatkowy zestaw parametrów >>> zobacz tabelę poniżej |
Dla productAttributes są to:
Parametr | Typ | Opis |
name* | string | nazwa cechy produktu; minimalna ilość znaków: 1 |
value | string | wartość cechy produktu |
Pozostałe parametry, które możesz umieścić w zapytaniu:
Parametr | Typ | Opis |
timeZone | string | strefa czasowa zamówienia |
websiteId | integer($int32) | numer ID strony sklepu, w którym złożono zamówienie |
status | string | status zamówienia: placed, paid, completed, canceled |
currency | string | waluta, w której złożono zamówienie, minimalna ilość znaków: 3, maksymalna ilość znaków: 3 |
returnsValue | number($double) | wartość zwróconych produktów, minimalna ilość znaków: 0 |
orderAttributes | cechy zamówienia; obejmuje dodatkowy zestaw parametrów >>> zobacz tabele poniżej |
Parametry orderAttributes posiadają jeszcze własne parametry, które pozwolą Ci na dodanie lub uzyskanie bardziej szczegółowych informacji na temat zamówień. Parametry oznaczone gwiazdką muszą znaleźć się w zapytaniu:
Parametr | Typ | Opis |
name* | string | nazwa cechy zamówienia; minimalna ilość znaków: 1 |
value | string | wartość cechy zamówienia |
Składnia zapytania dla metody POST
Poniżej widzisz przykładową składnię zapytania, za pomocą którego dodasz (mode: Add) szczegóły zamówienia do ExpertSender.
"mode": "Add",
"data": [
{
"id": "string",
"date": "2024-07-24T10:17:16.042Z",
"timeZone": "string",
"websiteId": 0,
"status": "string",
"currency": "str",
"totalValue": 0,
"returnsValue": 0,
"customer": {
"email": "string",
"phone": "string",
"crmId": "string"
},
"products": [
{
"id": "string",
"name": "string",
"price": 0,
"quantity": 2147483647,
"returned": 2147483647,
"url": "string",
"imageUrl": "string",
"category": "string",
"productAttributes": [
{
"name": "string",
"value": "string"
}
]
}
],
"orderAttributes": [
{
"name": "string",
"value": "string"
}
]
}
]
}
Jeśli nie wiesz, czy zamówienie zostało zarejestrowane w bazie, a chcesz dodać jego dane, zmień parametr „mode” na „AddOrReplace”.
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.
Przykładowa składnia odpowiedzi:
{
"type": "string",
"title": "string",
"status": 0,
"substatus": "CustomerInvalidModelState",
"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ładnia odpowiedzi:
{
"type": "string",
"title": "string",
"status": 0,
"substatus": "CustomerInvalidModelState",
"detail": "string",
"instance": "string"
}
Metoda GET – pozyskiwanie informacji o zamówieniu
Metoda GET służy do pozyskiwania informacji z platformy ExpertSender o zamówieniu złożonym przez klienta. Na prawidłowe zapytanie metodą GET otrzymasz następującą odpowiedź o statusie ‘tylko do odczytu’.
Metoda GET – zapytanie
Żeby wysłać zapytanie z użyciem tej metody, potrzebujesz następujących informacji:
- Adres serwera (endpoint): https://api.ecdp.app/orders/{id}
- Parametry:
Parametr | Typ | Kategoria | Opis |
x-api-key | string | header | twój klucz API, który znajdziesz w Ustawienia > API |
id | string | path | numer ID zamówienia |
Kody odpowiedzi na zapytanie metodą GET{id}
200: Success
Zapytanie zostało przetworzone, serwer zwrócił odpowiedź.
Przykładowa składnia odpowiedzi:
{
"status": 0,
"data": {
"id": "string",
"date": "2024-07-24T10:23:15.493Z",
"timeZone": "string",
"websiteId": 0,
"status": "string",
"currency": "str",
"totalValue": 0,
"returnsValue": 0,
"customer": {
"id": 0,
"email": "string",
"phone": "string",
"crmId": "string"
},
"products": [
{
"id": "string",
"name": "string",
"price": 0,
"quantity": 2147483647,
"returned": 2147483647,
"url": "string",
"imageUrl": "string",
"category": "string",
"productAttributes": [
{
"name": "string",
"value": "string"
}
]
}
],
"orderAttributes": [
{
"name": "string",
"value": "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ładnia 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 PUT – zmiana statusu zamówienia
Metoda PUT służy do zmiany statusu zamówienia zarejestrowanego w platformie ExpertSender CDP. Na prawidłowe zapytanie metodą PUT otrzymasz odpowiedź o statusie ‘tylko do odczytu’.
Metoda PUT – zapytanie
Żeby wysłać zapytanie z użyciem tej metody, musi ono zawierać:
- Adres serwera (endpoint): https://api.ecdp.app/orders/status
- Parametry:
Parametr | Typ | Kategoria | Opis |
x-api-key | string | header | klucz API, który znajdziesz w Ustawienia > API |
orderId* | string | body | Numer ID zamówienia; minimalna ilość znaków: 1 |
orderStatus* | string | body | status zamówienia; minimalna ilość znaków: 1 |
Składnia zapytania dla metody PUT
Poniżej widzisz przykładową składnię zapytania, za pomocą którego zmienisz status zamówienia.
{
"orderId": "string",
"orderStatus": "string"
}
Kody odpowiedzi na zapytanie metodą PUT
200: Success
Zapytanie zostało przetworzone, serwer zwrócił odpowiedź.
400: Bad request
Żądanie nie zostało przetworzone. Powodem jest zwykle brakujący lub nieprawidłowy parametr. Przykładowa składnia odpowiedzi:
{
"type": "string",
"title": "string",
"status": 0,
"substatus": "CustomerInvalidModelState",
"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,
"substatus": "CustomerInvalidModelState",
"detail": "string",
"instance": "string"
}
Metoda DELETE – zmiana statusu zamówienia na IsDeleted
Metoda PUT służy do zmiany statusu zamówienia zarejestrowanego w platformie ExpertSender na Usunięty (IsDeleted).
Na prawidłowe zapytanie metodą PUT otrzymasz odpowiedź o statusie ‘tylko do odczytu’.
Metoda DELETE – zapytanie
Żeby wysłać zapytanie z użyciem tej metody, musi ono zawierać:
- Adres serwera (endpoint): https://api.ecdp.app/orders/{id}
- Parametry
Parametr | Typ | Kategoria | Opis |
x-api-key | string | header | twój klucz API, który znajdziesz w Ustawienia > API |
orderId | string | path | numer ID zamówienia |
Prawidłowe zapytanie API o zmianę statusu zamówienia o numerze 12 na Usunięty wygląda następująco: https://client.ecdp.app/orders/{12}
Kody odpowiedzi na zapytanie metodą DELETE{id}
200: Success
Zapytanie zostało przetworzone, serwer zwrócił odpowiedź.
Przykładowa składnia odpowiedzi:
Example Value
Schema
{
"status": 0,
"data": {
"id": "string",
"date": "2024-07-24T10:26:09.455Z",
"timeZone": "string",
"websiteId": 0,
"status": "string",
"currency": "str",
"totalValue": 0,
"returnsValue": 0,
"customer": {
"id": 0,
"email": "string",
"phone": "string",
"crmId": "string"
},
"products": [
{
"id": "string",
"name": "string",
"price": 0,
"quantity": 2147483647,
"returned": 2147483647,
"url": "string",
"imageUrl": "string",
"category": "string",
"productAttributes": [
{
"name": "string",
"value": "string"
}
]
}
],
"orderAttributes": [
{
"name": "string",
"value": "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ładnia 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"
}