API de verificação OTP para desenvolvedores: Node.js, Python, PHP, exemplos de código Java (2026)

Se você é um desenvolvedor avaliando um API OTP para um aplicativo direcionado aos EUA em 2026, você não quer mais uma página de marketing, você quer um código que funcione. Este guia é um passo a passo prático sobre a integração de um API de verificação de número de telefone em um aplicativo de produção: referência de endpoint REST, amostras de código de trabalho em Node.js, Python, PHP e Java, tratamento de erros, tratamento de webhook, teste de sandbox e uma lista de verificação de produção antes de ativar o sinalizador de recurso.

Todos os exemplos usam os endpoints REST do VerifyNow, mas os padrões são transferidos para a maioria APIs OTP modernas (Twilio Verify, Vonage Verify, Sinch Verify) com alterações mínimas. Quando se aplicarem preocupações específicas dos EUA (roteamento de 10DLC, aceitação do TCPA, proteção contra fraudes), nós as denunciaremos on-line.

Os dois endpoints de que você precisa

Cada fluxo de verificação OTP se resume a duas chamadas REST, independentemente do provedor:

1. POST /verificação/envio: gera uma OTP, escolhe o canal ideal (SMS, WhatsApp, voz) e envia o código para o telefone do usuário. Retorna um ID de verificação para a próxima chamada.
2. POST /verificação/validação: aceita a ID de verificação e o código que o usuário inseriu. Retorna sucesso/falha mais um código de erro em caso de falha.

Todo o resto (preferências de canal, políticas de repetição, opções de proteção contra fraudes) é configurado na chamada de envio. A maioria dos provedores expõe de 8 a 12 parâmetros opcionais; os padrões são adequados para ~ 80% dos casos de uso.

Node.js: Enviar e verificar OTP

//Instalação: npm install axios
const axios = require ('axios');

const API_BASE = 'https://cpaas.messagecentral.com/verification/v3';
const API_KEY = process.env.mc_API_KEY;

função assíncrona SendOTP (phoneNumber, channel = 'SMS') {
resposta constante = await axios.post (`$ {API_BASE} /send`, {
Código do país: '1',
Número de celular: número de telefone,
Tipo de fluxo: canal,//'SMS' | 'WHATSAPP' | 'VOZ'
Comprimento superior: 6,
}, {
cabeçalhos: {'authToken': API_KEY}
});
retornar response.data.data.verificationID;
}

função assíncrona verifyOTP (verificationID, código) {
const response = await axios.post (`$ {API_BASE} /validate`, {
ID de verificação,
código,
}, {
cabeçalhos: {'authToken': API_KEY}
});
retornar response.data.data.verificationStatus === 'VERIFICADO';
}

//Uso em seu fluxo de autenticação
const verificationID = await SendOtp ('5551234567');
//... o usuário insere o código...
const verified = await verifyOTP (verificationID, '482917');



Python: Enviar e verificar OTP

# Instalação: solicitações de instalação do pip
sistema operacional de importação
solicitações de importação

API_BASE = 'https://cpaas.messagecentral.com/verification/v3'
API_KEY = os.environ ['MC_API_KEY']

def send_otp (número_telefone, canal = 'SMS'):
resposta = solicitações.post (
f' {API_BASE} /enviar',
json = {
'Código do país': '1',
'Número do celular': número do telefone,
'FlowType': canal,
'Comprimento total': 6,
},
cabeçalhos = {'authToken': API_KEY}
)
response.raise_for_status ()
return response.json () ['data'] ['verificationID']

def verify_otp (verificação_id, código):
resposta = solicitações.post (
f' {API_BASE} /validar',
json = {
'verificationId': verification_id,
'código': código,
},
cabeçalhos = {'authToken': API_KEY}
)
response.raise_for_status ()
return response.json () ['data'] ['verificationStatus'] == 'VERIFICADO'



PHP: Enviar e verificar OTP

<? php
//Usando cURL — sem necessidade de dependências externas.

definir ('API_BASE', 'https://cpaas.messagecentral.com/verification/v3');
definir ('API_KEY', getenv ('MC_API_KEY'));

função SendOTP ($phoneNumber, $channel = 'SMS') {
$ ch = curl_init (API_BASE). '/enviar');
curl_setopt_array ($ch, [
CURLOPT_RETURNTRANSFER => verdadeiro,
CURLOPT_POST => verdadeiro,
CURLOPT_HTTPHEADER => [
'Token de autenticação: '. CHAVE-API,
'Tipo de conteúdo: application/json',
],
CURLOPT_POSTFIELDS => json_encode ([
'CountryCode' => '1',
'MobileNumber' => $phoneNumber,
'FlowType' => $channel,
'otPlength' => 6,
]),
]);
$resposta = json_decode (curl_exec ($ch), true);
curl_close ($ch);
return $response ['data'] ['verificationID'];
}

função verifyOTP ($verificationID, $code) {
$ ch = curl_init (API_BASE). '/validar');
curl_setopt_array ($ch, [
CURLOPT_RETURNTRANSFER => verdadeiro,
CURLOPT_POST => verdadeiro,
CURLOPT_HTTPHEADER => [
'Token de autenticação: '. CHAVE-API,
'Tipo de conteúdo: application/json',
],
CURLOPT_POSTFIELDS => json_encode ([
'verificationId' => $verificationID,
'código' => $código,
]),
]);
$resposta = json_decode (curl_exec ($ch), true);
curl_close ($ch);
return $response ['data'] ['verificationStatus'] === 'VERIFICADO';
}



Java: Enviar e verificar OTP

//Usando java.net.http (JDK 11+).
importar java.net.URI;
importar java.net.http.HttpClient;
importar java.net.http.HttpRequest;
importar java.net.http.HttpResponse;
importar com.fasterxml.jackson.databind.ObjectMapper;
importar com.fasterxml.jackson.databind.jsonNode;

classe pública VerifyNowClient {
String final estática privada API_BASE = "https://cpaas.messagecentral.com/verification/v3 “;
String final estática privada API_KEY = System.getenv (“MC_API_KEY”);
cliente HttpClient final estático privado = httpClient.newHttpClient ();
mapeador de ObjectMapper final estático privado = novo ObjectMapper ();

String estática pública SendOTP (String PhoneNumber, String channel) gera exceção {
Corpo da string = mapper.writeValueAsString (java.util.map.of (
“Código do país”, “1",
“Número do celular”, número de telefone,
“FlowType”, canal,
“Comprimento máximo”, 6
));
requisição HttpRequest = HttpRequest.newBuilder ()
.uri (URI.create (API_BASE + “/send”))
.header (“AuthToken”, API_KEY)
.header (“Tipo de conteúdo”, “aplicativo/json”)
.POST (httpRequest.bodypublishers.ofString (corpo))
.build ();
httpResponse <String>resp = client.send (req, httpResponse.bodyHandlers.ofString ());
retornar mapper.readTree (resp.body ()) .get (“data”) .get (“verificationID”) .asText ();
}

O booleano estático público verifyOTP (String verificationID, código de string) lança a exceção {
Corpo da string = mapper.writeValueAsString (java.util.map.of (
“ID de verificação”, ID de verificação,
“código”, código
));
requisição HttpRequest = HttpRequest.newBuilder ()
.uri (URI.create (API_BASE + “/validar”))
.header (“AuthToken”, API_KEY)
.header (“Tipo de conteúdo”, “aplicativo/json”)
.POST (httpRequest.bodypublishers.ofString (corpo))
.build ();
httpResponse <String>resp = client.send (req, httpResponse.bodyHandlers.ofString ());
retornar “VERIFICADO” .equals (mapper.readTree (resp.body ())
.get (“dados”) .get (“VerificationStatus”) .asText ());
}
}



Tratamento de erros que você realmente precisa

Os erros que importam na produção não são os que estão no caminho certo. Cinco que você deve lidar com:

Formato de número de telefone inválido

‍Retorna HTTP 400 com código de erro NÚMERO_INVÁLIDO. Use o Google número de telefone libphone para normalizar antes de chamar a API.

Incompatibilidade de código

‍O usuário inseriu a OTP errada. Retorna HTTP 200 com VerificationStatus: “FALHOU”. Permita de 3 a 5 tentativas antes de invalidar a ID de verificação.

Código expirado

‍O usuário esperou muito tempo. Devoluções Status de verificação: “EXPIRADO”. Mostre um CTA de “Reenviar código” em sua interface de usuário.

Taxa limitada

‍O mesmo número de telefone solicitou muitas OTPs. Retorna HTTP 429. Não tente novamente imediatamente — recue exponencialmente.

Bombeamento de SMS detectado

‍Retorna HTTP 403 com código de erro FRAUDE DETECTADA. Não tente novamente. Sinalize a solicitação em seu pipeline de detecção de fraudes.

Webhooks para status de entrega

Para implantações de produção, ouça retornos de chamada de entrega assíncronos em vez de pesquisas. Configure um URL de webhook no painel do seu provedor e, em seguida, gerencie:

//Exemplo de manipulador de webhook Express.js
app.post ('/webhooks/verifynow', (req, res) => {
const {verificationID, deliveryStatus, channel, latencyMS} = req.body;

//Persista na análise
db.deliveryEvents.insert ({
ID de verificação,
DeliveryStatus,//'ENTREGUE' | 'FALHOU' | 'PENDENTE'
canal,//'SMS' | 'WHATSAPP' | 'VOZ'
Latência MS,
timestamp: nova data (),
});

//Opcional: acionar o fallback para o canal alternativo em caso de falha
if (DeliveryStatus === 'FALHOU' && channel === 'SMS') {
enviar OTPFallback (ID de verificação, 'WHATSAPP');
}

res.status (200) .end ();
});



Sempre verifique a autenticidade do webhook usando o cabeçalho de assinatura que seu provedor envia — nunca confie em um webhook não assinado em produção.

Teste de sandbox antes da produção

Antes de virar a bandeira do recurso, valide de ponta a ponta na sandbox:

• Teste números de telefone: a maioria Provedores de OTP nos EUA oferecem números de teste reservados que sempre têm sucesso/falham/atingem o tempo limite de forma determinística.
• Teste de rede: verifique se seu firewall permite HTTPS de saída para os endpoints da API do provedor (normalmente a porta 443).
• Teste de limite de taxa: acione deliberadamente um limite de taxa por número e confirme se o tratamento de erros mostra uma mensagem útil.
• Teste de latência: meça o tempo de ida e volta para enviar e verificar sob sua carga normal.
• Teste de entrega de webhook: use um serviço como webhook.site para inspecionar os retornos de chamada antes de direcioná-los para a produção.

O sandbox do VerifyNow usa créditos de teste gratuitos sem cartão de crédito, para que você possa executar a integração completa na pré-produção sem se comprometer com um contrato.

Lista de verificação de produção antes do lançamento

Doze itens para verificar antes de virar a bandeira do recurso:

1. Chaves de API armazenadas no gerenciador de segredos (não no controle de origem)
2. libphonenumber instalado e usado para normalização do lado do cliente
3. API SMS Retriever integrada no Android (ignora a entrada manual de código)
4. API WebOTP integrada na web (preenchimento automático a partir da notificação)
5. O menu suspenso com código de país usa como padrão o IP geográfico do usuário
6. Botão “Reenviar código” oculto nos primeiros 30 segundos e depois revelado
7. Recurso multicanal ativado (SMS → WhatsApp → Voz)
8. O manipulador de webhook autentica o cabeçalho da assinatura
9. Alerta de falha na entrega conectado ao Slack/PagerDuty
10. Limitação de taxa por IP e por número em sua camada de aplicação (não apenas na do provedor)
11. Testado o tratamento de palavras-chave STOP (conformidade com TCPA)
12. Runbook de produção para cenários de “entrega OTP está quebrada” gravados e armazenados

Perguntas frequentes

Qual idioma tem o melhor SDK para APIs OTP?‍

A maioria dos provedores oferece SDKs oficiais em Node, Python, Java, PHP, Go e Ruby com paridade de recursos. As diferenças entre os SDKs são principalmente cosméticas — REST é REST. Escolha o idioma em que sua equipe grava o serviço de autenticação. Se sua equipe escreve em Rust ou .NET, chamar endpoints REST diretamente com o cliente HTTP da linguagem (como no exemplo Java acima) é simples.

Como faço para lidar com o retorno do OTP para um canal diferente em caso de falha?‍

Dois padrões: (a) configurar o fallback automático do lado do provedor listando os canais em ordem de prioridade na chamada de envio, e o provedor tentará cada um deles em sequência em caso de falha na entrega; (b) escute os webhooks de entrega e acione uma nova chamada de envio com um canal diferente do seu aplicativo. O primeiro é mais simples; o segundo oferece mais controle. Verifique agora suporta os dois padrões.

Devo implementar a interface do usuário OTP na web com o WebOTP?‍

Sim, onde os navegadores o suportam. API WebOTP do Google preenche automaticamente o código a partir de uma notificação por SMS no Chrome e no Edge. A mensagem OTP deve ser formatada com um padrão especial (por exemplo, “Seu código é 123456 #abc .example.com #482917 “) para que os navegadores a reconheçam. Volta normalmente à entrada manual em navegadores não suportados.

Obtenha uma chave Sandbox em menos de um minuto

A maneira mais rápida de validar qualquer código acima é executá-lo em uma sandbox real. VerifyNow para os EUA oferece créditos de teste gratuitos sem cartão de crédito, endpoints REST documentados de ponta a ponta e SDKs em 6 idiomas. A maioria das equipes envia sua primeira integração OTP algumas horas após a inscrição.