Tutti gli endpoint restituiscono application/json. Gli errori seguono RFC 7807 (Problem+JSON). Ogni risposta contiene un header X-Request-Id per la correlazione con l'audit log lato server.
| Method | Path | Permesso | Scopo |
|---|---|---|---|
| GET | /v1/health | public | Health check non autenticato. |
| GET | /v1/me | any | Informazioni del proprio account e metadati chiave. |
| GET | /v1/products | read:products | Elenco di tutti i prodotti pubblicamente disponibili con prezzi. |
| GET | /v1/products/{id} | read:products | Dettagli prodotto incluse opzioni di configurazione. |
| POST | /v1/orders | write:orders | Effettuare un ordine. Idempotency-Key obbligatoria. |
| GET | /v1/orders/{id} | read:orders | Stato di un proprio ordine. |
| GET | /v1/services | read:services | Elenco dei propri servizi (paginato). |
| GET | /v1/services/{id} | read:services | Dettagli di un proprio servizio. |
| GET | /v1/services/{id}/credentials | read:credentials | Credenziali del servizio (permesso separato, registrato in audit). |
| POST | /v1/services/{id}/actions | write:services | Azione sul servizio: start, stop, reboot, cancel (alla fine del periodo di fatturazione), cancel_revoke. |
| GET | /v1/billing/balance | read:billing | Saldo credito. |
| GET | /v1/billing/invoices | read:billing | Elenco delle sue fatture (paginato). |
| GET | /v1/billing/invoices/{id}/pdf | read:billing | PDF della fattura. |
| GET | /v1/webhooks | read:webhooks | URL del webhook corrente. |
| PUT | /v1/webhooks | write:webhooks | Impostare o rimuovere l'URL del webhook. |
Idempotenza
POST /v1/orders e POST /v1/services/{id}/actions richiedono un header Idempotency-Key (da 1 a 80 caratteri dell'insieme [A-Za-z0-9_.-]). La chiave è legata a metodo, percorso e body. Se ripete la stessa richiesta con la stessa chiave entro un'ora, riceve la risposta memorizzata; trascorsa l'ora, riceve 410 con reason replay_stale e deve inviare una nuova chiave. La stessa chiave con un body diverso o su un altro endpoint viene rifiutata con 409 idempotency_conflict.
Limiti di velocità
Per impostazione predefinita valgono 60 richieste al minuto (più un burst di 20) e 5.000 al giorno per chiave, 120 al minuto per account su tutte le chiavi e 600 al minuto per IP di origine. Se un limite viene superato, riceve HTTP 429 con l'header Retry-After. Gli header di risposta X-RateLimit-Remaining e X-RateLimit-Reset mostrano lo stato attuale del limite della chiave.
