Poland and KSeF
Preview only: Space Invoices’ KSeF integration is not yet released or production-certified. Production submissions are unavailable pending release review. This guide describes the candidate scope and behavior.
Polish entities default to PLN and pl-PL. The preview covers online FA(3) standard invoices and linked reducing corrections in PLN for active-VAT Polish B2B sellers. KSeF obligation is modeled independently of the connection switch. Configure a sandbox entity to submit to KSeF TEST; production submission is not available in this preview.
Configure access
Supply a valid Polish NIP on the entity. The API normalizes an optional PL prefix, spaces and hyphens, validates the checksum, and stores ten digits. Customer NIP validation follows the customer’s country, independently of the seller. Ordinary invoicing permits an omitted NIP; KSeF requires one.
All setup routes require entity administration access and a bearer token. Send x-entity-id on document requests.
| Method and route | Body | Result |
|---|---|---|
GET /entities/{id}/ksef | None | Setup and release-switch state |
PUT /entities/{id}/ksef/credentials | {"environment":"test","token":"<KSEF_TOKEN>"} | Stores an encrypted, write-only token |
PUT /entities/{id}/ksef | {"enabled":true} | Authenticates the token and enables submission |
PUT /entities/{id}/ksef | {"enabled":false} | Disables new submissions |
DELETE /entities/{id}/ksef/credentials | None | Removes credentials after KSeF is disabled |
The token needs InvoiceWrite and InvoiceRead. Credentials are bound to the current NIP and immutable entity environment; environment mismatches return 422. Generic entity updates ignore protected settings.ksef. Changing the NIP requires disabling KSeF and completing pending reserved submissions, including UPO retrieval. Token removal has the same pending-work restriction (409). Enabling verifies the exact token’s active status, NIP and InvoiceRead/InvoiceWrite permissions with KSeF. Replacing a token while enabled or while reserved submissions are pending performs the same checks before saving; failure preserves the previous credential. Local preparation failures without a reserved XML hash do not block credential cleanup.
credential_configured means a matching encrypted token exists. submission_available reflects the environment’s operational release switch. The modeled obligation is required by default, regardless of enabled; an entity admin may record obligation: "exempt" with an exemption_reason of at least 10 characters. This records the entity’s declaration; it is not an automated legal determination. Enabling fails with 422 when the switch is off or authentication fails. Omitted or null enabled leaves settings unchanged. Disabling KSeF does not bypass the modeled obligation or unlock reserved submissions.
In the app or embed, open Settings → KSeF to store a token and enable submissions. Invoice and credit-note views show authority status, eligible retry actions and UPO download. Disabling new submissions or the operational switch preserves status and receipt recovery for existing submissions. Ordinary B2C invoicing remains available outside KSeF submission when the customer is explicitly marked with is_end_consumer: true; those invoices do not enter the KSeF submission flow.
Issue an invoice or correction
Create an invoice through POST /invoices, or create a draft and finalize it through the existing document flow. Issued supported B2B documents submit automatically when KSeF is enabled. Drafts do not submit. KSeF submission is limited to PLN, active-VAT standard invoices and linked reducing credit notes; advances, offline24, foreign currency and domestic gross totals above PLN 15,000 are outside the supported scope and are rejected before final invoice persistence. This is a conservative implementation limit, not a claim that every higher-value invoice legally requires split payment. When the modeled obligation is required, disabling KSeF does not permit a final Polish B2B invoice to bypass submission.
Provide complete seller and buyer names, addresses, country codes and tax identifiers. Use explicit tax rates. Cross-border lines require classification: "product" for goods or "service" for services and zero VAT. The mapper distinguishes intra-EU goods, exports and foreign services; it does not guess a tax treatment from an unclassified line. Domestic supported rates are 23%, 22%, 8%, 7%, 5% and explicit 0%.
Create a reducing correction through POST /credit-notes with linked_documents: ["<INVOICE_ID>"]. It must reference exactly one accepted invoice. The FA(3) correction includes the original KSeF number; stored positive credit-note amounts become negative correction amounts in XML and Polish output.
Invoice and credit-note responses expose server-managed ksef lifecycle state. Do not send it in create or update requests.
| State | Meaning |
|---|---|
reserved / processing | The submission reservation is durable; XML preparation is in progress |
dispatching | Sending started; its outcome requires reconciliation |
submitted | KSeF returned an invoice reference; acceptance is pending |
accepted | The authority invoice and its hash were verified |
rejected | KSeF rejected this submission; automatic resending is blocked |
retryable_error | Preparation failed before invoice dispatch |
Status, receipts and delivery
| Method and route | Purpose |
|---|---|
GET /invoices/{id}/ksef | Read status and reconcile pending authority results |
POST /invoices/{id}/ksef/submit | Submit or resume the existing reservation; no body |
POST /invoices/{id}/ksef/recover | Return a definitively unaccepted document to draft after an audited proof check; no body |
GET /invoices/{id}/ksef/upo | Download the verified UPO XML |
KSeF credit notes affect automatic invoice settlement and revenue reports only after verified acceptance. Pending and rejected corrections do not reduce the original invoice balance or reported revenue. Acceptance processing retries safely without applying the same credit twice. Use positive amounts for reducing corrections; increasing or mixed-direction corrections are outside this integration’s supported scope, including through /credit-notes/custom and draft finalization.
The same operations exist under /credit-notes/{id}/ksef. Status polling is rate limited. Background reconciliation uses the existing e-invoicing processing schedule. UPO may arrive after acceptance; its download returns 409 until available.
Repeated submit calls reuse the reservation. Interrupted dispatches are reconciled against the saved session and invoice hash; they are never blindly resent. A duplicate response alone does not establish acceptance. Reserved invoices cannot be edited or voided; use a linked credit note. Recovery is available for definitive nonacceptance, no-dispatch preparation failures, or a verified empty cancelled session; it archives the prior attempt and returns the document to draft. Accepted and unresolved ambiguous submissions remain locked.
Deliver PDFs through the existing /documents/{id}/pdf endpoint after acceptance. KSeF output contains the accepted number and a verification QR code, including for foreign buyers receiving the PDF outside KSeF. Polish credit notes are titled FAKTURA KORYGUJĄCA. Ordinary Polish date, currency, character and email formatting remains available independently of KSeF.
Scope
This preview covers standard online outgoing PLN B2B invoices and linked reducing corrections for active-VAT sellers. It excludes foreign currency, advances, offline24 and emergency modes, domestic gross totals above PLN 15,000, self-billing, KSeF submission for B2C, VAT RR, attachments, special VAT procedures and advanced corrections. Explicitly marked end-consumer invoices remain available through ordinary invoicing outside KSeF submission. Use applicable tax treatment; an ordinary PDF or stored credential alone is not KSeF acceptance. This preview is not blanket Polish tax-law certification.
The Ministry publishes the KSeF API documentation, including TEST authentication and verification QR rules.