Wszystkie wydania
v1.0.0 25 maja 2026

Platform v1.0 - REST API, Webhooks, SLA 99.9% & Magic Invite Trial

Pierwsze publiczne wydanie platformy NaprawKSeF API - kompletny stack od walidacji XML po automatyczne kredyty SLA w Stripe.

Platform v1.0 - wszystko, co było obiecane

Publikujemy NaprawKSeF API Platform v1.0. Wszystko, co znajdziesz na pricing page (REST API, Webhooks, Idempotency, SLA 99.9%, dedykowany support, autofix bez limitu), jest dostępne w produkcji od dziś.

TL;DR - co działa

  • REST API v1 - /api/v1/validate, /api/v1/correction, /api/v1/api-keys, /api/v1/webhooks, /api/v1/idempotency, /api/v1/health, /api/v1/status.
  • Webhooks - HMAC signing, exponential backoff, DLQ, deliverability dashboard, replay (single + bulk), auto-disable po 50 podaniach, failure-rate alert co 15 min.
  • Magic Invite Trial - partner generuje jeden link, klient klika → dostaje 14 dni Pro/API bez karty.
  • SLA 99.9% z automatycznymi kredytami - co miesiąc cron oblicza uptime, jeśli < 99.9% wystawia kredyt w Stripe (10/25/50/100% zależnie od tier'a).
  • Compliance pack - DPA (PL/EN, art. 28 RODO), Partner ToS, podpis z hash-binding (non-repudiation), audit log 5 lat, /dashboard/audit/export.
  • Strict XSD validator - opcjonalna walidacja przez xmllint-wasm na schema FA(3) (per-org toggle).
  • Security - /security policy, /.well-known/security.txt, threat model, OWASP API Top 10 audit, Semgrep CI.

API surface (publiczne endpointy)

Base URL: https://api.naprawksef.pl/api/v1 (stable, oddzielna subdomena - kontrakt pod przyszły gateway). Wszystkie endpointy działają identycznie pod https://naprawksef.pl/api/v1 (alias na ten sam backend).

MetodaPathCo robi
GET/healthzLiveness ping (plain text "ok")
GET/api/v1/healthJSON status + wersja + środowisko
GET/api/v1/statusPer-component snapshot + incidents (alias /api/v1/platform-status)
POST/api/v1/validateWalidacja XML faktury (FA-1/FA-2/FA-3)
POST/api/v1/correctionGeneruje korektę (/correction/erp-presets dla pre-mapowanych ERP-ów)
GET/POST/api/v1/api-keysLista / utworzenie klucza
POST/api/v1/api-keys/{id}/rotateRotacja z grace period
GET/POST/api/v1/webhooksLista / utworzenie endpoint'u
GET/api/v1/openapiOpenAPI 3.1 (JSON)
GET/api/v1/postmanPostman collection (auto-generated)

Pełna dokumentacja: /developers.

Oficjalne SDK - opublikowane

JęzykPakietInstalacjaMin. wersja
TypeScript / Node.js`@naprawksef/sdk`npm install @naprawksef/sdkNode ≥ 18, Bun, Deno, edge runtimes
PHP`naprawksef/sdk`composer require naprawksef/sdkPHP ≥ 8.1, ext-curl, ext-json

Oba SDK mają zero runtime dependencies, automatyczne retry (429/5xx/network) z respektowaniem Retry-After, automatic Idempotency-Key na POST-ach, typowane wyjątki (np. RateLimitException z retryAfterSeconds()), oraz wbudowany helper do weryfikacji podpisu webhooka (constant-time HMAC-SHA256).

Quickstarty: /developers/sdk-typescript, /developers/sdk-php.

Dashboard surface

  • /dashboard - przegląd, użycie, faktury.
  • /dashboard/api-keys - utworzenie, rotacja, IP allowlist.
  • /dashboard/webhooks - endpointy, eventy, signing secret.
  • /dashboard/webhooks/{id}/deliveries - historia dostaw, replay, failure rate.
  • /dashboard/sla - live monthly uptime + historyczne raporty + kredyty.
  • /dashboard/legal - DPA + Partner ToS (signing flow z hash-binding).
  • /dashboard/audit/export - eksport audytu CSV/JSON.
  • /dashboard/settings - strict XSD toggle, billing portal.

Operator surface (PLATFORM_ADMIN_EMAILS only)

  • /admin/sla - pending credit review (Apply / Waive / Reset + Stripe linkout).
  • /admin/audit - cross-org search + CSV export.
  • /admin/partners - invitations + attributed orgs + MRR per partner.
  • /admin/incidents - incident management + webhook fan-out.
  • /admin/partner-invitations - Magic Invite issuance.
  • /admin/runbook - pełne procedury (refundy, GDPR DSAR, incident response, security disclosure, key rotation, bulk replay, impersonacja).

SLA i automatyczne kredyty

Pełny opis: /developers/monitoring.

Cron sla-monthly-report (1. dnia miesiąca, 01:00 UTC) oblicza miesięczny uptime z 60-sekundowych próbek platform_health_checks, generuje raport per-org i - jeśli uptime spadł poniżej 99.9% - wystawia kredyt jako Stripe customer balance. Klient widzi historię w /dashboard/sla, operator review queue w /admin/sla.

UptimeKredytPowrót do normy
≥ 99.9%0%-
≥ 99.0%10%następny miesiąc
≥ 95.0%25%następny miesiąc
≥ 90.0%50%następny miesiąc
< 90.0%100%następny miesiąc

Idempotency key: sla_credit:<report_id> - żadnych duplikatów nawet po retry.

Magic Invite Trial - model partnerski

Pełny opis: /integracja/trawers (case study Trawers ERP).

  1. Partner (np. Trawers) generuje link w /admin/partner-invitations (plan = Pro/API, trial = 14 dni, max_uses = N).
  2. Klient klika link → strona accept → magic-link login → 14 dni wybranego planu bez karty.
  3. Po wygaśnięciu trial'a - automatyczny rollback do free + email do klienta (cron partner-trial-expiry).
  4. Partner dostaje attribution (visible w /admin/partners), my liczymy MRR po konwersji.

Compliance pack

  • DPA (PL / EN) - art. 28 RODO + Standard Contractual Clauses 2021/915 Moduł 2.
  • Partner ToS (PL / EN) - revenue share, dedicated SLA.
  • Signing flow w /dashboard/legal - scroll-to-end requirement, hash binding (SHA-256 dokumentu = document_hash w legal_acceptances), IP/UA/signer snapshot.
  • Audit log (5 lat retencji) - każda krytyczna akcja (klucz API, webhook, kredyt SLA, legal acceptance, partner invite) idzie do audit_events. Eksport CSV/JSON via /dashboard/audit/export.
  • Security policy - /security, /.well-known/security.txt, threat model (paid plan download via /api/dashboard/security/threat-model).

Co dalej

  • v1.1 (planowane Q3 2026): public Postman workspace, blog deep-dives, scheduled maintenance windows w /status.
  • v1.2 (Q4 2026): ISO 27001 readiness assessment, monthly compliance auto-report do compliance@.
  • Roadmap w /changelog - każde wydanie z notatkami i breaking changes.

Wbudowane presety ERP: v1.0 ma gotowe mapowania dla dwóch popularnych polskich systemów - Trawers 7 (TRES) i Comarch Optima. Każdy preset pokrywa kody VAT, JPK_V7M aliasy i scenariusze typu advance-jpk-reclassify (KOR_ZAL). Klient korzystający z któregokolwiek z nich nie mapuje pól ręcznie - preset jest częścią v1.0 od pierwszego wydania. Kolejne ERP-y dorzucamy w dniach przez Partner Program (1 INSERT + landing).

Pierwszy klient: możesz być Ty. Zacznij od /developers/quickstart lub od free planu.