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, cancel (al final del periodo de facturación), cancel_revoke. |
| 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 (de 1 a 80 caracteres del conjunto [A-Za-z0-9_.-]). La clave queda vinculada al método, la ruta y el cuerpo. Si repite la misma petición con la misma clave en el plazo de una hora, recibirá la respuesta almacenada; pasado ese plazo, obtendrá un 410 con reason replay_stale y deberá enviar una clave nueva. La misma clave con otro cuerpo o en otro endpoint se rechaza con 409 idempotency_conflict.
Límites de tasa
Por defecto, 60 peticiones por minuto (más una ráfaga de 20) y 5.000 al día por clave, 120 por minuto por cuenta entre todas las claves y 600 por minuto por IP de origen. Si se supera un límite, recibirá HTTP 429 con la cabecera Retry-After. Las cabeceras de respuesta X-RateLimit-Remaining y X-RateLimit-Reset muestran el estado actual del límite de la clave.
