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.

Источник