Jak wysłać dokument FV do zamówienia przez API

Do czego służy ta instrukcja

Ten artykuł pokazuje, jak dodać dokument FV do istniejącego zamówienia w xSale za pomocą REST API. Dzięki temu przy zamówieniu masz kompletną dokumentację, a integracje mogą wykorzystać ten dokument w dalszej obsłudze.

W dalszej części znajdziesz również część techniczną z przykładami zapytań API (pozostawioną bez zmian).

W tym artykule znajdziesz

• kiedy warto zastosować wysyłkę dokumentu FV przez API
• wymagania i dane potrzebne do wykonania operacji
• szybki przepis krok po kroku
• typowe problemy i sposób weryfikacji

Kiedy stosować

Najczęściej ta operacja jest przydatna, gdy faktura powstaje w systemie zewnętrznym (np. ERP), a w xSale chcesz ją widzieć bezpośrednio na zamówieniu. W zależności od konfiguracji integracji dokument może być również wykorzystany do przekazania danych dalej (np. do kanału sprzedaży).

Wymagania

• dostęp do REST API xSale (autoryzacja) dla właściwej organizacji
• wartość organizationName
• identyfikator zamówienia w xSale (id)
• plik faktury oraz dane wymagane przez endpoint (zgodnie z przykładem w części technicznej)

Szybki przepis (krok po kroku)

1. Ustal identyfikator zamówienia w xSale, do którego chcesz dodać fakturę.
2. Przygotuj dokument FV w formie załącznika (plik) oraz wymagane parametry.
3. Wyślij zapytanie API dodające załącznik do zamówienia (przykład znajduje się poniżej).
4. Sprawdź odpowiedź API i upewnij się, że operacja zakończyła się powodzeniem.
5. Zweryfikuj w panelu xSale, czy dokument jest widoczny na zamówieniu.

Typowe problemy i jak je sprawdzić

• Błąd autoryzacji — sprawdź dane logowania/token i uprawnienia użytkownika do REST API.
• Nieprawidłowy identyfikator zamówienia — upewnij się, że wysyłasz poprawne id dla zamówienia w xSale.
• Dokument nie pojawia się w xSale — odśwież widok zamówienia i sprawdź, czy w odpowiedzi API zwrócono identyfikator/rezultat operacji.
• Niepoprawny format danych — porównaj wysyłane pole z przykładem poniżej (w tym nazwę pola i typ danych).

Szczegóły techniczne

Aby dodać fakturę do zamówienia w systemie xSale i przesłać ją do Amazon, należy użyć odpowiednich metod API opisanych poniżej.

Dodanie załącznika (dla opisywanego przykładu jest to faktura)

POST /{organizationName}/orders/{id}/attachments

Parametry:

Parametr	Opis
Id	Identyfikator zamówienia w xSale
typeIds	Lista typów załączników (np. dla faktury:2048 )
documentNumber	Numer faktury – wyświetlany w interfejsie i przesyłany do Amazon
file	Plik z treścią faktury

Lista dostępnych typów załączników

Aby pobrać listę typów załączników (w tym identyfikator typu faktura:2048), skorzystaj z metody:

GET /{organizationName}/orders/attachments-types

Wysyłka do Amazon

Załącznik zostanie wysłany do Amazon tylko jeśli:

• typ załącznika to Faktura sprzedaży
• podano numer dokumentu (documentNumber)

Aktualizacja załącznika

Jeśli faktura nie została jeszcze wysłana (np. brakowało numeru), można ją zaktualizować – wtedy zostanie wysłana. Faktury już wysłanej nie można ponownie wysłać po edycji. Metoda:

PUT /{organizationName}/orders/{id}/attachments/{attachmentId}

Usuwanie załącznika

Metoda:

DELETE /{organizationName}/orders/{id}/attachments/{attachmentId}

Jeżeli załącznik został już wysłany do Amazon – zostanie usunięty tylko w xSale (nie w Amazon).

Pobieranie listy załączników

Aby wyświetlić wszystkie załączniki dla zamówienia:

GET /{organizationName}/orders/{id}

Załączniki są również widoczne w interfejsie użytkownika xSale: