Quickstart

Ścieżka opisuje proces wysłania faktury w trybie sandbox, odczytania jej stanu i pobrania UPO XML, gdy będzie dostępne.

Podsumowanie konfiguracji

Zanim wywołasz deweloperskie API faktur, potrzebujesz testowego deweloperskiego klucza API.

Przepływ konfiguracji wygląda tak:

  1. Utwórz konto w panelu emfakt.
  2. Zaloguj się przez stronę logowania, aby wejść do panelu developera w trybie sandbox.
  3. Utwórz organizację.
  4. Utwórz testowy klucz API.

Te wywołania konfiguracyjne korzystają z API Control Plane. Surowy klucz sk_test_... jest zwracany tylko raz w momencie utworzenia. Przechowuj go bezpiecznie.

Wywołania konfiguracyjne korzystają z API Control Plane i tokena dostępu JWT. Wywołania faktur korzystają z deweloperskiego klucza API, który tworzysz tutaj.

POST/v1/invoices

Wyślij fakturę w sandboxie

Do uwierzytelnienia wykorzystywany jest zwrócony klucz sk_test_..., przekazywany jako token bearer. Każde żądanie wysyłki faktury wymaga również nagłówka Idempotency-Key.

Opcjonalny nagłówek Ksef-Sandbox-Scenario jest dostępny wyłącznie dla wysyłek w trybie testowym. W przypadku jego pominięcia domyślnie używany jest scenariusz accepted.

Wyślij fakturę w sandboxie
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}

Odczytaj stan faktury

Pozwala sprawdzić aktualny status faktury.

Pobierz fakturę
curl "https://api-sandbox.emfakt.com/v1/invoices/inv_2kCYq4m4G7YbUjvH0kC1dg" \  -H "Authorization: Bearer <YOUR_API_KEY>"
Przyjęta faktura w sandboxie
{  "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"  }}
GET/v1/invoices/{id}/upo

Pobierz UPO, gdy jest dostępne

Wywołuj endpoint UPO dopiero wtedy, gdy powyższy endpoint odpytania faktury pokazuje upo_available: true.

Endpoint zwraca wyłącznie XML.

Pobierz UPO XML
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>

Następne kroki

Przeczytaj: