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, cancel (no fim do período de faturação), cancel_revoke. |
| 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 a 80 caracteres do conjunto [A-Za-z0-9_.-]). Esta chave fica associada ao método, ao caminho e ao corpo. Se repetir o mesmo pedido com a mesma chave no prazo de uma hora, recebe a resposta guardada; depois desse prazo, obtém 410 com reason replay_stale e deve enviar uma chave nova. A mesma chave com um corpo diferente ou noutro endpoint é rejeitada com 409 idempotency_conflict.
Limites de taxa
Por predefinição: 60 pedidos por minuto (mais um burst de 20) e 5000 por dia por chave, 120 por minuto por conta (somando todas as chaves) e 600 por minuto por IP de origem. Se um limite for excedido, recebe HTTP 429 com o cabeçalho Retry-After. Os cabeçalhos de resposta X-RateLimit-Remaining e X-RateLimit-Reset indicam o estado atual do limite da chave.
