Powiązania z zamówieniami

Jeśli integrujesz Fakturnię ze sklepem lub innym systemem sprzedaży, możesz powiązać dokument z zamówieniem w Twoim systemie. Powiązanie jest widoczne w aplikacji i pozwala odróżnić dokumenty wystawione przez integrację od tych wystawionych ręcznie.

Wymagany zakres uprawnień: documents:update-external-reference.

Ustawienie powiązania#

curl -s -X PATCH https://prod.api.fakturnia.pl/external/v1/documents/{id}/external-reference \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "externalSource": "woocommerce",
    "externalOrderId": "10241",
    "externalOrderNumber": "ZAM/2026/10241"
  }'

Odpowiedź zwraca aktualny stan powiązania:

{
  "success": true,
  "message": "External reference updated.",
  "data": {
    "id": "665f0c...",
    "externalSource": "woocommerce",
    "externalOrderId": "10241",
    "externalOrderNumber": "ZAM/2026/10241"
  }
}

Usunięcie powiązania#

curl -s -X DELETE https://prod.api.fakturnia.pl/external/v1/documents/{id}/external-reference \
  -H "Authorization: Bearer $TOKEN"

Dokument pozostaje bez zmian, znika tylko powiązanie z zamówieniem.

Filtrowanie po powiązaniu#

Na liście dokumentów parametr onlyUnlinked=true zwraca wyłącznie dokumenty bez powiązania. To przydatne, gdy dopinasz istniejące dokumenty do zamówień i chcesz znaleźć te jeszcze nieprzypisane:

curl -s "https://prod.api.fakturnia.pl/external/v1/documents?onlyUnlinked=true&buyerNip=5252248481" \
  -H "Authorization: Bearer $TOKEN"

Pozostałe filtry listy dokumentów (typ, zakres dat, dane nabywcy) opisuje Paginacja i filtrowanie.

Typowy przepływ integracji: wystaw dokument przez POST /documents, a następnie od razu ustaw powiązanie tym endpointem, używając identyfikatora zamówienia ze swojego systemu.