Nvoip · Base de Conhecimento

Como migrar da napikey e do token v2 para a API v3

Encerramento das credenciais antigas: 26/03/2027 às 21h, horário de Brasília (UTC−03:00). Migre suas integrações antes desse prazo para evitar interrupções.

Este manual apresenta o fluxo de chaves de API v3 disponível no Painel e na API. A migração de clientes de revendas segue as orientações específicas abaixo.

Se a sua integração usa napikey na URL ou um token v2, ela precisa migrar para o contrato da API v3. A nova chave autentica diretamente na v3, tem permissões limitadas por escopos, validade e revogação individual. O webphone mantido pela Nvoip será migrado pela Nvoip.

1. Identifique o que precisa migrar

Localize as integrações que chamam https://api.nvoip.com.br/v2, enviam napikey na URL ou obtêm tokens pela autenticação v2. Liste os endpoints, as operações e o responsável técnico por cada consumidor. Integrações que já usam OAuth v3 seguem seu contrato próprio; a chave nova não substitui automaticamente um cliente OAuth.

Confira o contrato de cada endpoint v3. Trocar apenas /v2 por /v3 pode mudar parâmetros, formato da resposta e permissões. A chave nova não funciona na API v2.

2. Crie uma chave para a sua integração

  1. Entre no Painel da sua conta e abra Desenvolvedor.
  2. Na seção Chaves de API v3, clique em Criar chave.
  3. Informe um nome que identifique a integração.
  4. Marque somente os escopos necessários. Para consultar o histórico de chamadas, use call:query. Os escopos disponíveis dependem da sua identidade.
  5. Escolha uma validade entre 1 e 365 dias e crie a chave.
  6. Copie o segredo exibido e guarde em um cofre de segredos. Ele aparece somente na criação: a lista e a recarga não recuperam esse valor. Se perder a chave, crie outra e revogue a anterior.

Use uma chave diferente para cada integração. Não coloque o segredo em URLs, repositórios, capturas de tela ou chamados de suporte.

3. Atualize a autenticação

Envie o segredo no cabeçalho X-Nvoip-Api-Key em uma conexão HTTPS para a API v3. Não há etapa de troca por token. Remova a napikey e o token v2 da requisição migrada; não combine a chave com o cabeçalho Authorization.

Exemplo de leitura do histórico, sem originar chamadas ou enviar mensagens:

import os
import urllib.parse
import urllib.request

params = urllib.parse.urlencode({"date": "today", "type": "inbound"})
header_name = "X-Nvoip-Api-Key"
request = urllib.request.Request(
    "https://api.nvoip.com.br/v3/calls/history?" + params,
    headers={header_name: os.environ["NVOIP_API_KEY"]},
)
with urllib.request.urlopen(request, timeout=30) as response:
    print("HTTP", response.status)

Configure NVOIP_API_KEY no ambiente protegido da aplicação e ajuste os parâmetros conforme o contrato e o cenário testado. O exemplo imprime somente o status; não registra a chave nem os dados recebidos.

4. Teste antes de mudar o tráfego

Comece com uma consulta permitida, como o histórico acima. Confira se os dados pertencem à conta esperada e acompanhe Último uso na lista de chaves do Painel. Depois teste as demais operações em um cenário controlado: chamadas, mensagens e cobranças produzem efeitos reais.

Resposta O que conferir
400 Chave em query, cabeçalho duplicado ou mistura com OAuth/Authorization.
401 Chave inválida, expirada ou revogada; identidade bloqueada ou conta inativa.
403 Escopo necessário ausente ou operação não permitida para essa chave.
503 Indisponibilidade temporária; preserve limites e retentativas da integração.

Algumas operações ainda não oferecem autenticação por chave, incluindo provisionamento SIP, gestão de contas/usuários, MCP e compra de números. Para essas operações, confira o contrato de autenticação específico antes de alterar o consumidor.

5. Mude a integração e acompanhe

Após o teste, atualize a configuração da integração e confirme que ela deixou de enviar a credencial antiga. A criação da chave, sozinha, não migra o tráfego. Acompanhe erros e resultado das operações. Para trocar uma chave nova, crie e teste a substituta, atualize a integração e só depois revogue a anterior.

As credenciais antigas serão encerradas em 26/03/2027 às 21h, horário de Brasília. Os lembretes serão enviados no aviso inicial, a três meses, um mês, 15, 10, 5 e um dia antes, e no dia do encerramento. A cada rodada serão consideradas somente contas com uso recente de credenciais antigas que ainda não tenham criado uma chave nova.

Revendedores e seus clientes

O revendedor recebe a comunicação e orienta seus clientes; a Nvoip não envia estes avisos diretamente aos clientes de revendas. A chave pertence à identidade e à conta que a criou: não use uma chave da revenda para acessar outra conta.

A criação e a autenticação por chave descritas acima ainda não estão disponíveis para os perfis de clientes de revenda. Antes de alterar essas integrações, o revendedor deve consultar o suporte da Nvoip sobre o caminho de migração disponível para cada perfil. Não tente aplicar o procedimento de uma conta direta a outra conta nem compartilhar a chave da revenda com seus clientes.

Ao pedir ajuda, informe o número da conta (ramal principal, final 001), o endpoint e o código de erro, sem enviar credenciais. Clientes diretos usam o suporte da Nvoip; clientes de revendas procuram o revendedor.