Step-by-step guides for issuing, sending and tracking e-invoices in KSeF with the Notaly API.
The legal invoice in KSeF is the structured FA(3) XML, and the UPO together with the KSeF number are your proof that it was accepted. KSeF keeps the structured invoices it stores for 10 years, so you can retrieve them while your access lasts; locally you should archive the XML, the UPO number and the KSeF number together. Treat the PDF as a readable copy for people, not as the document of record.
KSeF reports problems as exception codes in the response body alongside an HTTP status, and the code — not the HTTP number alone — tells you what actually failed. Common causes are an invalid authentication challenge, an invalid certificate, or an invoice that fails the FA(3) schema and is then reported as not correctly processed. Read the Polish description against the official KSeF code table instead of guessing, because the same numeric code can mean different things in different endpoints.
Moving to KSeF is a data-and-process change, not just an API swap: you need clean party identifiers, an invoice mapping that produces valid FA(3), an authentication method, and a TEST run before production. Working through that short checklist in the sandbox turns the eventual go-live into a configuration change rather than a first attempt.
KSeF offline mode is the Ministry of Finance's contingency for invoicing while the platform is unreachable, and in KSeF 2.0 an offline invoice carries two QR codes: KOD I and KOD II. KOD I is the verification link generated by the issuer from the SHA-256 of the invoice XML and shows "OFFLINE" in place of the KSeF number until acceptance; KOD II is the issuer's verification QR signed with a KSeF certificate of type Offline and labelled CERTYFIKAT. The document must still be submitted to KSeF afterwards, within the window set by the Ministry.
When an invoice is accepted, KSeF returns the UPO (official proof of receipt) and the KSeF number; the readable PDF is a visualisation Notaly generates from the FA(3) data, carrying the official KOD I QR. KOD I and KOD II are two different codes, not two states of one: KOD I is the verification link built by the issuer from the SHA-256 of the XML, and KOD II is the issuer's verification QR, signed with a KSeF certificate of type Offline, added only on an offline invoice.
You test KSeF integration in the TEST environment (api-test.ksef.mf.gov.pl), where every submission has no legal or tax effect. Notaly's sandbox sends to KSeF TEST with the platform's test credentials and gives you three free test invoices, so you can validate your FA(3) XML and the whole flow before going near production.
When you create an invoice, the POST /invoices response returns submitted with a KSeF reference number, and the final decision — accepted or rejected — arrives later. You can verify it by polling GET /invoices/{id}, which re-checks KSeF while the invoice is still submitted, or by listening for the signed status webhook. The UPO and the KSeF number arrive together with the accepted status.
The KSeF TEST environment (api-test.ksef.mf.gov.pl) is the Ministry of Finance's sandbox where you can send FA(3) invoices without touching production data. It uses the same FA(3) schema and the same status flow, so it is the safe place to validate your XML, your authentication and your status handling before going live. Notaly's sandbox maps to KSeF TEST and includes three free test invoices.
A KSeF token is the credential your system uses to authenticate to Poland's KSeF API and open an online session. You generate it in the KSeF portal (or via the API), provide it to your integration — or to Notaly in Connect KSeF — and it lets you submit invoices without a qualified seal. The token authenticates the session; it is not used to sign the invoice.
KSeF accepts two ways to authenticate a session: a KSeF-issued token, or an XAdES signature made with a qualified signature or seal or a KSeF certificate. They are alternatives for the same step — proving who you are before you send an invoice — and in both cases the invoice XML itself is not signed: it is encrypted and sent in the online session. Notaly uses the token, so you do not need a qualified seal.
KSeF decides whether an invoice is accepted asynchronously, so the submit call alone is not the end of the story: Notaly polls KSeF for you and pushes the final result to your endpoint as a signed webhook — invoice.accepted (with the KSeF number and UPO), invoice.rejected, or invoice.error. Each webhook is signed with HMAC and retried with backoff, so you can build reliable order-to-invoice automation without polling yourself.
Create a sandbox account: API key in seconds, 3 free test invoices on KSeF TEST, no credit card.
