Nvoip · Base de Conhecimento

Como usar o Nvoip Web SDK para OTP e 2FA

A versão 1.0.0 está disponível no npm e contém a migração para a API v3 com OAuth. Instale essa versão para seguir este guia.

API v3 e autenticação atual

Novas integrações usam https://api.nvoip.com.br/v3. Em integrações servidor a servidor, emita OAuth client_credentials em https://api.nvoip.com.br/auth/oauth2/token e use Authorization: Bearer. Guarde client_id, client_secret e tokens somente no backend; respeite expires_in.

Primeiros passos na v3 · Guia de migração v2 → v3. Napikey, token do usuário e fluxo de senha pertencem à compatibilidade legada.

Este artigo mostra como usar o Nvoip Web SDK para adicionar validação por OTP e 2FA em uma aplicação web.
Importante: nunca exponha Napikey, User Token, client secret, access token ou qualquer credencial da Nvoip no navegador. O SDK deve chamar um endpoint do seu backend, e o backend deve chamar a API da Nvoip.

Quando usar OTP ou 2FA?

Fluxo Quando usar Função do SDK
OTP Validação de telefone em cadastro, recuperação de conta, checkout ou confirmação de contato. NvoipAuthWidget.startOTP()
2FA Segunda etapa de segurança depois que e-mail e senha já foram validados pelo backend. NvoipAuthWidget.start2FA()

1. Instale o pacote

Em projetos com npm, instale o SDK:

npm install [email protected]

Você também pode usar os arquivos distribuídos em dist/nvoip-auth-widget.css e dist/nvoip-auth-widget.js.

2. Crie os endpoints no seu backend

O frontend deve chamar endpoints próprios da sua aplicação, por exemplo:

  • POST /api/nvoip/auth/start: inicia o envio do código por SMS, ligação ou WhatsApp.
  • POST /api/nvoip/auth/confirm: valida o código informado pelo usuário.

No backend, use a API da Nvoip para gerar o OAuth e chamar os endpoints corretos. Para OTP, os canais principais são:

  • SMS: POST /otp com phoneNumber e methods.sms=true.
  • Ligação: POST /otp com phoneNumber e methods.torpedo=true.
  • Validação OTP: GET /check/otp com code e key.

Para 2FA por SMS, use POST /2fa e depois GET /check/2fa.

3. Use 2FA depois do login

Depois que o backend validar e-mail e senha, abra o 2FA. Ao validar o código, o SDK pode redirecionar para a URL final do login.

<link rel="stylesheet" href="/dist/nvoip-auth-widget.css" />
<script src="/dist/nvoip-auth-widget.js"></script>

<script>
async function startVerification(payload) {
  const response = await fetch("/api/nvoip/auth/start", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload)
  });
  return response.json();
}

async function confirmVerification(payload) {
  const response = await fetch("/api/nvoip/auth/confirm", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload)
  });
  return response.json();
}

function afterPasswordLogin(user) {
  NvoipAuthWidget.start2FA({
    channels: ["sms", "voice", "whatsapp"],
    phone: user.phone,
    maskedPhone: user.maskedPhone,
    accountLabel: user.email,
    returnTo: "/app",
    startVerification,
    confirmVerification
  });
}
</script>

4. Use OTP direto para validar telefone

Use OTP quando o usuário ainda está em cadastro, recuperação de conta ou confirmação de número.

<button id="validate-phone">Validar telefone</button>
<input id="phone" type="tel" placeholder="5511999999999" />

<script>
document.getElementById("validate-phone").addEventListener("click", () => {
  NvoipAuthWidget.startOTP({
    channels: ["whatsapp", "sms", "voice"],
    phone: document.querySelector("#phone").value,
    returnTo: "/cadastro/concluido",
    startVerification,
    confirmVerification
  });
});
</script>

5. Escolha os canais exibidos no frontend

O desenvolvedor controla quais opções aparecem para o usuário:

channels: ["sms", "voice", "whatsapp"]

Se a conta ainda não tiver template de WhatsApp aprovado, mantenha apenas SMS e ligação até concluir a configuração.

6. Teste localmente

O repositório possui duas demos:

  • Mock: simula o envio e usa código fixo para validar o fluxo visual.
  • Real: usa um backend Node local para chamar a API da Nvoip.
npm run demo:mock
npm run demo:real

Cuidados de segurança

  • Não coloque credenciais da Nvoip em HTML, JavaScript público, apps mobile ou repositórios frontend.
  • Gere o access_token no backend usando OAuth.
  • Masque telefone e e-mail no frontend sempre que possível.
  • Valide no backend se o usuário atual pode iniciar aquele OTP ou 2FA.
  • Defina expiração e limite de tentativas para reduzir abuso.

Links úteis