REST API

Ubicación en el portal: Referencia de la API en https://<your-domain>/apidoc (pública) y claves de API en /api-keys. Ubicación en admin: Customers › API keys (/customers/apikeys) lista las claves creadas por clientes.

Qué hace

Cada acción que un cliente puede realizar en el portal —listar y controlar VMs, consultar facturas, gestionar SSH Keys, Kubernetes, almacenamiento y tickets de soporte— está disponible a través de una REST API versionada en https://<your-domain>/v1/. Los clientes la invocan desde scripts y CI mediante una API key con ámbito definido. La misma API alimenta la cmp herramienta de línea de comandos y el servidor MCP, y la referencia se genera a partir de la instalación en ejecución, por lo que siempre enumera exactamente las funciones que tiene activadas.

Requisitos

Elemento	Requisito
Dirección HTTPS pública	La API se sirve en su dominio principal (y en el dominio propio de cada distribuidor).
Una clave de API	Creada por el cliente en el portal; consulte API keys.
Dependencias	Ninguno. Los endpoints de un módulo no habilitado (por ejemplo Kubernetes u Object Storage) se ocultan de la referencia y se rechazan.

Preparar la infraestructura

No hay nada que instalar. Si un proxy inverso está delante de NexCMP, reenvíe /v1/, /mcp, /cli/ y /apidoc al panel (la configuración de nginx del instalador ya lo hace).

Conectar en NexCMP

La referencia interactiva

Abra https://cloud.example.com/apidoc (sustituya el host por su dominio; los clientes de un distribuidor ven la referencia en el dominio del distribuidor, con su nombre). Incluye documentación de endpoints con ejemplos de solicitud y respuesta en curl, la CLI de cmp, JavaScript, Python y Go, un cuadro de búsqueda (Ctrl o Cmd + K) y un panel Try it. Try it envía solicitudes únicamente al mismo sitio, con una clave que el visitante pega (guardada en la sesión del navegador); es de solo lectura por defecto, y las llamadas de escritura o de pago requieren un interruptor adicional y confirmación.

Descargas y documentos legibles por máquina

Todos son públicos, no requieren clave y se generan por sitio:

URL	Contenido
/apidoc	Referencia interactiva.
/v1/public/openapi.json	Documento OpenAPI 3.1.
/v1/public/openapi.yaml	El mismo, en YAML.
/v1/public/postman.json	Colección de Postman.
/v1/public/insomnia.json	Exportación para Insomnia.
/v1/public/api.md	La referencia en un único archivo Markdown.
/v1/public/api-catalog	JSON ligero: marca, URL base, prefijo de clave, cada scope y cada endpoint con método, ruta, scope y si necesita un Idempotency-Key.

curl -s https://cloud.example.com/v1/public/api-catalog | python3 -m json.tool | head -40
curl -sO https://cloud.example.com/v1/public/openapi.yaml

En Postman elija Import › Link y pegue https://cloud.example.com/v1/public/postman.json. La página de referencia también ofrece clientes API de un solo archivo para JavaScript y Python.

Autenticación

Envíe la clave en el encabezado Authorization:

curl -s https://cloud.example.com/v1/billing/wallet \
  -H "Authorization: Bearer vk_XXXX"

• Las claves de cliente comienzan con vk_. Las claves están vinculadas al sitio: una clave creada en cloud.example.com no funciona en el dominio de un revendedor.
• Los tokens de sesión del navegador (pt_...) son solo para el portal; use una clave para la automatización.
• Los scopes de la clave deciden a qué puede llamar; si falta un scope responde HTTP 403 scope_required. Consulte API keys.
• Compruebe una clave con GET /v1/apikeys/self: devuelve el nombre de la clave que realiza la llamada, los scopes, la expiración y el límite de tasa restante permitido (cualquier clave puede llamarlo).

Ejemplos

# List virtual machines
curl -s "https://cloud.example.com/v1/vm?page=1" -H "Authorization: Bearer vk_XXXX"

# Start one (needs vm:write)
curl -s -X POST https://cloud.example.com/v1/vm/3f2a1c9e-0000-4000-8000-000000000000/start \
  -H "Authorization: Bearer vk_XXXX"

# Create a VM (paid: needs vm:create and an Idempotency-Key)
curl -s -X POST https://cloud.example.com/v1/vm \
  -H "Authorization: Bearer vk_XXXX" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d @vm.json

Tome los campos de solicitud exactos de cada operación desde /apidoc.

Errores

Cada error es un JSON con un code estable y un message legible para humanos:

{"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}}

HTTP	code típicos	Significado
401	unauthenticated, key_invalid, key_revoked, key_expired, key_ip_denied, site_mismatch, api_keys_disabled	Clave ausente o desconocida, revocada, expirada, IP de origen fuera de la lista de permitidas de la clave, clave de otro sitio o API keys desactivadas.
403	scope_required, endpoint_not_public, account_blocked, quota_exceeded, impersonate_forbidden	La clave carece del scope; el endpoint no está disponible para claves; la cuenta está bloqueada; se alcanzó una cuota; acción no permitida en una sesión personificada.
404	not_found	No encontrado — también se devuelve para recursos que pertenecen a otra persona.
422	invalid_argument	Error de validación (campo nombrado en la respuesta).
429	rate_limited	Demasiadas solicitudes; espere hasta Retry-After.
503	maintenance	El modo de mantenimiento está activo: las lecturas funcionan, las escrituras se rechazan.

Límites de tasa

Límite	Predeterminado
Por clave	120 solicitudes por minuto
Por cuenta (todas las claves juntas)	300 solicitudes por minuto

Cada respuesta incluye X-RateLimit-Limit, X-RateLimit-Remaining y X-RateLimit-Reset; un error 429 añade Retry-After.

Idempotencia

Los comandos que conllevan costo o no pueden repetirse (crear, cambiar de plan, comprar, eliminar...) requieren un encabezado Idempotency-Key (cualquier cadena de hasta 200 caracteres; un UUID funciona bien). Envíe la misma clave de nuevo tras un timeout y el servidor devolverá el resultado original (con Idempotency-Replayed: 1) en lugar de repetir la operación. Reutilizar una clave para un comando distinto devuelve 422; una solicitud aún en curso devuelve 409/Retry-After. Sin el encabezado se rechaza cualquier llamada de pago.

Verificación

1. Cree una clave con el scope vm:read en el portal (API keys › Create key).

2. Ejecute:

   curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX"

   Obtendrá HTTP 200 y los encabezados de límite de tasa.

3. curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX" lista las VM de la cuenta. En el portal, la columna Last used de la clave y el Key usage log muestran las llamadas.

Límites y notas

• Nunca disponible para una clave: recargas, retiros, cambiar tarjetas o recargas automáticas, cambiar contraseña, correo electrónico o 2FA, eliminar la cuenta, crear, editar o revocar otras claves. Estas acciones requieren una sesión iniciada en el navegador.
• Módulos ocultos: la referencia y el documento OpenAPI solo enumeran las funcionalidades habilitadas en ese sitio.
• Tamaño de respuesta y paginación: los endpoints de listado están paginados (page, per_page); consulte el documento OpenAPI de cada endpoint.
• Tiempo y dinero: los montos están en centavos de USD a menos que el nombre del campo indique lo contrario.
• API de administración: la consola de administración dispone de su propia página System › Admin › API y claves de administrador (ofw_...) para la gestión; son independientes de la API de clientes aquí descrita.
• Versionado: el prefijo de ruta /v1 es estable; es posible que se añadan nuevos campos a las respuestas.

Resolución de problemas

Síntoma	Causa	Solución
401 en una clave nueva	Clave de otro dominio, vencida o escrita con espacios	Cree la clave en el dominio al que llama; verifique el encabezado Authorization: Bearer vk_....
403 scope_required	Scope faltante	Edite la clave en el portal y agregue el scope.
401 key_ip_denied o site_mismatch	Clave restringida a otras IP ("allowed IPs") o creada en otro dominio	Agregue la IP de su servidor a las IP permitidas de la clave o llame al dominio donde se creó.
404 en una VM existente	La VM pertenece a otra cuenta	Use una clave del propietario.
400/422 solicitando Idempotency-Key	Operación de pago sin el encabezado	Agregue Idempotency-Key: <uuid>.
429	Límite superado	Reduzca la frecuencia; use Retry-After.
/apidoc muestra menos de lo esperado	Módulo desactivado	Active el módulo en License & updates.