--- title: REST API description: Invoque la API de clientes de NexCMP: autenticación, referencia interactiva, descargas OpenAPI y Postman, errores, límites de tasa y ejemplos curl. url: https://nexcmp.com/es/docs/developers/api/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # REST API > **Ubicación en el portal:** Referencia de la API en `https:///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 {#what-it-does} 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:///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](https://nexcmp.com/es/docs/developers/cmp-cli/) y el [servidor MCP](https://nexcmp.com/es/docs/developers/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 {#requirements} | 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](https://nexcmp.com/es/docs/developers/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 {#prepare-the-infrastructure} 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 {#connect-in-nexcmp} ### La referencia interactiva {#the-interactive-reference} 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 {#downloads-and-machine-readable-documents} 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`. | ```bash 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 {#authentication} Envíe la clave en el encabezado `Authorization`: ```bash 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](https://nexcmp.com/es/docs/developers/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 {#examples} ```bash # 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 {#errors} Cada error es un JSON con un `code` estable y un `message` legible para humanos: ```json {"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](https://nexcmp.com/es/docs/billing/quotas/); 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 {#rate-limits} | 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 {#idempotency} 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 {#verify} 1. Cree una clave con el scope `vm:read` en el portal (**API keys › Create key**). 2. Ejecute: ```bash 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 {#limits-notes} - **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 {#troubleshooting} | 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: `. | | 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. |