Invoices

The invoice endpoints are the core developer integration surface. They use developer API-key auth and operate in the account, organization, and mode attached to the presented key.

POST/v1/invoices

Submit an invoice

Creates an invoice submission for the organization attached to the authenticated sk_test_... or sk_live_... API key.

Idempotency-Key

Idempotency-Key is required for POST /v1/invoices.

Replaying the same key with the same canonical request returns the stored HTTP status and response body. Reusing the same key with a different canonical request returns idempotency_conflict.

Sandbox scenario

For sk_test_..., the optional Ksef-Sandbox-Scenario header supports:

  • accepted
  • rejected
  • temporary_failure
  • delayed

Ksef-Sandbox-Scenario is ignored for sk_live_....

Sandbox scenarios are deterministic test paths. They do not call real KSeF TEST, DEMO, or production systems.

POST/v1/invoices
curl -X POST "https://api-sandbox.emfakt.com/v1/invoices" \  -H "Authorization: Bearer <YOUR_API_KEY>" \  -H "Content-Type: application/json" \  -H "Idempotency-Key: inv-submit-sandbox-fv-0001" \  -H "Ksef-Sandbox-Scenario: accepted" \  -d '{    "external_id": "sandbox-fv-0001",    "invoice_xml": "<emfakt_sandbox_invoice><scenario>accepted</scenario><external_id>sandbox-fv-0001</external_id></emfakt_sandbox_invoice>",    "metadata": {      "order_id": "ord_123"    }  }'
201 response
{  "id": "inv_2kCYq4m4G7YbUjvH0kC1dg",  "object": "invoice",  "mode": "test",  "status": "processing",  "organization_id": "org_2kCYq4m4G7YbUjvH0kC1dg",  "external_id": "fv-2026-0001",  "created_at": "2026-05-31T10:15:30Z",  "updated_at": "2026-05-31T10:15:30Z",  "ksef_number": null,  "upo_available": false,  "retrying": false,  "next_retry_at": null,  "last_error": null,  "metadata": {    "order_id": "ord_123"  }}
GET/v1/invoices/{id}

Retrieve an invoice

Retrieves the stored invoice object for the account, organization, and mode attached to the developer API key.

This endpoint reads persisted state only. It does not call KSeF, open KSeF sessions, or perform live lookup during the GET request.

Request
curl "https://api-sandbox.emfakt.com/v1/invoices/inv_2kCYq4m4G7YbUjvH0kC1dg" \  -H "Authorization: Bearer <YOUR_API_KEY>"
Accepted invoice response
{  "id": "inv_2kCYq4m4G7YbUjvH0kC1dg",  "object": "invoice",  "mode": "test",  "status": "accepted",  "organization_id": "org_2kCYq4m4G7YbUjvH0kC1dg",  "external_id": "fv-2026-0001",  "created_at": "2026-05-31T10:15:30Z",  "updated_at": "2026-05-31T10:18:30Z",  "ksef_number": "KSEF-TEST-8D7C6B5A4E3F2A1B0C9D",  "upo_available": true,  "retrying": false,  "next_retry_at": null,  "last_error": null,  "metadata": {    "order_id": "ord_123"  }}

Invoice response fields

  • idstring

    Public invoice ID.

  • modetest | live

    Mode resolved from the developer API key.

  • statusreceived | processing | accepted | rejected | failed

    Stable public invoice status.

  • ksef_numberstring | null

    Synthetic sandbox KSeF-like number for accepted test invoices, or official live number after live acceptance when available.

  • upo_availableboolean

    True only when a persisted UPO XML artifact exists for retrieval.

  • retryingboolean

    Whether a background retry is scheduled.

  • next_retry_atstring | null

    Next retry time when retrying is true.

  • last_errorobject | null

    Safe error details when processing is retrying or terminally failed/rejected.

GET/v1/invoices/{id}/upo

Retrieve UPO XML

Returns the persisted UPO XML artifact for an accepted invoice.

For sk_test_..., the XML is deterministic sandbox test data only. It is not a real Ministry of Finance/KSeF UPO and has no legal effect.

For sk_live_..., XML is returned only after live UPO has been retrieved and stored.

This endpoint never performs a live KSeF lookup during the GET request.

Request
curl "https://api-sandbox.emfakt.com/v1/invoices/inv_2kCYq4m4G7YbUjvH0kC1dg/upo" \  -H "Authorization: Bearer <YOUR_API_KEY>" \  -H "Accept: application/xml"
200 sandbox XML response
<?xml version="1.0" encoding="UTF-8"?><emfakt_sandbox_upo>  <object>sandbox_upo</object>  <artifact_type>upo_xml</artifact_type>  <sandbox>true</sandbox>  <test_data>true</test_data>  <invoice_id>inv_2kCYq4m4G7YbUjvH0kC1dg</invoice_id>  <organization_id>org_2kCYq4m4G7YbUjvH0kC1dg</organization_id>  <ksef_number>KSEF-TEST-8D7C6B5A4E3F2A1B0C9D</ksef_number>  <accepted_at>2026-05-31T10:18:30Z</accepted_at>  <available_at>2026-05-31T10:18:30Z</available_at>  <notice>Product-owned simulated sandbox artifact for developer testing only. Not valid for tax or production use.</notice></emfakt_sandbox_upo>

UPO unavailable

received, processing, rejected, failed, accepted-without-UPO, and accepted-with-UPO-retry-pending invoices return upo_not_available.

409 response
{  "error": {    "type": "invalid_request_error",    "code": "upo_not_available",    "message": "The invoice UPO artifact is not available for this invoice.",    "param": null,    "request_id": "req_0Y9a6cW9xQz9xwWzYxA0fY",    "retryable": true  }}

Common invoice errors

  • missing_idempotency_key
  • invalid_idempotency_key
  • idempotency_conflict
  • invalid_invoice_xml
  • invalid_metadata
  • invalid_sandbox_scenario
  • live_mode_disabled
  • live_ksef_credentials_missing
  • upo_not_available