Tryb sandbox i live

Sandbox służy do budowania i testowania integracji bez wysyłania faktur do KSeF. Tryb live umożliwia rzeczywistą komunikację z KSeF i wymaga osobnej konfiguracji oraz poświadczeń organizacji.

Żądanie sk_test_... to lokalna symulacja sandboxa. Przydaje się do testowania integracji, ale nie jest oficjalną wysyłką do KSeF TEST, DEMO ani produkcyjnego.

Scenariusze sandboxa

Ksef-Sandbox-Scenario dotyczy wyłącznie wysyłek faktur kluczem sk_test_....

Obsługiwane wartości:

  • accepted

    Scenariusz domyślny. Brak nagłówka Ksef-Sandbox-Scenario oraz jawne accepted to na potrzeby idempotentności to samo żądanie.

  • rejected

    Deterministycznie finalizuje fakturę w sandboxie jako rejected.

  • temporary_failure

    Planuje ponowienie po pierwszej ponawialnej awarii przetwarzania w sandboxie. Kolejna zaplanowana próba domyślnie kończy się sukcesem, chyba że wyczerpano liczbę ponowień.

  • delayed

    Scenariusz delayed symuluje opóźnione przetwarzanie faktury w sandboxie: faktura pozostaje w statusie processing przez skonfigurowany czas, a po jego upływie finalizuje się tak jak accepted, z testowym numerem KSEF-TEST-... i symulowanym UPO.

Nagłówek scenariusza sandboxa
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 '{ ... }'

Tryb live

Aktualnie niedostępny.

Poświadczenia live

Tryb live sk_live_... będzie wymagał zapisanych poświadczeń KSeF dla organizacji skonfigurowanych przez Control Plane.

Jeśli organizacja nie ma zapisanego poświadczenia TOKEN, API zwraca 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  }}

UPO w sandboxie

Przyjęte faktury w trybie testowym otrzymują symulowany artefakt UPO XML sandboxa.

To XML jest wyłącznie deterministycznymi danymi testowymi. Nie jest prawdziwym UPO Ministerstwa Finansów/KSeF, nie ma skutków prawnych i nie wolno go traktować jako prawnie ważnego dowodu przetworzenia w KSeF.