Do czego służy ta instrukcja
Ten artykuł pokazuje, jak pobierać zamówienia z xSale do własnego systemu ERP za pomocą REST API. Najczęściej wykorzystuje się do tego statusy i filtry, aby do ERP trafiały tylko te zamówienia, które spełniają konkretne warunki.
Niżej znajduje się część techniczna z endpointami i przykładami (pozostawiona bez zmian), a na początku dodajemy skrótowy opis kroków i wymagań.
W tym artykule znajdziesz
- kiedy i jak planować pobieranie zamówień do ERP
- wymagania i dane potrzebne do wykonania zapytań
- szybki przepis krok po kroku
- typowe problemy i sposób weryfikacji
Kiedy stosować
To podejście sprawdza się, gdy xSale jest źródłem zamówień (np. z marketplace’ów i sklepów), a proces realizacji i fakturowania odbywa się w Twoim ERP. W praktyce pobierasz zamówienia w określonym statusie, a po imporcie zmieniasz status w xSale, aby uniknąć ponownego pobrania.
Wymagania
- dostęp do REST API xSale (autoryzacja) dla właściwej organizacji
- wartość organizationName
- ustalona logika statusów (który status oznacza „do pobrania do ERP” i jaki status ustawiasz po imporcie)
- znajomość filtrów, które chcesz stosować (np. status, data, kanał)
Szybki przepis (krok po kroku)
- Ustal status (lub zestaw statusów), które oznaczają zamówienia gotowe do pobrania do ERP.
- Wyślij zapytanie do listy zamówień z odpowiednimi filtrami (przykłady poniżej).
- W ERP zaimportuj zamówienia i zapisz powiązania (np. numer/ID zamówienia).
- Po imporcie zmień status zamówień w xSale, aby nie pobrać ich ponownie.
- Monitoruj wyjątki (np. zamówienia błędne lub wymagające ręcznej obsługi) i obsługuj je osobno.
Typowe problemy i jak je sprawdzić
- Duplikaty w ERP — upewnij się, że po imporcie zmieniasz status w xSale lub zapisujesz w ERP informację, że zamówienie zostało już pobrane.
- Pobierasz „za dużo” zamówień — doprecyzuj filtry (najczęściej status + zakres dat).
- Błąd autoryzacji — sprawdź dane logowania/token oraz uprawnienia do REST API.
- Brak oczekiwanych zamówień — zweryfikuj status w xSale i czy filtr nie wyklucza zamówień (np. z innego kanału).
Szczegóły techniczne
Projektując mechanizm pobierania zamówień z xSale do własnego systemu ERP warto opierać się na statusach zamówień. Dzięki dostępnym filtrom REST API xSale daje możliwość precyzyjnego wskazania, które zamówienia mają trafić do ERP. Zmiana statusu zamówienia po jego imporcie pozwala wygodnie zarządzać procesem realizacji zamówienia i uniknąć ewentualnych pomyłek.
Listę wszystkich zamówień zwraca endpoint:
GET /{organizationName}/orders
W przesyłanym zapytaniu możesz wykorzystać filtry statusidin oraz statusnamein. W obu przypadkach wskaż tablicę zawierającą odpowiednio id statusów (integer) dla statusidin oraz nazw statusów (string) dla statusnamein.
W otrzymanej odpowiedzi Items to kolekcja pozycji zamówienia, zawierająca listę zakupionych produktów. Z kolei OrderItemArticles to kolekcja artykułów powiązanych z pozycją zamówienia w Items. W praktyce można ją traktować jako listę towarów do wydania z magazynu – zwracamy tutaj pozycje przeliczone z zamówionych ofert i zestawów.
Lista wszystkich statusów dostępna jest w zasobie:
GET /{organizationName}/statuses
Po pobraniu zamówienia do systemu ERP rekomendujemy aktualizację jego statusu. Ta operacja pozwala wykluczyć ponowny import zamówienia w oparciu o wskazane w filtrach statusy.
Przykład:
1. Pobierz zamówienia ze statusem Nowe.
2. Po poprawnym wczytaniu zamówienia do ERP zmień status zamówienia w xSale. Domyślny status, jaki xSale nadaje zamówieniom poprawnie przesłanym do systemu ERP, to Zaimportowano do ERP.
3. Jeśli podczas wczytywania zamówienia do systemu ERP wystąpił błąd, ustaw na takim zamówieniu statusu Do obsługi ręcznej.
Aktualizacja statusu odbywa się z wykorzystaniem endpointu:
PUT /{organizationName}/orders/{id}/change-status
Do przesłania zapytania potrzebne jest ID zamówienia oraz ID statusu, który ma zostać nadany po wysłaniu żądania.
