Todos los endpoints devuelven application/json. Los errores siguen el RFC 7807 (Problem+JSON). Toda respuesta incluye la cabecera X-Request-Id para correlacionar con el registro de auditoría del servidor.
| Method | Path | Permiso | Propósito |
|---|---|---|---|
| GET | /v1/health | public | Comprobación de salud sin autenticación. |
| GET | /v1/me | any | Información de la propia cuenta y metadatos de la clave. |
| GET | /v1/products | read:products | Listado de todos los productos públicos con sus precios. |
| GET | /v1/products/{id} | read:products | Detalles del producto, incluidas las opciones de configuración. |
| POST | /v1/orders | write:orders | Realizar un pedido. Idempotency-Key obligatorio. |
| GET | /v1/orders/{id} | read:orders | Estado de un pedido propio. |
| GET | /v1/services | read:services | Listado de los servicios propios (paginado). |
| GET | /v1/services/{id} | read:services | Detalles de un servicio propio. |
| GET | /v1/services/{id}/credentials | read:credentials | Credenciales del servicio (permiso separado, auditado). |
| POST | /v1/services/{id}/actions | write:services | Acción de servicio: start, stop, reboot, reinstall, suspend, unsuspend, terminate. |
| GET | /v1/billing/balance | read:billing | Saldo disponible. |
| GET | /v1/billing/invoices | read:billing | Listado de sus facturas (paginado). |
| GET | /v1/billing/invoices/{id}/pdf | read:billing | PDF de factura. |
| GET | /v1/webhooks | read:webhooks | URL actual del webhook. |
| PUT | /v1/webhooks | write:webhooks | Configurar o eliminar la URL del webhook. |
Idempotencia
POST /v1/orders y POST /v1/services/{id}/actions requieren la cabecera Idempotency-Key (1-80 caracteres del conjunto [A-Za-z0-9_.-]). El servidor almacena en caché la respuesta y el hash del cuerpo durante 24h; una segunda petición con la misma clave y el mismo cuerpo devuelve la misma respuesta, mientras que una segunda petición con la misma clave pero cuerpo distinto se rechaza con 409 idempotency_conflict.
Límites de tasa
Por defecto: 60 peticiones/minuto (con ráfaga de 20) y 5000/día por clave, más 600 peticiones/minuto por IP independientemente de la clave. Al superarlos, se devuelve HTTP 429 con la cabecera Retry-After. Las cabeceras de respuesta X-RateLimit-Remaining y X-RateLimit-Reset informan del estado actual.
