Send Invoice
POST /invoices/{environment}/sendβ
Sends an invoice to KSeF in online or offline mode.
Sending Modesβ
| Mode | Description |
|---|---|
online | Invoice is encrypted and sent directly to KSeF. The endpoint waits for confirmation and returns the KSeF number. Requires an active KSeF session and KSeF availability. |
offline | Invoice is signed with an offline certificate and saved to the queue. Requires an active KSeF outage/simulation. |
Path Parametersβ
| Parameter | Type | Required | Description |
|---|---|---|---|
environment | string | β | test, demo or prod |
Request Bodyβ
{
"invoiceXml": "PD94bWwgdmVyc2lvbj0i...",
"mode": "online"
}
| Field | Type | Required | Description |
|---|---|---|---|
invoiceXml | string | β | Base64-encoded invoice XML content |
mode | string | β | online or offline |
Response 200 β online modeβ
{
"mode": "online",
"ksefNumber": "1234567890-20260101-ABCDEF-12",
"referenceNumber": "20260101-AU-XXXXXXXX-XXXX-XX",
"status": "sent",
"invoiceNumber": "FV/2026/01/001"
}
| Field | Type | Description |
|---|---|---|
mode | string | Always online |
ksefNumber | string | null | KSeF number assigned to the invoice (null if still processing) |
referenceNumber | string | KSeF session reference number |
status | string | sent (KSeF number obtained) or pending (still processing) |
invoiceNumber | string | Invoice number from XML (P_2 element) |
Session Reference
The referenceNumber is automatically saved to synced_invoices.session_reference_number by ksef-proxy. This reference is required to download UPO later via the status endpoint.
Response 200 β offline modeβ
{
"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/..."
}
| Field | Type | Description |
|---|---|---|
mode | string | Always offline |
offlineId | string (uuid) | ID of the saved offline invoice |
status | string | signed β invoice signed and queued |
invoiceNumber | string | Invoice number from XML |
qrLinkInvoice | string | null | QR verification URL for the invoice |
qrLinkCertificate | string | null | QR verification URL for the certificate |
Error Codesβ
| Code | Description |
|---|---|
| 400 | Invalid parameters (missing XML, missing mode) |
| 401 | Unauthorized |
| 404 | No active KSeF session (online) or certificate (offline) |
| 409 | Mode conflict β e.g. KSeF available with mode=offline or KSeF unavailable with mode=online. Error message includes details about the outage cause (simulation or real outage). |
| 502 | KSeF error β error message is enriched with outage context if applicable |
Outage Awareness
All REST API endpoints that communicate with KSeF check the outage/simulation flags before making requests. If an outage or simulation is active, the API returns a 409 error with a descriptive message indicating:
- Whether it's a simulation (π§) or a real outage (π¨)
- Whether the administrator has confirmed the situation
- That only offline actions are available
If a KSeF request fails and no flags are set, the error message notes that the administrator has not yet confirmed the cause.