Faktury

Te endpointy służą do wysyłania faktur oraz sprawdzania stanu ich przetwarzania. Każde żądanie jest wykonywane w kontekście konta, organizacji i trybu przypisanego do użytego klucza API.

POST/v1/invoices

Wyślij fakturę

Tworzy wysyłkę faktury dla organizacji powiązanej z uwierzytelnionym kluczem API sk_test_... lub sk_live_....

Idempotency-Key

Idempotency-Key jest wymagany dla POST /v1/invoices.

Powtórzenie tego samego klucza z tym samym żądaniem zwraca ten status HTTP i treść odpowiedzi. Ponowne użycie tego samego klucza z innym żądaniem zwraca idempotency_conflict.

Scenariusz sandboxa

Dla sk_test_... opcjonalny nagłówek Ksef-Sandbox-Scenario obsługuje:

  • accepted
  • rejected
  • temporary_failure
  • delayed

Ksef-Sandbox-Scenario jest ignorowany dla sk_live_....

Scenariusze sandboxa to deterministyczne ścieżki testowe. Nie wywołują prawdziwych systemów KSeF TEST, DEMO ani produkcyjnych.

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"    }  }'
Odpowiedź 201
{  "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}

Pobierz fakturę

Pobiera zapisany obiekt faktury dla konta, organizacji i trybu powiązanego z deweloperskim kluczem API.

Ten endpoint odczytuje wyłącznie utrwalony stan. Podczas żądania GET nie wywołuje KSeF, nie otwiera sesji KSeF ani nie wykonuje odpytania na żywo.

Żądanie
curl "https://api-sandbox.emfakt.com/v1/invoices/inv_2kCYq4m4G7YbUjvH0kC1dg" \  -H "Authorization: Bearer <YOUR_API_KEY>"
Odpowiedź dla przyjętej faktury
{  "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"  }}

Pola odpowiedzi faktury

  • idstring

    Publiczny identyfikator faktury.

  • modetest | live

    Tryb ustalony na podstawie deweloperskiego klucza API.

  • statusreceived | processing | accepted | rejected | failed

    Stabilny publiczny status faktury.

  • ksef_numberstring | null

    Syntetyczny, przypominający KSeF numer w sandboxie dla przyjętych faktur testowych lub oficjalny numer live po przyjęciu w trybie live, gdy jest dostępny.

  • upo_availableboolean

    Ma wartość true tylko wtedy, gdy istnieje utrwalony artefakt UPO XML do pobrania.

  • retryingboolean

    Czy zaplanowano ponowienie w tle.

  • next_retry_atstring | null

    Czas kolejnego ponowienia, gdy retrying ma wartość true.

  • last_errorobject | null

    Bezpieczne szczegóły błędu, gdy przetwarzanie jest ponawiane albo trwale nieudane/odrzucone.

GET/v1/invoices/{id}/upo

Pobierz UPO XML

Zwraca utrwalony UPO XML dla przyjętej faktury.

Dla sk_test_... XML to wyłącznie deterministyczne dane testowe sandboxa. Nie jest prawdziwym UPO Ministerstwa Finansów/KSeF i nie ma skutków prawnych.

Dla sk_live_... XML jest zwracane dopiero po pobraniu i zapisaniu UPO live.

Ten endpoint nigdy nie wykonuje odpytania KSeF na żywo podczas żądania GET.

Żądanie
curl "https://api-sandbox.emfakt.com/v1/invoices/inv_2kCYq4m4G7YbUjvH0kC1dg/upo" \  -H "Authorization: Bearer <YOUR_API_KEY>" \  -H "Accept: application/xml"
Odpowiedź 200 XML (sandbox)
<?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 niedostępne

Faktury received, processing, rejected, failed, a także przyjęte bez UPO oraz przyjęte z oczekującym ponowieniem pobrania UPO zwracają upo_not_available.

Odpowiedź 409
{  "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  }}

Częste błędy faktur

  • 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