Wysyłka faktury

POST /invoices/{environment}/send

Wysyła fakturę do KSeF w trybie online lub offline.

Tryby wysyłki

Tryb	Opis
online	Faktura szyfrowana i wysyłana bezpośrednio do KSeF. Endpoint czeka na potwierdzenie i zwraca numer KSeF. Wymaga aktywnej sesji KSeF i dostępności KSeF.
offline	Faktura podpisywana certyfikatem offline i zapisywana do kolejki. Wymaga aktywnej awarii/symulacji KSeF.

Parametry ścieżki

Parametr	Typ	Wymagany	Opis
environment	string	✅	test, demo lub prod

Request Body

{
  "invoiceXml": "PD94bWwgdmVyc2lvbj0i...",
  "mode": "online"
}

Pole	Typ	Wymagany	Opis
invoiceXml	string	✅	Treść XML faktury zakodowana w base64
mode	string	✅	online lub offline

Odpowiedź 200 — tryb online

{
  "mode": "online",
  "ksefNumber": "1234567890-20260101-ABCDEF-12",
  "referenceNumber": "20260101-AU-XXXXXXXX-XXXX-XX",
  "status": "sent",
  "invoiceNumber": "FV/2026/01/001"
}

Pole	Typ	Opis
mode	string	Zawsze online
ksefNumber	string | null	Numer KSeF przypisany do faktury (null jeśli wciąż przetwarzana)
referenceNumber	string	Numer referencyjny sesji KSeF
status	string	sent (uzyskano numer KSeF) lub pending (wciąż przetwarzana)
invoiceNumber	string	Numer faktury z XML (element P_2)

Referencja sesji

referenceNumber jest automatycznie zapisywany do synced_invoices.session_reference_number przez ksef-proxy. Ta referencja jest wymagana do późniejszego pobrania UPO przez endpoint statusu.

Odpowiedź 200 — tryb offline

{
  "mode": "offline",
  "offlineId": "uuid",
  "status": "signed",
  "invoiceNumber": "FV/2026/01/001",
  "qrLinkInvoice": "https://qr-test.ksef.mf.gov.pl/...",
  "qrLinkCertificate": "https://qr-test.ksef.mf.gov.pl/..."
}

Pole	Typ	Opis
mode	string	Zawsze offline
offlineId	string (uuid)	ID zapisanej faktury offline
status	string	signed — faktura podpisana i dodana do kolejki
invoiceNumber	string	Numer faktury z XML
qrLinkInvoice	string | null	URL weryfikacyjny QR dla faktury
qrLinkCertificate	string | null	URL weryfikacyjny QR dla certyfikatu

Kody błędów

Kod	Opis
400	Błędne parametry (brak XML, brak mode)
401	Brak autoryzacji
404	Brak aktywnej sesji KSeF (online) lub certyfikatu (offline)
409	Konflikt trybu — np. KSeF dostępny przy mode=offline lub KSeF niedostępny przy mode=online. Komunikat błędu zawiera szczegóły przyczyny (symulacja lub rzeczywista awaria).
502	Błąd KSeF — komunikat wzbogacony o kontekst awarii, jeśli dotyczy

Świadomość awarii

Wszystkie endpointy REST API komunikujące się z KSeF sprawdzają flagi awarii/symulacji przed wykonaniem żądania. Jeśli awaria lub symulacja jest aktywna, API zwraca błąd 409 z opisowym komunikatem informującym:

• Czy to symulacja (🔧) czy rzeczywista awaria (🚨)
• Czy administrator potwierdził sytuację
• Że dostępne są tylko akcje offline

Jeśli żądanie do KSeF się nie powiedzie, a żadne flagi nie są ustawione, komunikat informuje, że administrator nie potwierdził jeszcze przyczyny.