Wprowadzenie

info

Jeżeli jesteś zainteresowany korzystaniem i dostępem do REST API usługi Fast KSeF prosimy o kontakt z naszym pracownikiem dostępnym pod adresem E-mail: [kontakt@fast-ksef.pl].

Fast KSeF REST API

REST API umożliwia integrację systemów zewnętrznych z Krajowym Systemem e-Faktur (KSeF) za pośrednictwem platformy FastKSeF.

Architektura

Klient  ──────▶  REST API  ──────▶  ksef-proxy (Edge Function)  ──────▶  API KSeF
                  │                        │
                  ▼                        ▼
             Logika lokalna            PostgreSQL (sync DB)
             - walidacja               - referencje sesji
             - format daty             - powiązania faktur ROZ↔ZAL,
             - generacja PDF           - korygujące faktury,
             - generowanie QR          - metadane synchronizacji
             - kodowanie base64        - obsługa awarii/symulacji                     

REST API jest cienkim wrapperem — nigdy nie komunikuje się z KSeF bezpośrednio. Wszystkie operacje KSeF delegowane są do ksef-proxy, który pełni podwójną rolę:

1. Proxy HTTP — jedyny punkt komunikacji z API KSeF, obsługujący uwierzytelnianie, odświeżanie tokenów i weryfikację statusu połączenia.
2. Synchronizator DB — utrzymuje spójność danych pomiędzy KSeF a lokalną bazą:
   • Przypisuje session_reference_number do synced_invoices i offline_invoices podczas wysyłki/sprawdzania statusu
   • Wiąże faktury zaliczkowe (ROZ ↔ ZAL) przez advance_groups / advance_group_invoices
   • Wiąże faktury korygujące (KOR ↔ oryginał) przez invoice_corrections
   • Aktualizuje invoice_sync_meta podczas synchronizacji

REST API odpowiada wyłącznie za logikę lokalną: walidację wejścia, formatowanie dat, kodowanie/dekodowanie base64, generowanie PDF po stronie serwera (ksef-pdf-generator) i generowanie kodów QR.

Autoryzacja

Wszystkie endpointy (z wyjątkiem GET /status i GET /openapi.json) wymagają uwierzytelnienia Basic Auth:

Authorization: Basic base64(email:hasło)

warning

Użytkownik musi posiadać rolę admin lub technical.

Środowiska KSeF

Parametr {environment} przyjmuje wartości:

Wartość	Opis
test	Środowisko testowe KSeF
demo	Środowisko demo KSeF
prod	Środowisko produkcyjne KSeF

Format dat

Daty zwracane przez API są typu string. Format jest konfigurowalny kluczem api.date.format w tabeli system_config (domyślnie: yyyy-MM-dd HH:mm:ss).

Śledzenie referencji sesji

Podczas wysyłki faktur lub sprawdzania statusu, ksef-proxy automatycznie zapisuje session_reference_number w synced_invoices (online) i offline_invoices (batch). Ta referencja jest wymagana do późniejszego pobrania UPO.

Swagger UI

Interaktywna dokumentacja Swagger UI jest dostępna dla uprawnionych użytkowników pod adresem:

GET /swagger

Specyfikacja OpenAPI 3.0 jest dostępna pod:

GET /openapi.json