KSeF Test, Demo, and Production Environments: A Safe Guide

KSeF has three public API environments with different jobs. TEST is a shared integration sandbox for synthetic data and failure simulation. DEMO uses real identity and permissions for production-like validation, but invoice content must stay fictitious. PRD issues legally effective invoices. A safe integration isolates every credential and record, then promotes one pinned build through those boundaries.

This guide was checked against Ministry of Finance and CIRF documentation on August 28, 2026. KSeF rolls API changes out by environment, so treat the official changelog and each environment’s live OpenAPI contract as release inputs. This is technical guidance, not tax or legal advice.

How do KSeF TEST, DEMO, and PRD differ?

The difference is not just the hostname. Each environment has its own trust model, data rules, credentials, API release, and consequence of a successful submission.

These boundaries come from the Ministry’s support for integrators and CIRF’s KSeF environment matrix. The aliases are worth learning because official material uses both: TEST is also called TE or the integration environment, while DEMO is also called TR or pre-production.

One rule survives every version change: never promote data or credentials between environments. Promote tested code and configuration structure, then provision the target environment independently.

How should you configure KSeF environment endpoints?

Select an allowlisted environment profile, not an arbitrary URL. A production process should never accept a base host from a request parameter, invoice field, or mutable database setting.

A small immutable map keeps the choice visible:

KSEF_ENVIRONMENTS = {
  test: {
    api_base: "https://api-test.ksef.mf.gov.pl/v2",
    docs: "https://api-test.ksef.mf.gov.pl/docs/v2"
  },
  demo: {
    api_base: "https://api-demo.ksef.mf.gov.pl/v2",
    docs: "https://api-demo.ksef.mf.gov.pl/docs/v2"
  },
  production: {
    api_base: "https://api.ksef.mf.gov.pl/v2",
    docs: "https://api.ksef.mf.gov.pl/docs/v2"
  }
}.freeze

profile = KSEF_ENVIRONMENTS.fetch(ENV.fetch("KSEF_ENV").to_sym)

That is only the public half of the profile. Keep the following values separate as one environment-bound unit:

• certificate and private-key reference;
• KSeF token, access token, and refresh token storage;
• KSeF public-key cache and the selected publicKeyId;
• database or object-storage namespace for XML and UPO;
• queue, retry budget, and rate-limit coordinator;
• dashboards, alerts, and log labels;
• a production enablement flag and kill switch.

The Ministry’s production credential notice is explicit: production keys and KSeF credentials belong to PRD. A token, certificate, or encryption key from TEST or DEMO is not a production credential. The public-key guide also documents rotation, so do not cache one global key across all three environments.

Do not rewrite URLs returned by KSeF

KSeF can return signed upload or download URLs. CIRF states that their hosts match the environment called. Validate a returned host against the selected environment’s allowlist, then use the complete URL as returned. Do not replace its host, prepend /v2, or attach a production bearer token to a storage URL.

This sounds minor until a helper designed for normal API routes receives a signed object-storage URL. Treat API bases and returned resource URLs as two distinct types.

What should you test in the KSeF TEST environment?

TEST is where you prove that the client handles contracts and failures with synthetic data. It is deliberately easier to enter than production, which is why it cannot prove that production identity or permissions will work.

TEST accepts self-signed certificates and simulated credentials. Its /testdata/* endpoints can create test people, entity structures, and permissions, enable attachment scenarios, block a context, shorten a certificate’s validity, and change limit profiles. CIRF publishes runnable examples in the test-data scenarios guide.

Use those controls to exercise states that are expensive to trigger naturally:

1. valid and invalid authentication;
2. permission denied after a credential succeeds;
3. certificate expiry and rotation;
4. online and batch submission failures;
5. HTTP 429 handling and a shared quota pause;
6. process restart while an invoice is still asynchronous;
7. unknown response fields and new warning headers;
8. UPO retrieval after the original worker disappears.

The goal is not a single green happy path. It is evidence that the integration reaches a known state when KSeF accepts, delays, rejects, throttles, or changes a response additively.

Why real data is unsafe in TEST

TEST is not a private tenant. Because multiple integrators can authenticate in the same synthetic company context, data can be visible outside your test run. CIRF tells integrators to use random identifiers and no real entity data.

That warning covers more than names. Do not send real invoice numbers, addresses, line descriptions, bank details, email addresses, customer references, or production XML with only the NIP swapped. Generate a complete synthetic fixture set. Recreate it when needed because TEST data is deleted periodically and no current official source promises a retention interval.

An environment guard should reject production customer IDs and known production invoice prefixes before serialization. That check belongs in application code, not in a release checklist someone can skip.

What should you validate in KSeF DEMO?

DEMO tests the parts that TEST intentionally fakes: real authentication identity, actual ownership records, and real permission chains. It is the final rehearsal for a production candidate, not a second sandbox for arbitrary identities.

The Ministry’s DEMO launch notice says DEMO uses actual authentication data and permissions comparable to production. This is where you find the gap between “our XAdES code works” and “this certificate can act for this taxpayer with the required permission.” The KSeF authentication guide covers that flow in detail.

DEMO should answer five release questions:

• Can the real organization authenticate with its intended certificate path?
• Do the intended operators and systems have the actual KSeF permissions?
• Does the release candidate work against production-supported invoice formats?
• Does it remain stable under production-like request limits?
• Can it resume status polling and evidence capture after a restart?

Use exactly the build you plan to release. Avoid DEMO-only branches and manual patches. If a configuration difference is required, it should live in the environment profile, not in code that changes behavior silently.

Real login does not mean real invoice content

DEMO combines real identity with fictitious invoice payloads. The Ministry says invoices there have no legal effect and are later deleted. It also says the environment can contain migrated or production-origin data that is not anonymized and receives production-grade protection.

Both facts can be true. Your test input must be fictional, while data already resident in DEMO may still be sensitive. Apply production access controls and log redaction. Do not describe DEMO as a database of harmless sample records.

Why is a PRD smoke test still a real invoice?

PRD has no harmless “test invoice” mode. If KSeF accepts the document and assigns a KSeF number, the invoice enters legal circulation.

The Ministry’s KSeF 2.0 handbook, part II warns that an accidental test invoice in production can create VAT consequences. Article 108(1) of Poland’s VAT Act is blunt: an issuer that shows VAT on an invoice is obliged to pay it.

Your first issuing canary must therefore be a genuine business transaction. Before it runs:

• provision production credentials in PRD rather than copying them from DEMO;
• verify the taxpayer context and permissions with non-issuing calls;
• confirm the invoice is real, approved, and ready to enter the books;
• start with an empty or controlled queue;
• have an operator watching status, KSeF number, and UPO;
• know how to stop new submissions without losing accepted references.

Never build automatic fallback from TEST or DEMO to PRD. Never let a retry change the selected environment. Persist the environment beside every session reference, invoice reference, KSeF number, and UPO object key so reconciliation cannot cross the boundary.

The UPO and status-polling guide explains the evidence that belongs with each accepted invoice. An HTTP 202 or a session reference is not final acceptance.

How does KSeF API version drift affect promotion?

TEST can run ahead of DEMO and PRD. That gives you advance notice of a change, but it also means one green environment can exercise a different contract from the target.

The official changelog records API 2.7.1 for TEST on August 26, 2026, with DEMO and PRD deployments scheduled for September 15 and September 23. At the check date, 2.6.1 was the newest release recorded as deployed to PRD. The exact snapshot will age; the deployment pattern is the lasting lesson.

Before every promotion, record:

Do not generate a client from the repository’s main branch and assume it matches production. Pin the contract you tested, tolerate documented additive response fields, and run compatibility tests against the target environment before deployment.

Rate limits demonstrate why this matters. Older official prose said TEST defaults were ten times production. The later API 2.5.0 changelog says TEST defaults were aligned with PRD, while TEST kept its simulation endpoints. The safe rule is to inspect effective limits at runtime and follow the dedicated KSeF retry guide, not copy a multiplier into code.

What is a safe KSeF promotion checklist?

Promote evidence, not assumptions. The following checklist is an engineering synthesis, not a Ministry-mandated procedure.

In local and CI tests

• Pin FA(3) schemas and deterministic fixtures.
• Verify the exact bytes you hash, encrypt, and submit.
• Keep environment selection outside invoice data.
• Reject any host outside the three official allowlists.
• Test unknown fields and interrupted asynchronous work.

In TEST

• Create fresh synthetic identities and payloads.
• Exercise success, rejection, throttling, expiry, and restart paths.
• Confirm no production identifiers or secrets reach logs or storage.
• Capture the TEST OpenAPI version used by the run.

In DEMO

• Authenticate with the intended real organizational identity.
• Verify the actual permission graph.
• Submit fictitious or anonymized invoice content only.
• Run with production-like limits and the release candidate.
• Reconcile status, references, and UPO after a forced restart.

Before and during PRD cutover

• Compare the live PRD OpenAPI with the pinned client contract.
• Provision fresh PRD certificates, tokens, permissions, and public-key cache.
• Enable guards that block synthetic tenants and fixtures.
• Verify non-issuing operations first.
• Submit one genuine invoice, then reconcile its final status and UPO.
• Increase volume gradually while watching 429, failures, and queue age.

Keep the FA(3) structure guide beside this checklist. Passing XSD and TEST confirms XML shape and client behavior, not the tax treatment or legal completeness of a real invoice. For failures, use the KSeF validation troubleshooting guide without replaying an ambiguous submission blindly.

How does KSeF Kit handle the environment boundary?

The safest environment switch is the one your team does not have to maintain. KSeF Kit is a separate product for teams whose invoice source is Stripe. It maps finalized Stripe invoices to FA(3), submits them, waits for the KSeF result, stores the UPO, and writes the KSeF number back to the source record.

Its public connection guide documents TEST and production setup. That makes it a focused build-versus-buy option for Stripe billing, not a claim to cover every accounting system, invoice type, or tax decision.

Whether you use a managed path or your own client, keep the same boundary: synthetic work in TEST, real identity with fictional invoices in DEMO, and only genuine approved invoices in PRD. Promote code through the environments. Never promote their secrets or data.