Integrating Poland's KSeF 2.0 from Python: 8 pitfalls

说明与用途

Python 与 KSeF 2.0 集成指南，列出 8 个常见陷阱及解决方案，面向测试环境。

问题

Python developers need to issue invoices to Poland's mandatory KSeF 2.0 system, but the official docs are Polish and examples are in C#/Java, making integration error‑prone.

结果

The guide enables developers to authenticate asynchronously, avoid retry pitfalls, generate compliant test certificates, and submit invoices to KSeF’s test environment reliably.

工作流

• 1. Request authentication challenge via /auth/challenge
• 2. Sign the challenge with an XAdES certificate and POST to /auth/xades-signature
• 3. Poll /auth/{referenceNumber} until status 200
• 4. Redeem the temporary token once via /auth/token/redeem to obtain an access token
• 5. Create a self‑signed XAdES certificate with VATPL‑<NIP> in organizationIdentifier
• 6. Convert a neutral invoice to EN16931 UBL and FA(3) XML
• 7. Submit FA(3) XML to /invoices via the test environment
• 8. Retrieve the official receipt (UPO) and verify success

证据

Submitting your signed authentication request does not log you in. It returns 202 with a reference number and a temporary token, and authentication carries on in the background.

来源

The TEST environment, and only TEST, accepts self‑signed certificates for XAdES.

来源