Dodanie zamówienia z własnego sklepu lub marketplace

Do czego służy ta instrukcja

Ten artykuł pokazuje, jak dodać do xSale zamówienie pochodzące z własnego sklepu lub marketplace, dla którego nie masz gotowej integracji w katalogu xSale. Krok po kroku uzupełniasz dane zamówienia, płatności, dostawy/przesyłki oraz kontrahenta, aby w xSale powstał kompletny rekord do dalszej obsługi.

Na początku znajdziesz skrótowy opis procesu i wymagania, a dalej część techniczną z endpointami i przykładami (pozostawioną bez zmian).

W tym artykule znajdziesz

• kiedy warto dodawać zamówienia do xSale przez API
• wymagania i dane wejściowe
• szybki przepis krok po kroku (co w jakiej kolejności wywołać)
• typowe problemy i sposób weryfikacji

Kiedy stosować

To rozwiązanie stosuje się, gdy zamówienia powstają w systemie zewnętrznym (np. autorski sklep lub niestandardowy marketplace), a chcesz obsługiwać je w xSale — np. uruchamiać automatyzacje, przekazywać do ERP lub tworzyć wysyłki. W praktyce API pozwala odtworzyć strukturę zamówienia tak, jakby została pobrana przez standardową integrację.

Wymagania

• dostęp do REST API xSale (autoryzacja) dla właściwej organizacji
• wartość organizationName
• dane zamówienia z systemu źródłowego (pozycje, kwoty, waluta, statusy)
• dane płatności (jeśli występują) oraz dane dostawy/przesyłki
• dane kontrahenta (klienta) powiązane z zamówieniem

Szybki przepis (krok po kroku)

1. Dodaj zamówienie do xSale (utworzenie rekordu zamówienia).
2. Dodaj płatność i powiąż ją z zamówieniem (jeśli dotyczy).
3. Uzupełnij dane dostawy i przesyłki (metoda, adres, parametry).
4. Utwórz lub powiąż kontrahenta (klienta) oraz przypisz go do zamówienia.
5. Zweryfikuj w xSale, czy zamówienie ma komplet danych i jest gotowe do dalszej obsługi.

Typowe problemy i jak je sprawdzić

• Brak części danych na zamówieniu — upewnij się, że wykonałeś wszystkie kroki (zamówienie → płatność → dostawa/przesyłka → kontrahent).
• Duplikaty zamówień — w systemie źródłowym trzymaj jednoznaczne identyfikatory i zapisuj powiązania po stronie integracji.
• Błąd autoryzacji — sprawdź dane logowania/token oraz uprawnienia do REST API.
• Niezgodny format danych — porównaj body zapytań z przykładami w części technicznej (nazwy pól i typy).

Szczegóły techniczne

Dzięki zasobom REST API możesz wprowadzać do xSale zamówienia z dedykowanych platform e-commerce oraz marketplace, niedostępnych w katalogu integracji xSale. Zakres danych w  zamówieniu wprowadzanym z własnego systemu sprzedażowego obejmuje kilka obszarów. Ten poradnik opisuje dodawanie do xSale zamówień i płatności. Omawia także zasoby, których należy użyć, aby uzupełnić szczegółowe informacje o dostawie i przesyłce oraz dane kontrahenta powiązanego z zamówieniem. Zdecyduj, jakie dane chcesz importować do xSale i skorzystaj z poniższych instrukcji, aby przesłać zamówienie.

1. Wprowadzenie zamówienia do xSale

Aby dodać zamówienie do xSale, użyj zasobu:

POST /{organizationName}/orders

Wymagane pola

Poniższa lista prezentuje pola wymagane do utworzenia zamówienia. Jest to minimalny zakres danych, niezbędny do przesłania w zapytaniu, aby xSale mógł utworzyć zamówienie.

Dane o integracji i płatności:

• ID integracji – IntegrationId – wskazuje źródło, z którego  pochodzi zamówienie. Sprawdź tutaj, jak dodać integrację REST API.
• ID formy płatności – PaymentFormId
• data zamówienia – PurchaseDate  – np. 2024-10-25

Dane kontrahenta:

• ID nabywcy – BuyerId
• ID odbiorcy – RecipientId
• ID płatnika – PayerId

Dodając zamówienie możesz wyszukać wśród kontrahentów istniejących w bazie xSale twojej firmy (np. po adresie e-mail lub numerze NIP) i użyć ID odnalezionego kontrahenta lub stworzyć nowego kontrahenta. Więcej informacji o danych kontrahenta znajdziesz w dalszej części wpisu.

Zamówione produkty:

• ID oferty – OfferId
• ID wariantu – VariantId
• ilość – Quantity
• cena netto – PriceNet – cena netto za jednostkę towaru
• cena brutto – PriceGross – cena brutto za jednostkę towaru

Wymagane jest przesłanie wartości przynajmniej w jednym z pól – PriceNet lub PriceGross. Natomiast domyślne mechanizmy w xSale działają w oparciu o cenę brutto, dlatego rekomendujemy wprowadzanie ceny brutto.

Dodatkowe informacje

Opcjonalnie możesz przesłać dodatkowe dane, które ułatwią obsługę zamówienia w xSale i/lub umożliwią prawidłowe działanie dalszych akcji i procesów. Wśród tych akcji znajduje się szereg automatyzacji związanych m. in. z przekazywaniem zamówienia do systemu ERP, tworzeniem przesyłki i drukowaniem listu przewozowego, wystawianiem faktur oraz wysyłaniem do klienta maili z aktualizacjami statusu realizacji zamówienia.

Status i identyfikacja zamówienia

• numer obcy – ForeignId – np. ID zamówienia ze sklepu lub marketplace
• ID statusu – StatusId – dla nowych zamówień rekomendujemy użycie statusu Nowe (ID: 3), który domyślnie wyzwala automatyzacje działające np. w integracjach z systemami ERP

Informacje o dostawie i przesyłce

• ID sposobu dostawy – DeliveryMethodId
• liczba paczek – NumberOfPackages
• punkt dostawy – PointOfDelivery – np. numer Paczkomatu InPost – (KRA197M)

Zarządzanie sposobami dostawy odbywa się z wykorzystaniem zasobu DeliveryMethod. Aby pobrać listę dostępnych sposobów dostawy odpytaj endpoint:

GET /{organizationName}/delivery-method

Adres odbiorcy, nabywcy i płatnika

Powiązanie kontrahenta z zamówieniem odbywa się poprzez ID odbiorcy, nabywcy i płatnika. Jeśli jednak nie zamierzasz wyszukiwać kontrahenta w bazie xSale, prześlij w danych zamówienia dane adresowe, uzupełniając odpowiednie sekcje:

• adres kupującego – BuyerAddress
• adres odbiorcy – RecipientAddress – dane do wysyłki
• adres płatnika – PayerAddress

Zestaw pól, które możesz uzupełnić, wygląda następująco:

• nazwa – Name, np. imię lub nazwa firmy
• nazwa 2 – Name2, np. nazwisko
• nazwa 3 – Name3
• NIP – TaxNumber
• numer telefonu – Phone – użyj tego pola, aby podać numer do przekazania kurierowi
• numer telefonu komórkowego – MobilePhone
• e-mail – Email
• miasto – City
• ulica – Street
• numer budynku / lokalu – StreetNumber
• kod pocztowy – ZipCode
• kraj – Country
• notatki – Notes

Pozostałe informacje

• ID waluty – CurrencyId
• dokument liczony od brutto – IsVatTypeGross – domyślna i rekomendowana wartość to false
• rodzaj dokumentu – InvoiceTypeId – 1 – faktura, 2 – paragon
• uwagi klienta – Comments

Po poprawnym utworzeniu zamówienia aplikacja zwróci jego dane - ID i FGUID oraz status 201.

2. Dodawanie płatności za zamówienie

Ze względu na szerokie funkcjonalności w obszarze eksportu danych o płatnościach do zintegrowanych z xSale systemów ERP, płatności stanowią odrębny zasób. Dodając płatność możesz powiązać ją z zamówieniem, dlatego jest to operacja, którą należy wykonać chronologicznie później – wymagane jest podanie ID zamówienia. Prześlij zapytanie na endpoint:

POST /{organizationName}/payment

Wprowadź wymagane dane:

• ID kontrahenta – CustomerId
• wartość – Amount
• ID waluty – CurrencyId
• ID integracji – IntegrationId
• rodzaj płatności – TypeId – 5 – wpłata, 6 – wypłata
• data – Date – np. 2024-10-25
• ID statusu płatności – StatusId

Dodatkowo endpoint przyjmuje poniższe dane:

• ID zamówienia – OrderId
• rejestr – Register – np. Allegro
• operacja – Operation – np. KP
• uwagi – Comments
• data importu pliku zamówień – ImportKPFileDate – np. 2024-08-29T07:56:55.356Z

Zmianę statusu płatności i aktualizację jej wartości wykonasz komunikując się z API przez endpoint:

PUT /{organizationName}/payment{id}