Adresy REST

Wszystkie adresy zaczynają się od /api. Odpowiedzi i żądania są w JSON.

Konwencje

Stronicowanie. Listy przyjmują page (od 1) i per_page. Odpowiedź niesie {"items": [...], "total": N, "page": P, "per_page": R} — total to liczba wszystkich pasujących rekordów, nie tylko tych na stronie.

Nie każda lista używa tych samych nazw

Kilka starszych adresów przyjmuje limit zamiast per_page i zwraca kolekcję pod inną nazwą niż items. Zawsze sprawdź pierwszą odpowiedź zamiast zakładać kształt — ta niezgodność wywołała u nas realną usterkę, w której wyszukiwarka klientów zawsze zwracała pustą listę.

Sortowanie. Tam, gdzie jest wspierane: sort_by (nazwa pola) i sort_dir (asc/desc).

Identyfikatory. UUID w postaci tekstowej. Numer zamówienia (order_number) to osobne, czytelne dla człowieka pole — nie używaj go jako klucza w API.

Główne grupy zasobów

Grupa	Przykładowy adres	Zawartość
Zamówienia	/api/orders	pełny obieg zamówienia, oś czasu, tagi, notatki
Produkty	/api/products	katalog, warianty, stany, ceny
Klienci	/api/crm/customers	kartoteka, etykiety, statusy
Magazyn	/api/warehouses, /api/stock	magazyny, stany, ruchy
Dokumenty magazynowe	/api/warehouse-docs	PZ, WZ, MM, korekty, inwentaryzacje
Faktury	/api/documents	dokumenty sprzedaży, serie numeracji
Przesyłki	/api/shipments	nadania, etykiety, śledzenie
Zwroty	/api/returns	zgłoszenia i ich obieg
Integracje	/api/integrations	katalog dostawców, poświadczenia, testy połączenia
Automatyzacje	/api/automations	reguły, historia wykonań
Webhooki	/api/webhooks	subskrypcje zdarzeń wychodzących
Analityka	/api/analytics/*	sprzedaż, produkty, klienci, wysyłka

Pełną, zawsze aktualną listę adresów wraz z kształtem żądań i odpowiedzi znajdziesz pod /docs swojej instancji (interaktywna dokumentacja OpenAPI wystawiana przez aplikację).

Nadawanie przesyłki — przykład

curl -X POST https://twoja-instancja/api/shipments \
  -H "X-API-Key: $KLUCZ" -H "Content-Type: application/json" \
  -d '{"order_id": "…", "courier_code": "dpd", "fields": {"service": "standard"}}'

Odpowiedź 201 oznacza, że kurier przyjął nadanie i zwrócił numer śledzenia. Odpowiedź 422 oznacza, że odmówił — w detail jest jego powód, a w Kangurze nie powstaje rekord przesyłki. Nie ma stanu pośredniego „przesyłka utworzona, ale bez numeru”.