Sandbox and live mode

The Developer API distinguishes deterministic sandbox behavior from deployment-gated live mode. Keep those two modes separate when building and testing integrations.

Sandbox scenarios

Ksef-Sandbox-Scenario applies only to sk_test_... invoice submissions.

Supported values:

  • accepted

    The default scenario. Missing Ksef-Sandbox-Scenario and explicit accepted are the same semantic request for idempotency.

  • rejected

    Deterministically finalizes the sandbox invoice as rejected.

  • temporary_failure

    Schedules a retry after the first retryable sandbox processing failure. The next due attempt succeeds by default unless retry attempts are exhausted.

  • delayed

    Leaves the invoice processing until its due time, then finalizes to accepted.

Sandbox scenario header
curl -X POST "https://api-sandbox.emfakt.com/v1/invoices" \  -H "Authorization: Bearer sk_test_..." \  -H "Content-Type: application/json" \  -H "Idempotency-Key: inv-submit-sandbox-fv-0001" \  -H "Ksef-Sandbox-Scenario: temporary_failure" \  -d '{ ... }'

Live mode

Live mode is not universally available.

A deployment can reject sk_live_... invoice submission with live_mode_disabled.

Live credentials

In a live-enabled deployment, sk_live_... submissions require stored organization KSeF TOKEN credentials configured through the control plane.

If the organization has no stored TOKEN credential, the API returns live_ksef_credentials_missing.

live_ksef_credentials_missing
{  "error": {    "type": "invalid_request_error",    "code": "live_ksef_credentials_missing",    "message": "Live KSeF credentials are not configured for this organization.",    "param": null,    "request_id": "req_0Y9a6cW9xQz9xwWzYxA0fY",    "retryable": false  }}

Sandbox UPO

Accepted test-mode invoices receive a simulated sandbox UPO XML artifact.

This XML is deterministic test data only. It is not a real Ministry of Finance/KSeF UPO, has no legal effect, and must not be treated as legally valid evidence of KSeF processing.