Developer API emfakt

Developer API umożliwia wysyłanie faktur, sprawdzenie ich stanu i pobranie UPO XML. Ten przewodnik obejmuje podstawowy deweloperski flow: uwierzytelnienie, wysłanie faktury w sandboxie, odpytywanie o wynik i pobranie UPO, gdy jest dostępne.

Adres bazowy

Aktualna publiczna wersja API to 1.0.0.

API sandboxa jest dostępne pod adresem:

Adres bazowy
https://api-sandbox.emfakt.com/v1

Wszystkie przykłady w tym przewodniku korzystają z tego adresu bazowego.

Request-Id

Każda odpowiedź publicznego API zawiera generowany przez serwer nagłówek odpowiedzi Request-Id — na potrzeby wsparcia i diagnostyki.

Wartości Request-Id przesłane przez klienta są ignorowane. W przypadku potrzeby zgłoszenia nieudanego żądania, podaj wartość zwróconą przez API.

Nagłówek odpowiedzi
Request-Id: req_0Y9a6cW9xQz9xwWzYxA0fY

Obszary uwierzytelniania

emfakt ma dwa odrębne obszary uwierzytelniania.

  • Control Plane APItoken dostępu JWT

    Używany do konfiguracji i operacji właściciela: tworzenia konta, logowania, organizacji oraz zarządzania deweloperskimi kluczami API.

  • Developer APIdeweloperski klucz API

    Używany przez zewnętrzne integracje. Podstawowe wywołania faktur korzystają z Authorization: Bearer sk_test_... w trybie sandbox lub Authorization: Bearer sk_live_... w trybie live, gdy ten zostanie uruchomiony.

Tryby klucza API

Klucze sk_test_... zapewniają deterministyczne zachowanie sandboxa. Wysłanie faktury w sandboxie odbywa się lokalnie w produkcie i nie wywołuje prawdziwych systemów KSeF TEST, DEMO ani produkcyjnych.

sk_live_... oznacza klucz API przeznaczony do komunikacji z produkcyjnym środowiskiem KSeF. Tryb live nie jest obecnie dostępny i zostanie uruchomiony niebawem.

Podstawowy flow

Dokumentacja opisuje pierwszą ścieżkę integracji faktur:

  1. Utworzenie lub uzyskanie deweloperskiego klucza API.
  2. Wysłanie faktury w środowisku sandbox za pomocą POST /v1/invoices.
  3. Odpytanie GET /v1/invoices/{id} o status.
  4. Pobranie utrwalonego UPO XML z GET /v1/invoices/{id}/upo, gdy upo_available ma wartość true.

Zacznij od Quickstart, a następnie przeczytaj Uwierzytelnianie, Idempotentność i Faktury.

Pozostałe obszary API

Poza deweloperskim przepływem faktur API udostępnia endpointy konfiguracyjne i zarządcze Control Plane oraz model webhooków. Zobacz Webhooki i zdarzenia - doręczanie zdarzeń, katalog zdarzeń i rejestry doręczeń.

W obecnej publicznej powierzchni nie ma publicznego API do listowania ani odtwarzania zdarzeń.