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, reboot, cancel (na koniec okresu rozliczeniowego), cancel_revoke. |
| 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 (od 1 do 80 znaków z zestawu [A-Za-z0-9_.-]). Klucz jest powiązany z metodą, ścieżką i treścią żądania. Powtórzenie tego samego żądania z tym samym kluczem w ciągu godziny zwraca zapisaną odpowiedź; po upływie tego czasu otrzymają Państwo kod 410 z reason replay_stale i należy wtedy wysłać nowy klucz. Ten sam klucz z inną treścią lub na innym endpoincie zostaje odrzucony z kodem 409 idempotency_conflict.
Limity szybkości
Domyślnie 60 żądań na minutę (plus burst do 20 żądań) i 5000 dziennie na klucz, 120 na minutę na konto łącznie dla wszystkich kluczy oraz 600 na minutę na źródłowy adres IP. Po przekroczeniu limitu otrzymają Państwo HTTP 429 z nagłówkiem Retry-After. Nagłówki odpowiedzi X-RateLimit-Remaining i X-RateLimit-Reset pokazują bieżący stan limitu klucza.
