Platforma API v1.0

REST API dla integratorów KSeF

Walidacja XML, generator korekt FA(3) i pełna dokumentacja OpenAPI 3.1 - wszystko z jednym tokenem Bearer. Sandbox dla testów, dedykowane wsparcie dla planu API.

Utwórz klucz API OpenAPI 3.1 spec

Bezpieczna autentykacja

Klucze API w formacie nk_(live|test)_*, w bazie tylko skrót SHA-256, szczegółowe scopes, ślad audytu unieważnień i wygaśnięć. Jawną postać klucza widzisz tylko raz.

Sandbox bez limitów

Klucze nk_test_* nie konsumują limitu walidacji/korekt, nie zapisują historii. Testuj integrację bez ryzyka i bez wpływu na limity.

Wysokie limity

Plan API: 600 req/min, 200 000 req/dzień. Walidacja i korekty bez limitu. Webhooks na zdarzenia, retry z exponential backoff (Faza 4).

Quickstart - 3 kroki

Od zera do pierwszego zwalidowanego XML w 5 minut.

Utwórz klucz API

Wejdź na /dashboard/api-keys → Nowy klucz. Wybierz environment: test dla pierwszej integracji (bez ryzyka). Skopiuj jawną postać sekretu - zobaczysz ją TYLKO RAZ.

Sprawdź połączenie (health + me)

# Liveness - bez auth
curl https://api.naprawksef.pl/api/v1/health

# Whoami - z Twoim kluczem
curl https://api.naprawksef.pl/api/v1/me \
  -H "Authorization: Bearer nk_test_<TWÓJ_KLUCZ>"

Zwaliduj XML faktury

curl https://api.naprawksef.pl/api/v1/validate \
  -X POST \
  -H "Authorization: Bearer nk_test_<TWÓJ_KLUCZ>" \
  -H "Content-Type: application/xml" \
  --data-binary @faktura.xml

Endpointy v1

Base URL: https://api.naprawksef.pl/api/v1

GET/healthscope: -Liveness check (publiczny, bez auth)

GET/mescope: authWhoami - info o kluczu, organizacji i limitach

GET/scenariosscope: scenarios | correctionKatalog 13 scenariuszy korekt FA(3)

POST/validatescope: validateWalidacja XML KSeF (JSON body z polem xml lub raw application/xml)

POST/correction/analyzescope: correctionAnaliza pierwotnej faktury + sugestie scenariuszy

POST/correction/buildscope: correctionGeneruj XML faktury korygującej FA(3)

Autentykacja

Format klucza

Każdy klucz ma format nk_(live|test)_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx.

nk_live_* - produkcja: konsumuje limit, zapisuje historię, prawdziwe metryki.
nk_test_* - sandbox: bez limitu, bez historii. Identyczna walidacja, identyczny generator korekt - tylko bez skutków ubocznych.

Bezpieczeństwo

Jawną postać klucza widzisz TYLKO RAZ przy tworzeniu. W bazie tylko skrót SHA-256.
Każdy klucz jest ograniczony do swoich scopes: validate, correction, scenarios, webhooks, reports.
Możesz ustawić datę wygaśnięcia - klucz automatycznie się unieważnia po upływie terminu.
Ręczne unieważnienie działa natychmiast. Ślad audytu w dashboardzie.

Kody błędów

HTTP	Code	Znaczenie
400	`INVALID_BODY / INVALID_XML`	Body nie jest JSON-em / XML nie ma struktury KSeF.
400	`FILE_TOO_LARGE`	XML > 10 MB.
400	`VALIDATION_ERROR`	Walidacja Zod nie przeszła - szczegóły w details[].
401	`MISSING_AUTH`	Brak nagłówka Authorization: Bearer ...
401	`INVALID_KEY_FORMAT`	Klucz nie pasuje do nk_(live\|test)_<hex>.
401	`INVALID_KEY`	Klucz nieprawidłowy, wygasły lub unieważniony.
403	`INSUFFICIENT_SCOPE`	Klucz nie ma wymaganego uprawnienia.
429	`QUOTA_EXCEEDED`	Wykorzystano dzienny/miesięczny limit. Sprawdź X-Quota-* headers.
500	`VALIDATION_FAILED / BUILD_FAILED`	Wewnętrzny błąd serwisu - request_id w nagłówku, support@naprawksef.pl.