Status wysyłki

Sprawdzenie statusu wysyłki

GET /invoices/{environment}/status/{referenceNumber}

Sprawdza status sesji wysyłki (online lub batch) po numerze referencyjnym. Zwraca pełne dane sesji wraz z liczbą faktur i statusem każdej faktury. Wymaga aktywnej sesji KSeF.

Parametry ścieżki pobierania statusu

Parametr	Typ	Wymagany	Opis
environment	string	✅	test, demo lub prod
referenceNumber	string	✅	Numer referencyjny sesji/paczki KSeF

Odpowiedź 200 pobierania statusu

{
  "referenceNumber": "20260101-AU-XXXXXXXX-XXXX-XX",
  "status": {
    "code": 200,
    "description": "Sesja wsadowa przetworzona pomyślnie"
  },
  "dateCreated": "2026-01-15 12:00:00",
  "dateUpdated": "2026-01-15 12:05:00",
  "totalInvoiceCount": 3,
  "successfulInvoiceCount": 3,
  "failedInvoiceCount": 0,
  "invoices": [
    {
      "ordinalNumber": 1,
      "invoiceNumber": "FV/2026/01/001",
      "ksefNumber": "1234567890-20260101-ABCDEF-12",
      "acquisitionDate": "2026-01-15 12:01:00",
      "status": { "code": 200, "description": "OK" }
    }
  ]
}

Pole	Typ	Opis
referenceNumber	string	Numer referencyjny KSeF
status	object	Status przetwarzania sesji (code + description)
dateCreated	string	Data utworzenia sesji
dateUpdated	string	Data ostatniej aktualizacji sesji
totalInvoiceCount	integer	Łączna liczba faktur w sesji
successfulInvoiceCount	integer	Liczba pomyślnie przetworzonych faktur
failedInvoiceCount	integer	Liczba faktur z błędami
invoices	array	Lista faktur z ich indywidualnym statusem

Obiekt faktury

Pole	Typ	Opis
ordinalNumber	integer	Pozycja faktury w sesji
invoiceNumber	string	Numer faktury (np. FV/2026/01/001)
ksefNumber	string	Numer KSeF faktury
acquisitionDate	string	Data przyjęcia faktury przez KSeF
status	object	Status danej faktury (code + description)

Synchronizacja referencji sesji

Podczas sprawdzania statusu, ksef-proxy automatycznie aktualizuje session_reference_number w:

• synced_invoices — dla faktur online dopasowanych po ksef_number
• offline_invoices — dla faktur batch dopasowanych po ksef_reference_number

Dzięki temu faktury wysłane przed wdrożeniem śledzenia sesji mogą być wstecznie powiązane z odpowiednią sesją.

Kody błędów pobierania statusu

Kod	Opis
401	Brak autoryzacji
404	Brak aktywnej sesji KSeF
409	Awaria lub symulacja KSeF — komunikat zawiera szczegóły
502	Błąd KSeF — wzbogacony o kontekst awarii, jeśli dotyczy

Pobieranie UPO

GET /invoices/{environment}/status/{referenceNumber}/{ksefNumber}/upo

Pobiera UPO (Urzędowe Poświadczenie Odbioru) dla faktury z KSeF. Wymaga numeru referencyjnego sesji, w której faktura została wysłana, oraz aktywnej sesji KSeF.

Dlaczego wymagany jest referenceNumber?

API KSeF v2 wymaga numeru referencyjnego sesji do pobrania UPO: /v2/sessions/{referenceNumber}/invoices/ksef/{ksefNumber}/upo

referenceNumber to identyfikator sesji zwrócony podczas wysyłki faktury (z POST /invoices/{environment}/send lub GET /invoices/{environment}/status/{referenceNumber}).

Parametry ścieżki pobierania UPO

Parametr	Typ	Wymagany	Opis
environment	string	✅	test, demo lub prod
referenceNumber	string	✅	Numer referencyjny sesji KSeF (z odpowiedzi wysyłki)
ksefNumber	string	✅	Numer KSeF faktury

Parametry zapytania pobierania UPO

Parametr	Typ	Domyślnie	Opis
docType	string	xml	xml (UPO XML) lub pdf (UPO PDF)

Odpowiedź 200 — XML

{
  "ksefNumber": "1234567890-20260101-ABCDEF-12",
  "referenceNumber": "20260101-AU-XXXXXXXX-XXXX-XX",
  "docType": "xml",
  "contentType": "application/xml",
  "content": "PD94bWwgdmVyc2lvbj0i...",
  "fileName": "1234567890-20260101-ABCDEF-12-upo.xml"
}

Odpowiedź 200 — PDF

{
  "ksefNumber": "1234567890-20260101-ABCDEF-12",
  "referenceNumber": "20260101-AU-XXXXXXXX-XXXX-XX",
  "docType": "pdf",
  "contentType": "application/pdf",
  "content": "JVBERi0xLjQK...",
  "fileName": "1234567890-20260101-ABCDEF-12-upo.pdf"
}

Generowanie PDF po stronie serwera

Gdy zażądano docType=pdf, REST API zawsze zwraca dokument PDF. Jeśli API KSeF zwróci UPO w formacie XML (co jest domyślnym zachowaniem KSeF), serwer automatycznie konwertuje je do sformatowanego PDF za pomocą pdfmake, zawierającego nagłówek, szczegóły dokumentu i uporządkowany układ. Oznacza to, że docType=pdf jest zawsze niezawodny, niezależnie od natywnego formatu zwróconego przez KSeF.

Pole	Typ	Opis
ksefNumber	string	Numer KSeF faktury
referenceNumber	string	Numer referencyjny sesji
docType	string	xml lub pdf
contentType	string	application/xml lub application/pdf
content	string	Zawartość UPO zakodowana w base64
fileName	string	Sugerowana nazwa pliku

Kody błędów pobierania UPO

Kod	Opis
400	Nieprawidłowy parametr docType
401	Brak autoryzacji
404	UPO jeszcze niedostępne lub faktura nie znaleziona
409	Awaria lub symulacja KSeF
502	Błąd KSeF