--- title: REST API description: Chame a API de cliente da sua instalação NexCMP: autenticação, a referência interativa, downloads de OpenAPI e Postman, erros, limites de taxa, idempotência e exemplos em curl. url: https://nexcmp.com/pt/docs/developers/api/ applies_to: NexCMP 1.6.1 updated: 2026-11-02 --- # REST API > **Onde no portal:** Referência da API em `https:///apidoc` (pública) e chaves de API em `/api-keys`. **Onde no admin:** Customers › API keys (`/customers/apikeys`) lista as chaves criadas pelos clientes. ## O que faz {#what-it-does} Todas as ações que um cliente pode realizar no portal — listar e controlar VMs, ler faturas, gerenciar chaves SSH, Kubernetes, armazenamento e tickets de suporte — estão disponíveis por meio de uma API REST versionada em `https:///v1/`. Os clientes a chamam de scripts e CI com uma **API key** com escopo definido. A mesma API alimenta a [`cmp` command-line tool](https://nexcmp.com/pt/docs/developers/cmp-cli/) e o [MCP server](https://nexcmp.com/pt/docs/developers/mcp/), e a referência é gerada a partir da instalação em execução, listando sempre exatamente os recursos que você ativou. ## Requisitos {#requirements} | Item | Requisito | |---|---| | Endereço HTTPS público | A API é servida no seu domínio principal (e no domínio próprio de cada revendedor). | | Uma chave de API | Criada pelo cliente no portal; consulte [API keys](https://nexcmp.com/pt/docs/developers/api-keys/). | | Dependências | Nenhum. Os endpoints de um módulo que você não ativou (por exemplo, Kubernetes ou Object Storage) ficam ocultos na referência e são recusados. | ## Preparar a infraestrutura {#prepare-the-infrastructure} Nada para instalar. Se houver um proxy reverso na frente do NexCMP, encaminhe `/v1/`, `/mcp`, `/cli/` e `/apidoc` para o painel (a configuração do nginx do instalador já faz isso). ## Conectar no NexCMP {#connect-in-nexcmp} ### A referência interativa {#the-interactive-reference} Abra `https://cloud.example.com/apidoc` (substitua o host pelo seu domínio; os clientes de um revendedor veem a referência no domínio do revendedor, com o nome dele). Ela possui documentação de endpoints com exemplos de solicitação e resposta em curl, `cmp` CLI, JavaScript, Python e Go, uma caixa de pesquisa (Ctrl ou Cmd + K) e um painel **Try it**. O Try it envia solicitações apenas para o mesmo site, com uma chave colada pelo visitante (mantida na sessão do navegador); ele é somente leitura por padrão, e chamadas de gravação ou pagas exigem um comando extra e confirmação. ### Downloads e documentos legíveis por máquina {#downloads-and-machine-readable-documents} Todos são públicos, não exigem chave e são gerados por site: | URL | Conteúdo | |---|---| | `/apidoc` | Referência interativa. | | `/v1/public/openapi.json` | Documento OpenAPI 3.1. | | `/v1/public/openapi.yaml` | O mesmo, em YAML. | | `/v1/public/postman.json` | Coleção do Postman. | | `/v1/public/insomnia.json` | Exportação do Insomnia. | | `/v1/public/api.md` | A referência como um único arquivo Markdown. | | `/v1/public/api-catalog` | JSON leve: marca, URL base, prefixo de chave, cada escopo e cada endpoint com método, caminho, escopo e se ele precisa de um `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 ``` No Postman, escolha **Import › Link** e cole `https://cloud.example.com/v1/public/postman.json`. A página de referência também oferece clientes de API em arquivo único para JavaScript e Python. ### Autenticação {#authentication} Envie a chave no cabeçalho `Authorization`: ```bash curl -s https://cloud.example.com/v1/billing/wallet \ -H "Authorization: Bearer vk_XXXX" ``` - As chaves de cliente começam com `vk_`. As chaves são **vinculadas ao site**: uma chave criada em `cloud.example.com` não funciona no domínio de um revendedor. - Tokens de sessão do navegador (`pt_...`) são apenas para o portal; use uma chave para automação. - Os **escopos** da chave decidem o que ela pode chamar; um escopo ausente responde com HTTP 403 `scope_required`. Consulte [API keys](https://nexcmp.com/pt/docs/developers/api-keys/). - Verifique uma chave com `GET /v1/apikeys/self`: ele retorna o nome da chave chamadora, escopos, validade e o limite restante de taxa (qualquer chave pode chamá-lo). ### Exemplos {#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 ``` Obtenha os campos exatos de requisição de cada operação em `/apidoc`. ### Erros {#errors} Cada erro é um JSON com um `code` estável e uma `message` legível por humanos: ```json {"error": {"code": "scope_required", "message": "Key lacks scope vm:write"}} ``` | HTTP | `code` Típico | Significado | |---|---|---| | 401 | `unauthenticated`, `key_invalid`, `key_revoked`, `key_expired`, `key_ip_denied`, `site_mismatch`, `api_keys_disabled` | Chave ausente ou desconhecida, revogada, expirada, IP do chamador fora da lista de permissões da chave, chave de outro site ou chaves de API desativadas. | | 403 | `scope_required`, `endpoint_not_public`, `account_blocked`, `quota_exceeded`, `impersonate_forbidden` | A chave não tem o escopo; o endpoint não está disponível para chaves; a conta está bloqueada; uma [quota](https://nexcmp.com/pt/docs/billing/quotas/) foi atingida; ação não permitida em uma sessão impersonada. | | 404 | `not_found` | Não encontrado — também retornado para recursos que pertencem a outra pessoa. | | 422 | `invalid_argument` | Erro de validação (campo nomeado na resposta). | | 429 | `rate_limited` | Muitas solicitações; aguarde por `Retry-After`. | | 503 | `maintenance` | O modo de manutenção está ativado: leituras funcionam, gravações são recusadas. | ### Limites de taxa {#rate-limits} | Limite | Padrão | |---|---| | Por chave | 120 requisições por minuto | | Por conta (todas as chaves juntas) | 300 requisições por minuto | Cada resposta carrega `X-RateLimit-Limit`, `X-RateLimit-Remaining` e `X-RateLimit-Reset`; um 429 adiciona `Retry-After`. ### Idempotência {#idempotency} Comandos que custam dinheiro ou não podem ser repetidos (criar, alterar plano, comprar, excluir ...) **exigem** um cabeçalho `Idempotency-Key` (qualquer string de até 200 caracteres; um UUID funciona bem). Envie a mesma chave novamente após um tempo limite e o servidor retornará o resultado **original** (com `Idempotency-Replayed: 1`) em vez de repetir a operação. Reutilizar uma chave para um comando diferente responde com 422; uma requisição ainda emandamento responde com 409/`Retry-After`. Sem o cabeçalho, uma chamada paga é recusada. ## Verificar {#verify} 1. Crie uma chave com o escopo `vm:read` no portal (**API keys › Create key**). 2. Execute: ```bash curl -i https://cloud.example.com/v1/apikeys/self -H "Authorization: Bearer vk_XXXX" ``` Você obtém o HTTP 200 e os cabeçalhos de limite de taxa. 3. `curl -s https://cloud.example.com/v1/vm -H "Authorization: Bearer vk_XXXX"` lista as VMs da conta. No portal, a coluna **Last used** da chave e o **Key usage log** mostram as chamadas. ## Limites e notas {#limits-notes} - **Nunca disponíveis para uma chave:** recarregar, sacar, alterar cartões ou recarga automática, alterar senha, e-mail ou 2FA, excluir a conta, criar, editar ou revogar outras chaves. Essas ações exigem uma sessão de navegador iniciada. - **Módulos ocultos:** a referência e o documento OpenAPI listam apenas os recursos habilitados naquele site. - **Tamanho de resposta e paginação:** os endpoints de listagem são paginados (`page`, `per_page`); leia o documento OpenAPI para cada endpoint. - **Tempo e dinheiro:** os valores monetários estão em centavos de USD, a menos que o nome do campo diga o contrário. - **Admin API:** o console de administração tem sua própria página **System › Admin › API** e chaves de administrador (`ofw_...`) para a administração; elas são separadas da API de clientes descrita aqui. - **Controle de versão:** o prefixo de caminho `/v1` é estável; novos campos podem ser adicionados às respostas. ## Resolução de problemas {#troubleshooting} | Sintoma | Causa | Correção | |---|---|---| | 401 em uma chave nova | Chave de outro domínio, expirada ou digitada com espaços | Crie a chave no domínio que você chama; verifique o cabeçalho `Authorization: Bearer vk_...`. | | 403 `scope_required` | Escopo ausente | Edite a chave no portal e adicione o escopo. | | 401 `key_ip_denied` ou `site_mismatch` | Chave restrita a outros IPs ("allowed IPs") ou criada em outro domínio | Adicione o IP do seu servidor aos IPs permitidos da chave ou chame o domínio onde a chave foi criada. | | 404 em uma VM existente | A VM pertence a outra conta | Use uma chave do proprietário. | | 400/422 solicitando `Idempotency-Key` | Operação paga sem o cabeçalho | Adicione `Idempotency-Key: `. | | 429 | Acima do limite | Aguarde; use `Retry-After`. | | `/apidoc` mostra menos do que o esperado | Módulo desativado | Ative o módulo em License & updates. |