Skip to main content

Poland — KSeF Sandbox Onboarding

Operational guide for getting test credentials at the KSeF (Krajowy System e-Faktur) sandbox.

PropertyValue
AuthorityMinistry of Finance (Ministerstwo Finansów)
Sandbox base URLhttps://ksef-test.mf.gov.pl/api/
CostFree for token mode; ~€100-300/yr if you need qualified e-signature
Time to provision1-3 days for token; 2-4 weeks for qualified e-sig
Identity requiredPolish NIP (10-digit tax number)

Steps​

  1. Register at the KSeF test portal with your NIP.
  2. Choose authentication mode:
    • Token mode (easiest): generate from the portal; no e-sig needed. Use this for sandbox/CI.
    • Qualified electronic signature or trusted profile (Profil Zaufany): needed for production prod-grade integrations.
  3. Generate a session token via POST /api/online/Session/InitToken. Adapter at rust/adapters/poland/src/auth.rs handles the token-exchange flow.
  4. Validate with a small invoice submission via POST /Invoice/Send.

GitHub secrets to set​

PL_KSEF_NIP
PL_KSEF_TOKEN

Gotchas​

  • Sandbox runs FA(2) today. FA(3) becomes mandatory 2026-10-01. During the overlap window (mid-2026 to 2026-09-30), sandbox-nightly should test both schemas. The adapter has a feature flag for this.
  • Token has a session lifetime. Adapter's runtime.rs already handles refresh.
  • Mandatory rollout has slipped multiple times. Verify the current sandbox state matches the production rollout date — KSeF's calendar has been a moving target.
  • Dual-numbering: issuer's P_2 is what goes on the printed invoice; KSeF assigns numerKSeF post-acceptance. Sandbox tests should verify both fields are correctly persisted (already in fiscal_id + fiscal_id_upstream per fi-9ss).

Non-resident path​

Polish NIP is required for KSeF taxpayer registration. There is no foreign-software-vendor shortcut here — the auth model assumes a NIP-bearing entity.

  • Foreign legal entities can apply for a NIP via the NIP-2 form, but it's a longer process — 4-6 weeks typical.
  • Standard route is a Polish accountant or fiscal representative who handles NIP issuance + token generation on the platform's behalf. Budget ~€100-300/month.
  • Cheapest dev path: partner with a Polish accountant for NIP + KSeF token issuance. ~2-4 weeks.
  • Production. For serving Polish merchants, the merchants themselves register on KSeF; the platform doesn't need a Polish entity. The platform-as-intermediary model keeps us out of NIP-bearing scope. For VAT-bearing transactions on the platform's own books, a Polish branch or VAT representative is needed.
  • Research doc: poland.md
  • Adapter crate: rust/adapters/poland/
  • Sandbox tests: rust/adapters/poland/tests/sandbox.rs