Zamówienia
Metody HTTP do obsługi zamówień pozwalają platformom e-commerce synchronizować dane o zamówieniach z ECDP. Dzięki temu historia zakupów klientów jest zawsze aktualna, co wspiera analitykę, segmentację, analizę RFM i spersonalizowane scenariusze marketingowe.
POST /orders – dodawanie i aktualizacja zamówień
Metoda POST /orders tworzy nowe zamówienia lub aktualizuje istniejące dane. Obsługuje trzy tryby operacji: Add (tworzenie nowego), AddOrReplace (tworzenie nowego lub aktualizacja istniejącego) oraz Replace (aktualizacja istniejącego).
Endpoint#
Endpoint, czyli adres serwera dla tego zapytania to https://api.ecdp.app /orders
Parametry zapytania
| Parametr | Lokalizacja | Typ | Wymagany | Opis | Dozwolone wartości / Uwagi |
| x-api-key | header | string | tak | klucz uwierzytelniający API. | Pobierz w Ustawienia > API. |
| Content-Type | header | string | tak | typ zawartości żądania. | application/json. |
| mode | body | string | tak | tryb operacji. | Add, AddOrReplace, Replace. |
| id | body | string | tak | unikalny identyfikator zamówienia. | Maks. 128 znaków. |
| date | body | string ($date-time) | tak | data i czas złożenia zamówienia. | Format: YYYY-MM-DDTHH:mm:ss.sssZ. |
| timeZone | body | string | nie | strefa czasowa dla daty zamówienia. | Zobacz Obsługiwane strefy czasowe. Domyślnie: strefa czasowa jednostki biznesowej. |
| websiteId | body | integer($int32) | nie | identyfikator strony internetowej, na której złożono zamówienie. | Wartość całkowita. |
| status | body | string | nie | status zamówienia. | placed, paid, completed, canceled. |
| currency | body | string | nie | kod waluty zamówienia. | Dokładnie 3 znaki (ISO 4217). |
| totalValue | body | numer($double) | nie | całkowita wartość zamówienia. | Min. 0. |
| returnsValue | body | numer($double) | nie | wartość zwróconych produktów. | Min. 0. |
| customer | body | object | tak | dane identyfikacyjne klienta. | Zobacz Order customer data |
| products | body | array | tak | zamówione produkty. | Zobacz Order product data |
| orderAttributes | body | array | nie | niestandardowe atrybuty zamówienia. | Zobacz Order attribute value |
Order customer data
| Parametr | Lokalizacja | Typ | Wymagany | Opis | Uwagi |
| body | string | warunkowo | adres e-mail klienta. | Wymagany, jeśli e-mail jest domyślnym trybem dopasowania. Maks. 320 znaków. | |
| phone | body | string | warunkowo | numer telefonu klienta. | Wymagany, jeśli telefon jest domyślnym trybem dopasowania. Maks. 20 znaków. |
| crmId | body | string | warunkowo | identyfikator CRM klienta. | Wymagany, jeśli CRM ID jest domyślnym trybem dopasowania. Maks. 128 znaków. |
Wymagany jest co najmniej jeden identyfikator klienta zgodny z konfiguracją w Ustawienia > Klienci > Klienci.
Order product data
| Parametr | Lokalizacja | Typ | Wymagany | Opis | Uwagi |
| id | body | string | tak | identyfikator produktu. | Min. 1, maks. 128 znaków. |
| name | body | string | tak | nazwa produktu. | Min. 0, maks. 2048 znaków. |
| price | body | numer($double) | tak | cena jednostkowa. | Min. 0. |
| quantity | body | integer($int32) | tak | zamówiona ilość. | Min. 1, maks. 2147483647. |
| returned | body | integer($int32) | nie | zwrócona ilość. | Min. 0, maks. 2147483647. |
| url | body | string | nie | URL strony produktu. | Maks. 2048 znaków. |
| imageUrl | body | string | nie | URL zdjęcia produktu. | Maks. 2048 znaków. |
| category | body | string | nie | kategoria produktu. | Maks. 2048 znaków. |
| productAttributes | body | array | nie | niestandardowe cechy produktu. | Zobacz Product custom attribute values |
Product custom attribute values
| Parametr | Lokalizacja | Typ | Wymagany | Opis | Uwagi |
| name | body | string | tak | nazwa cechy produktu. | Maks. 256 znaków. |
| value | body | string | nie | wartość tej cechy. | – |
Order attribute value#
| Parametr | Lokalizacja | Typ | Wymagany | Opis | Uwagi |
| name | body | string | tak | nazwa cechy zamówienia. | Maks. 256 znaków. |
| value | body | string | nie | wartość tej cechy. | – |
Przykładowe zapytania#
Dodanie nowego zamówienia
{
"mode": "Add",
"data": [
{
"id": "202478543",
"date": "2024-11-15T14:32:00.000Z",
"timeZone": "Central European Standard Time",
"websiteId": 1,
"status": "completed",
"currency": "PLN",
"totalValue": 1049.97,
"returnsValue": 0,
"customer": {
"email": "jan.kowalski@poczta.pl",
"phone": "+48501234567",
"crmId": "CRM-98765"
},
"products": [
{
"id": "SKU-12345",
"name": "Słuchawki bezprzewodowe Bluetooth",
"price": 899.99,
"quantity": 1,
"returned": 0,
"url": "https://sklep.pl/produkty/sluchawki-bezprzewodowe",
"imageUrl": "https://sklep.pl/zdjecia/sluchawki-czarne.jpg",
"category": "Elektronika > Audio",
"productAttributes": [
{
"name": "Kolor",
"value": "Czarny"
},
{
"name": "Gwarancja",
"value": "24 miesiące"
}
]
},
{
"id": "SKU-67890",
"name": "Kabel ładujący USB-C",
"price": 74.99,
"quantity": 2,
"returned": 0,
"url": "https://sklep.pl/produkty/kabel-usb-c",
"imageUrl": "https://sklep.pl/zdjecia/kabel-usbc.jpg",
"category": "Elektronika > Akcesoria"
}
],
"orderAttributes": [
{
"name": "Metoda wysyłki",
"value": "Dostawa ekspresowa"
},
{
"name": "Metoda płatności",
"value": "Karta kredytowa"
}
]
}
]
}AddOrReplace – tworzenie nowego lub aktualizacja istniejącego zamówienia
{
"mode": "AddOrReplace",
"data": [
{
"id": "ORD-2024-78543",
"date": "2024-11-15T14:32:00.000Z",
"status": "paid",
"currency": "PLN",
"totalValue": 1049.97,
"customer": {
"email": "jan.kowalski@ poczta.pl "
},
"products": [
{
"id": "SKU-12345",
"name": "Słuchawki bezprzewodowe Bluetooth",
"price": 899.99,
"quantity": 1
}
]
}
]
}Kody odpowiedzi
| Kod | Status | Opis |
| 201 | Created | zamówienie zostało pomyślnie utworzone lub zaktualizowane. |
| 400 | Bad Request | nieprawidłowe parametry żądania lub brak wymaganych pól. |
| 401 | Unauthorized | brak lub nieprawidłowy klucz API. |
Przykładowe odpowiedzi
201 Created
W przypadku sukcesu endpoint zwraca pustą treść odpowiedzi.
400 Bad Request
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "Bad Request",
"status": 400,
"detail": "Validation failed",
"instance": "/orders",
"errors": [
"Field 'id' is required",
"Field 'totalValue' must be greater than or equal to 0"
]
}GET /orders/{id} – pobieranie zamówienia po ID
Metoda GET /orders/{id} pobiera pełne dane zamówienia, w tym informacje o kliencie, produktach i niestandardowych atrybutach, na podstawie identyfikatora zamówienia.
Endpoint
Endpoint, czyli adres serwera dla tego zapytania to https://api.ecdp.app/orders/{id}
Parametry zapytania
| Parametr | Lokalizacja | Typ | Wymagany | Opis | Uwagi |
| id | path | string | tak | identyfikator zamówienia. | Unikalny ID przypisany podczas tworzenia zamówienia. |
| x-api-key | header | string | tak | klucz uwierzytelniający API. | Pobierz w Ustawienia > API. |
Przykładowe zapytania
GET /orders/202478543
Kody odpowiedzi
| Kod | Status | Opis |
| 200 | Success | dane zamówienia zostały pomyślnie zwrócone. |
| 401 | Unauthorized | brak lub nieprawidłowy klucz API. |
| 404 | Not Found | zamówienie o podanym ID nie istnieje. |
Przykładowe odpowiedzi#
200 Success
{
"status": 0,
"data": {
"id": "202478543",
"date": "2024-11-15T14:32:00.000Z",
"timeZone": "Central European Standard Time",
"websiteId": 1,
"status": "completed",
"currency": "PLN",
"totalValue": 1049.97,
"returnsValue": 0,
"customer": {
"id": 458721,
"email": "jan.kowalski@ poczta.pl ",
"phone": "+48501234567",
"crmId": "CRM-98765"
},
"products": [
{
"id": "SKU-12345",
"name": "Słuchawki bezprzewodowe Bluetooth",
"price": 899.99,
"quantity": 1,
"returned": 0,
"url": "https://sklep.pl/produkty/sluchawki-bezprzewodowe",
"imageUrl": "https://sklep.pl/zdjecia/sluchawki-czarne.jpg",
"category": "Elektronika > Audio",
"productAttributes": [
{
"name": "Kolor",
"value": "Czarny"
},
{
"name": "Gwarancja",
"value": "24 miesiące"
}
]
},
{
"id": "SKU-67890",
"name": "Kabel ładujący USB-C",
"price": 74.99,
"quantity": 2,
"returned": 0,
"url": "https://sklep.pl/produkty/kabel-usb-c",
"imageUrl": "https://sklep.pl/zdjecia/kabel-usbc.jpg",
"category": "Elektronika > Akcesoria",
"productAttributes": []
}
],
"orderAttributes": [
{
"name": "Metoda wysyłki",
"value": "Dostawa ekspresowa"
},
{
"name": "Metoda płatności",
"value": "Karta kredytowa"
}
]
}
}404 Not Found
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
"title": "Not Found",
"status": 404,
"detail": "Order not found",
"instance": "/orders/ORD-INVALID-123"
}PUT /orders/status – aktualizacja statusu zamówienia
Metoda PUT /orders/status aktualizuje status istniejącego zamówienia. Używaj tego endpointu, aby odzwierciedlić zmiany w cyklu życia zamówienia – na przykład potwierdzenie płatności czy zakończenie realizacji.
Endpoint
Endpoint, czyli adres serwera dla tego zapytania to https://api.ecdp.app/orders/status
Parametry zapytania
| Parametr | Lokalizacja | Typ | Wymagany | Opis | Dozwolone wartości / Uwagi |
| x-api-key | header | string | tak | klucz uwierzytelniający API. | Pobierz w Ustawienia > API. |
| orderId | body | string | tak | identyfikator zamówienia. | Musi wskazywać na istniejące zamówienie. Min. 1 znak. |
| orderStatus | body | string | tak | nowy status zamówienia. | placed, paid, completed, canceled. |
Przykładowe zapytania
Oznaczenie zamówienia jako opłacone
{
"orderId": "202478543",
"orderStatus": "paid"
}Oznaczenie zamówienia jako zrealizowane
{
"orderId": "202478543",
"orderStatus": "completed"
}Kody odpowiedzi
| Kod | Status | Opis |
| 200 | Success | status zamówienia został pomyślnie zaktualizowany. |
| 400 | Bad Request | nieprawidłowa wartość statusu lub brak wymaganych pól. |
| 401 | Unauthorized | brak lub nieprawidłowy klucz API. |
Przykładowa odpowiedź
400 Bad Request
{
"type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
"title": "Bad Request",
"status": 400,
"detail": "Invalid order status",
"instance": "/orders/status",
"errors": [
"Field 'orderStatus' must be one of: placed, paid, completed, canceled"
]
}DELETE /orders/{id} – oznaczanie zamówienia jako usuniętego
Metoda DELETE /orders/{id} oznacza zamówienie jako usunięte poprzez ustawienie flagi IsDeleted. To tzw. miękkie usunięcie – rekord zamówienia pozostaje w bazie danych do celów audytowych, ale jest wykluczony z aktywnych raportów i analiz.
Endpoint
Endpoint, czyli adres serwera dla tego zapytania to https://api.ecdp.app/orders/{id}
Parametry zapytania
| Parametr | Lokalizacja | Typ | Wymagany | Opis | Uwagi |
| id | path | string | tak | identyfikator zamówienia. | Musi wskazywać na istniejące zamówienie. |
| x-api-key | header | string | tak | klucz uwierzytelniający API. | Pobierz w Ustawienia > API. |
Przykładowe zapytanie
DELETE /orders/2024-78543
Host: https://api.ecdp.app
Kody odpowiedzi
| Kod | Status | Opis |
| 200 | Success | zamówienie oznaczone jako usunięte; zwraca dane zamówienia. |
| 401 | Unauthorized | brak lub nieprawidłowy klucz API. |
| 404 | Not Found | zamówienie o podanym ID nie istnieje. |
Przykładowa odpowiedź
200 Success
{
"status": 0,
"data": {
"id": "202478543",
"date": "2024-11-15T14:32:00.000Z",
"timeZone": "Central European Standard Time",
"websiteId": 1,
"status": "completed",
"currency": "PLN",
"totalValue": 1049.97,
"returnsValue": 0,
"customer": {
"id": 458721,
"email": "jan.kowalski@ poczta.pl ",
"phone": "+48501234567",
"crmId": "CRM-98765"
},
"products": [
{
"id": "SKU-12345",
"name": "Słuchawki bezprzewodowe Bluetooth",
"price": 899.99,
"quantity": 1,
"returned": 0,
"url": "https://sklep.pl/produkty/sluchawki-bezprzewodowe",
"imageUrl": "https://sklep.pl/zdjecia/sluchawki-czarne.jpg",
"category": "Elektronika > Audio",
"productAttributes": [
{
"name": "Kolor",
"value": "Czarny"
}
]
}
],
"orderAttributes": [
{
"name": "Metoda wysyłki",
"value": "Dostawa ekspresowa"
}
]
}
}Walidacja i zasady działania
Poniższe reguły walidacji obowiązują dla wszystkich endpointów API zamówień:
- ID zamówienia musi być unikalne w ramach jednostki biznesowej.
- Wymagany jest co najmniej jeden identyfikator klienta (email, phone lub crmId) zgodny z domyślnym polem identyfikującym.
- Tablica products musi zawierać co najmniej jeden produkt z prawidłowymi polami id, name, price i quantity.
- Liczba produktu musi wynosić co najmniej 1. Cena produktu i totalValue muszą być równe 0 lub większe.
- Jeśli timeZone nie zostanie podany, stosowana jest strefa czasowa skonfigurowana dla jednostki biznesowej.
- Status zamówienia przyjmuje tylko wartości: placed, paid, completed, canceled (wielkość liter nie ma znaczenia).
- Operacja DELETE wykonuje miękkie usunięcie. Zamówienie pozostaje w bazie danych z flagą IsDeleted ustawioną na true.
Dokumentacja referencyjna
Swagger – sekcja Orders