Dokumentacja API – KSeF Service

Wersja: v1

1. Wysyłka faktury do KSeF

POST /api/sendInvoice.php

Request (JSON lub multipart/form-data)

{
  "client_guid": "string",        // identyfikator klienta
  "invoice_xml": "string",        // treść faktury FA(3) jako base64 lub surowy XML
  "certificate_pfx_base64": "string|null",  // jeśli klient wysyła certyfikat przy żądaniu
  "cert_password": "string|null", // hasło do certyfikatu (jeśli podawany)
  "env": "test"|"prod"            // środowisko: testowe lub produkcyjne
}

Alternatywnie możesz użyć formularza multipart/form-data z polami:

invoice_file – plik .xml
certificate_file – plik .pfx (jeśli podajesz certyfikat)
cert_password – hasło do certyfikatu
client_guid, env

Response (JSON)

{
  "status": "ok" | "error",
  "message": "string",           // komunikat w przypadku error
  "ksef_number": "string|null",
  "reference_number": "string|null",
  "upo_base64": "string|null",   // UPO zakodowane base64
  "upo_url": "string|null",      // link do pobrania UPO (jeśli masz system plików)
  "qr_png_base64": "string|null" // opcjonalnie: QR code PNG base64
}

Przykład:

{
  "status": "ok",
  "ksef_number": "2025/00001234",
  "reference_number": "abc12345",
  "upo_base64": "UE9HVF9ERVRFQ0hfLi4u",
  "qr_png_base64": "iVBORw0KGgoAAAANSUhEUgAA..."
}

2. Pobranie statusu / UPO / danych faktury

GET /api/getInvoice.php

Parametry query string:

client_guid – Twój identyfikator
invoice_internal_id – Twój numer faktury lub identyfikator nadany przy wysyłce

Response

{
  "status": "ok" | "error",
  "message": "string",
  "ksef_number": "string|null",
  "reference_number": "string|null",
  "upo_base64": "string|null",
  "sent_at": "string|null",      // timestamp
  "updated_at": "string|null",   // timestamp ostatniej zmiany
  "raw_invoice_xml": "string|null" // oryginalne XML faktury
}

Umożliwia pobranie UPO, zmiennej z numerem KSeF, oraz — jeśli chcesz — surowego XML faktury.

3. Eksport faktur

GET/POST /api/exportInvoices.php

Uprawniony klient może eksportować swoje faktury z KSeF — JSON / CSV / XML.

Request (opcjonalnie)

{
  "client_guid": "string",
  "from_date": "YYYY-MM-DD",  // opcjonalnie — filtr od daty
  "to_date": "YYYY-MM-DD",    // opcjonalnie — filtr do daty
  "format": "json" | "csv" | "xml"
}

Response

- dla JSON: `application/json`, tablica obiektów faktur, każda z polami: `invoice_id`, `ksef_number`, `reference_number`, `upo_base64`, `sent_at`, `updated_at` - dla CSV / XML: plik do pobrania

4. Autoryzacja i bezpieczeństwo

Każde żądanie API musi zawierać nagłówek lub parametr:

Client-GUID – Twój identyfikator klienta (przydzielany przy rejestracji)
Dla dodatkowego bezpieczeństwa — klucz API / podpis (opcjonalnie w przyszłości)

Jeśli wysyłasz plik `.pfx`, musi być on zaszyfrowany (lub przesyłany przez HTTPS), a hasło do certyfikatu przekazane w parametrze `cert_password`. Serwer nigdy nie zapisuje certyfikatu jeśli żądanie było w trybie „jednorazowym”.

5. Kody błędów

Kod	Opis
400	Niepoprawny request — brak wymaganych pól / błędny format XML / JSON
401	Brak lub niepoprawny Client-GUID / brak autoryzacji
422	Walidacja faktury nie powiodła się (XSD / schema error)
500	Błąd serwera / błąd połączenia z KSeF

6. Uwagi

Wszystkie endpointy obsługują CORS – możesz dzwonić z przeglądarki lub innego front-endu.
Pliki `.pfx` traktuj jako wrażliwe — zawsze używaj HTTPS.
Zalecamy regularne aktualizacje schematów XML KSeF; nasz backend automatycznie wspiera nowe wersje, jeśli tylko udostępnisz aktualizację.

Kontakt / Wsparcie

W razie problemów lub pytań — skontaktuj się: kontakt@audev.pl