Todos os endpoints retornam application/json. Erros seguem a RFC 7807 (Problem+JSON). Cada resposta traz um cabeçalho X-Request-Id para correlação com o log de auditoria do servidor.
| Method | Path | Escopo | Finalidade |
|---|---|---|---|
| GET | /v1/health | public | Health check sem autenticação. |
| GET | /v1/me | any | Informações da própria conta e metadados da chave API. |
| GET | /v1/products | read:products | Lista de todos os produtos listados publicamente, com preços. |
| GET | /v1/products/{id} | read:products | Detalhes do produto, incluindo opções de configuração. |
| POST | /v1/orders | write:orders | Realizar um pedido. Idempotency-Key obrigatório. |
| GET | /v1/orders/{id} | read:orders | Status de um pedido próprio. |
| GET | /v1/services | read:services | Lista dos próprios serviços (paginada). |
| GET | /v1/services/{id} | read:services | Detalhes de um serviço próprio. |
| GET | /v1/services/{id}/credentials | read:credentials | Credenciais do serviço (escopo separado, registrado em auditoria). |
| POST | /v1/services/{id}/actions | write:services | Ação de serviço: start, stop, reboot, reinstall, suspend, unsuspend, terminate. |
| GET | /v1/billing/balance | read:billing | Saldo de crédito. |
| GET | /v1/billing/invoices | read:billing | Lista das suas faturas (paginada). |
| GET | /v1/billing/invoices/{id}/pdf | read:billing | PDF da fatura. |
| GET | /v1/webhooks | read:webhooks | URL atual do webhook. |
| PUT | /v1/webhooks | write:webhooks | Definir ou remover a URL do webhook. |
Idempotência
POST /v1/orders e POST /v1/services/{id}/actions exigem um cabeçalho Idempotency-Key (1-80 caracteres em [A-Za-z0-9_.-]). O servidor mantém em cache a resposta e o hash do corpo por 24h; uma segunda requisição com a mesma chave e o mesmo corpo retorna a mesma resposta, enquanto uma segunda requisição com a mesma chave, porém corpo diferente, é rejeitada com 409 idempotency_conflict.
Limites de taxa
Padrão: 60 req/min (com burst de 20) e 5000/dia por chave API, mais 600 req/min por IP independentemente da chave. Em caso de excesso, HTTP 429 com cabeçalho Retry-After. Os cabeçalhos X-RateLimit-Remaining e X-RateLimit-Reset na resposta expõem o estado atual.
