Como gerar credenciais OAuth da API v3 no Painel Nvoip

Última atualização: 23/10/2026

Este manual explica como criar um Client ID e um Client Secret para integrar um sistema à API v3 da Nvoip. As credenciais pertencem à conta e ao usuário que as criou e devem ser usadas somente pela integração identificada no cadastro.

Antes de começar

Você precisa de:

• acesso ao Painel Nvoip;
• permissão para acessar a área Desenvolvedor;
• a lista das operações que a integração realizará;
• uma aplicação backend ou um cofre de segredos para armazenar o Client Secret.

Usuários secundários podem precisar que o administrador da conta habilite o acesso à API. Se a área Desenvolvedor não aparecer ou a criação for recusada, solicite a revisão dessa permissão sem compartilhar nenhuma credencial.

Entenda qual credencial você está criando

Este procedimento cria uma credencial OAuth2 da API v3, formada por Client ID e Client Secret. Ela não é a Napikey, o User Token nem uma chave enviada em X-Nvoip-Api-Key.

Use uma credencial diferente para cada integração. Assim, você pode limitar permissões, identificar o uso e desativar apenas o consumidor necessário.

Acessar a área Desenvolvedor

1. Entre no Painel Nvoip.
2. No menu lateral, clique em Desenvolvedor.
3. Localize a seção Nvoip API v3 (OAuth2.0).
4. Confira o endpoint de token exibido na tela: https://api.nvoip.com.br/auth/oauth2/token.
5. Clique em Criar credencial.

Escolher o tipo de autorização

No campo Tipo de autorização, escolha o fluxo compatível com sua integração:

Não coloque Client Secret em navegador, aplicativo público, código JavaScript entregue ao cliente ou aplicativo móvel. Para esses cenários, use o fluxo indicado pela documentação da integração.

Definir nome e escopos

1. Informe um nome que identifique o sistema, por exemplo Zabbix produção ou ERP financeiro.
2. Selecione somente os escopos necessários.
3. Quando usar authorization_code, informe a Redirect URI HTTPS exata, sem fragmento.

Os principais escopos disponíveis são:

O escopo openid normalmente não é necessário para client_credentials. Cada manual de integração informa os escopos exigidos para aquele uso.

Criar e guardar o Client Secret

1. Revise o nome, o tipo de autorização, a Redirect URI e os escopos.
2. Clique em Criar credencial.
3. Copie o Client ID e o Client Secret imediatamente.
4. Guarde o Client Secret em um cofre de segredos ou variável de ambiente protegida.
5. Confirme em Já copiei somente depois de armazenar os dois valores.

O Client Secret aparece apenas na criação. Depois que a janela for fechada, ele não poderá ser consultado novamente. Se o valor for perdido, crie uma credencial substituta e desative a anterior depois de validar a troca.

Nunca publique Client ID, Client Secret ou access token em repositórios, tickets, prints, chats, URLs ou logs.

Obter um access token

Para uma credencial client_credentials, envie os dados como formulário para o endpoint de token:

curl --request POST 'https://api.nvoip.com.br/auth/oauth2/token' \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data-urlencode 'grant_type=client_credentials' \
  --data-urlencode "client_id=$NVOIP_OAUTH_CLIENT_ID" \
  --data-urlencode "client_secret=$NVOIP_OAUTH_CLIENT_SECRET"

Use o access_token retornado no cabeçalho Authorization: Bearer <token>. Respeite o campo expires_in: obtenha um novo token quando necessário e não registre o token em logs.

Comece a validação com uma consulta sem efeito externo permitida pelos escopos da credencial. Envios de SMS, WhatsApp ou chamadas podem gerar comunicação e cobrança e devem ser testados somente com destino controlado e autorizado.

Gerenciar ou substituir uma credencial

Na mesma seção Nvoip API v3 (OAuth2.0), o Painel mostra nome, criador, Client ID, tipo, Redirect URI, escopos, data e status.

• Desativar: interrompe o uso sem apagar o registro.
• Ativar: libera novamente uma credencial desativada.
• Excluir: remove a credencial definitivamente.
• Trocar um segredo: crie e teste uma nova credencial, atualize a integração e somente depois desative ou exclua a anterior.

Antes de desativar ou excluir, confirme quais sistemas utilizam o Client ID. Não exclua uma credencial apenas porque o nome não é reconhecido.

Solução de problemas

A área Desenvolvedor não aparece

Peça ao administrador da conta para conferir o acesso à API do seu usuário. Clientes de revenda devem seguir a gestão de acesso definida pelo revendedor.

A criação foi recusada

Confirme que o nome foi preenchido, que pelo menos um escopo foi selecionado e que a Redirect URI é uma URL HTTPS válida quando usar authorization_code.

O token retorna HTTP 401

Confira Client ID, Client Secret, status da credencial e codificação do formulário. Não envie as credenciais na URL.

A API retorna HTTP 403

O token foi reconhecido, mas pode faltar o escopo exigido ou a operação pode estar bloqueada pela política da conta. Não amplie os escopos sem revisar a necessidade da integração.

O Client Secret foi perdido ou exposto

Crie uma credencial substituta, atualize a integração e valide o novo acesso. Depois desative ou exclua a credencial antiga. Não envie o segredo ao suporte.

Próximos passos

Depois de gerar a credencial, volte ao manual da integração que você está configurando. Ele informa os escopos, campos e testes específicos daquele produto.

Se precisar de ajuda, abra um chamado na Central de Ajuda Nvoip informando o nome da integração e o erro recebido, sem anexar credenciais ou tokens.