Wszystkie endpointy zwracają application/json. Błędy są zgodne z RFC 7807 (Problem+JSON). Każda odpowiedź zawiera nagłówek X-Request-Id do korelacji z serwerowym dziennikiem audytu.
| Method | Path | Zakres uprawnień | Przeznaczenie |
|---|---|---|---|
| GET | /v1/health | public | Sprawdzenie stanu bez uwierzytelnienia. |
| GET | /v1/me | any | Informacje o własnym koncie oraz metadane klucza. |
| GET | /v1/products | read:products | Lista wszystkich publicznie oferowanych produktów z cenami. |
| GET | /v1/products/{id} | read:products | Szczegóły produktu wraz z opcjami konfiguracyjnymi. |
| POST | /v1/orders | write:orders | Złożenie zamówienia. Wymagany Idempotency-Key. |
| GET | /v1/orders/{id} | read:orders | Status własnego zamówienia. |
| GET | /v1/services | read:services | Lista własnych usług (z paginacją). |
| GET | /v1/services/{id} | read:services | Szczegóły własnej usługi. |
| GET | /v1/services/{id}/credentials | read:credentials | Dane dostępowe usługi (oddzielny zakres uprawnień, wpis w audycie). |
| POST | /v1/services/{id}/actions | write:services | Akcja serwisowa: start, stop, restart, reinstalacja, zawieszenie, odwieszenie, terminacja. |
| GET | /v1/billing/balance | read:billing | Saldo kredytowe. |
| GET | /v1/billing/invoices | read:billing | Lista Państwa faktur (z paginacją). |
| GET | /v1/billing/invoices/{id}/pdf | read:billing | Faktura w formacie PDF. |
| GET | /v1/webhooks | read:webhooks | Aktualny URL webhooka. |
| PUT | /v1/webhooks | write:webhooks | Ustawienie lub usunięcie URL webhooka. |
Idempotencja
POST /v1/orders oraz POST /v1/services/{id}/actions wymagają nagłówka Idempotency-Key (1-80 znaków z zestawu [A-Za-z0-9_.-]). Serwer buforuje odpowiedź i skrót treści przez 24h; drugie żądanie z tym samym kluczem i tą samą treścią zwraca tę samą odpowiedź, drugie żądanie z tym samym kluczem, ale odmienną treścią zostaje odrzucone z kodem 409 idempotency_conflict.
Limity szybkości
Domyślnie: 60 żądań/min (z 20-burst) i 5000/dzień na klucz, dodatkowo 600 żądań/min na IP niezależnie od klucza. W przypadku przekroczenia zwracany jest HTTP 429 z nagłówkiem Retry-After. Nagłówki odpowiedzi X-RateLimit-Remaining i X-RateLimit-Reset prezentują bieżący stan.
