API platforma v1.0

REST API dla integratorów KSeF

Walidacja XML, generator korekt FA(3) i pełna dokumentacja OpenAPI 3.1 - wszystko za jedną integracją Bearer token. Sandbox dla testów, dedykowane wsparcie dla planu API.

Utwórz klucz API OpenAPI 3.1 spec

Bezpieczna autentykacja

API keys w formacie nk_(live|test)_*, SHA-256 hash w DB, fine-grained scopes, audit trail revoke/expiry. Plaintext widzisz raz.

Sandbox bez quota

Klucze nk_test_* nie konsumują quota 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 (Phase 4).

Quickstart - 3 kroki

Od zera do pierwszego waliduj-ed XML w 5 minut.

Utwórz klucz API

Wejdź na /dashboard/api-keys → Nowy klucz. Wybierz environment: test dla pierwszej integracji (bez ryzyka). Skopiuj plaintext secret - zobaczysz go TYLKO RAZ.

Sprawdź połączenie (health + me)

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

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

Zwaliduj XML faktury

curl https://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://naprawksef.pl/api/v1

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

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

GET/scenariosscope: scenarios | correctionKatalog 12 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 quota, zapisuje historię, prawdziwe metryki.
nk_test_* - sandbox: bez quota, bez historii. Identyczna walidacja, identyczny generator korekt - tylko bez side effects.

Bezpieczeństwo

Plaintext klucza widzisz TYLKO RAZ przy create. W DB tylko SHA-256 hash.
Klucze są scope-restricted: validate, correction, scenarios, webhooks, reports.
Możesz ustawić datę wygaśnięcia - auto-revoke po upływie terminu.
Manualne revoke jest natychmiastowe. Audit trail w Dashboard.

Error codes

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`	Zod validation failed - 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.