Monitoring & uptime

Każdy poważny integrator chce wiedzieć „czy NaprawKSeF żyje” zanim odpali własny cron przeciw naszemu API. Udostępniamy trzy warstwy monitoringu - od najtańszego (jeden ping co 60s) do najbogatszego (snapshot wszystkich komponentów + aktywne incydenty).

Wszystkie endpointy są publiczne (bez autentykacji), nie liczą się do limitu rate-limit per-API-key, i mają cache 30s na edge. Możesz pollować spokojnie z dowolnej częstotliwości - my odpowiadamy z cache.

Najtańsze rozwiązanie: zwraca 200 OK z plain-text body „ok”. Nie dotyka bazy, nie loguje, działa nawet jeśli Supabase ma awarię.

curl -i https://naprawksef.pl/healthz
# HTTP/2 200
# content-type: text/plain; charset=utf-8
# cache-control: no-store
#
# ok

Wspiera HEAD dla monitorów, które unikają body (oszczędność transferu w wolumenie). Użyj jako liveness probe w Kubernetes/Coolify, albo jako URL w UptimeRobot „Free plan”.

Identyczna semantyka co /healthz, ale zwraca JSON z numerem wersji API, środowiskiem i timestampem. Przydatne, gdy chcesz w jednym requeście wiedzieć „jaka wersja działa na produkcji”.

curl -s https://naprawksef.pl/api/v1/health | jq
{
  "status": "ok",
  "api_version": "1.0.0",
  "timestamp": "2026-05-25T08:14:21.123Z",
  "environment": "production"
}

Bogaty snapshot wszystkich komponentów platformy (api, baza, email, webhooks), z 30- i 90-dniowym uptime, percentylami p50/p99, listą aktywnych incydentów. Backuje stronę /status.

curl -s https://naprawksef.pl/api/v1/status | jq '.overall, .components[].component'
"ok"
"api"
"database"
"email"
"webhooks"

Alias dostępny pod kanoniczną nazwą: /api/v1/platform-status (identyczne body i nagłówki).

Free-tiery większości monitorów (UptimeRobot, Better Stack) nie parsują JSON - alarmują wyłącznie na podstawie kodu HTTP. Dodaj ?strict=1:

# Wszystko OK:
curl -i 'https://naprawksef.pl/api/v1/status?strict=1' | head -1
# HTTP/2 200

# Komponent degraded/down → HTTP 503:
curl -i 'https://naprawksef.pl/api/v1/status?strict=1' | head -1
# HTTP/2 503

Body pozostaje takie samo (pełen snapshot) - tylko status code się zmienia. Twój monitor zaalarmuje, a Ty masz pełną treść do podejrzenia w dashboardzie monitora.

UptimeRobot

• Monitor type: HTTP(s)
• URL: https://naprawksef.pl/api/v1/status?strict=1
• Monitoring interval: 5 min (free plan) lub 1 min (paid)
• Alert when: not 200 - alarm zadziała przy 503 (degraded).

Better Stack (Uptime)

• Monitor type: HTTP(s)
• URL: https://naprawksef.pl/api/v1/status?strict=1
• Check frequency: 30s
• Optional: dodaj drugi monitor na /healthz jako 1-second ping (cheaper).

Grafana / własny dashboard

# scrape co minutę, zapisz overall do TSDB
*/1 * * * * curl -s https://naprawksef.pl/api/v1/status | \
  jq -r '"naprawksef_overall \(.overall) \(now)"' >> /var/log/naprawksef.metrics

Nasz /status page sam ciągnie z tego endpointu - możesz też po prostu zembedować iframe.

Płacisz za plan API? Mamy SLA 99.9% z automatyczną kompensatą:

• Uptime jest liczony z tych samych próbek, które widzisz w /api/v1/status - żadnej osobnej infrastruktury, którą Ty musisz weryfikować.
• Raz w miesiącu (1. dnia, 01:00 UTC) cron oblicza miesięczny uptime, generuje raport SLA i - jeśli zszedł poniżej 99.9% - wystawia kredyt:
  • ≥ 99.0% → 10%
  • ≥ 95.0% → 25%
  • ≥ 90.0% → 50%
  • < 90.0% → 100%
• Kredyt trafia jako customer balance w Stripe (auto-applied do następnej faktury). Idempotency key: sla_credit:<report_id> - nie zdublujemy.
• Klient widzi swoją historię SLA w /dashboard/sla (live projekcja na bieżący miesiąc + historia).