otp por sms
SMS de código de verificação: login e cadastro com OTP pela API
Mande o SMS de código de verificação do seu SaaS pela rota transacional da D-API: o seu backend gera o código, a API entrega em qualquer celular e o webhook avisa se ele chegou, para você oferecer outro canal a tempo.
SaaS testa 14 dias com o time técnico ajudando na integração.
- conexões na D-API
- 1.875
- de uptime garantido em contrato
- 99,9%
- datacenters no Brasil
- 4
- por ligação de WhatsApp na API não-oficial
- R$ 0
Rota transacional dedicada
Com route otp, o código sai pela rota de envios transacionais, separada da rota de comunicados.
O código é seu
O seu backend gera, guarda e valida o código. A D-API cuida da entrega e devolve o messageId para rastrear.
Sem app e sem internet
O SMS chega em qualquer celular com linha ativa, o que cobre quem não tem WhatsApp no número cadastrado.
Falha vira ação
O webhook informa quando o código não foi entregue, com motivo normalizado, e o seu produto oferece outro canal.
O SMS de código de verificação é a mensagem mais curta e mais urgente que um SaaS manda: o usuário está parado numa tela de login, de cadastro ou de troca de senha, esperando seis dígitos. Se o código atrasa, ele desiste ou abre um chamado. Na D-API, o SMS de código de verificação sai pelo endpoint POST /api/v1/sms/send com route: "otp", a rota transacional, e o status de entrega volta por webhook para o seu backend decidir se oferece outro canal.
Um ponto antes de começar, para evitar confusão com a referência da API: a D-API não tem um serviço de OTP que gera e valida códigos para os seus usuários. O único endpoint com OTP no nome, migration-otp, serve para migrar uma sessão de WhatsApp Web e não envia SMS. A geração e a validação do código ficam no seu backend, e a D-API cuida do envio. Na prática, isso é bom: a regra de segurança fica sob o seu controle, e o canal de entrega pode ser trocado sem mexer nela.
Onde o código por SMS aparece num SaaS
- Cadastro em plataforma de e-commerce: validar que o telefone informado no checkout pertence ao comprador antes de liberar pagamento na entrega.
- Login em software de clínicas: segundo fator para profissionais que acessam prontuários.
- Troca de senha em plataforma de atendimento: confirmar a identidade de quem pediu a recuperação.
- Aprovação de pagamento em software de cobrança: código para confirmar um acordo de parcelamento feito pelo próprio devedor.
- Ativação de conta em edtech: validar o celular do responsável antes de liberar o acesso do aluno.
Em todos esses casos, o SMS tem uma vantagem sobre os outros canais: chega em qualquer celular com linha ativa, sem depender de aplicativo instalado nem de internet no aparelho.
O fluxo completo, do clique à validação
O desenho que funciona bem tem cinco passos, e só um deles chama a D-API:
- O usuário pede o código. O seu backend aplica limite de pedidos por telefone e por IP.
- O backend gera o código com um gerador criptográfico, guarda um hash com validade curta e um contador de tentativas.
- O backend chama
/api/v1/sms/sendcomroute: "otp"e grava omessageIdjunto com o pedido. - O webhook de SMS atualiza o status do envio: entregue, não entregue ou expirado.
- O usuário digita o código, e o backend compara com o hash, respeitando validade e tentativas.
Em Node, a parte do envio fica assim:
import crypto from "node:crypto";
import { DApi } from "d-api-sdk";
const dapi = new DApi({ apiKey: process.env.DAPI_API_KEY! });
export async function enviarCodigo(usuarioId: string, telefone: string) {
const codigo = crypto.randomInt(0, 1_000_000).toString().padStart(6, "0");
const hash = crypto.createHash("sha256").update(`${usuarioId}:${codigo}`).digest("hex");
const envio = await dapi.sms.send({
to: telefone,
text: `Seu codigo de acesso e ${codigo}. Ele vale por 10 minutos. Nao compartilhe.`,
route: "otp",
});
await pedidosDeCodigo.criar({
usuarioId,
hash,
expiraEm: Date.now() + 10 * 60_000,
tentativas: 0,
messageId: envio.messageId,
});
}
A resposta traz messageId, segments e status: "sent". Os erros que a tela precisa tratar: HTTP 400 com BAD_PHONE quando o número não pode ser normalizado, e HTTP 402 com INSUFFICIENT_CREDITS sem saldo. Se a saída rejeitar a mensagem, a API responde HTTP 502 e o valor é estornado; nesse caso, ofereça outro canal na hora em vez de pedir que o usuário espere.
Texto do código: curto, sem acento, em um segmento
A D-API converte o texto para o alfabeto GSM-7 antes de enviar: acentos são removidos e caracteres fora do alfabeto, como emoji, viram ?. Por isso o template do exemplo já foi escrito sem acento. Escrever assim no seu código evita surpresa no texto final e mantém a mensagem abaixo de 160 caracteres, o limite de um segmento. Acima disso, ela é dividida em partes de 153 caracteres e cobrada por parte, o que num fluxo de login de alto volume pesa no custo.
Boas práticas de conteúdo para o código:
- coloque o código no início ou num ponto fácil de achar;
- diga a validade e que o código não deve ser compartilhado;
- identifique o produto, para o usuário reconhecer a mensagem;
- nunca inclua link junto do código.
Quando o código não chega
O webhook de SMS é o que transforma “o código não chegou” em ação de produto. Os eventos sms.undelivered, sms.failed e sms.expired chegam com data.messageId e um errorCode normalizado. Alguns mapeamentos úteis para a tela de verificação:
errorCode |
O que significa | O que a tela pode fazer |
|---|---|---|
LANDLINE |
O número é fixo | Pedir um celular ou oferecer WhatsApp |
INVALID_NUMBER |
Número de destino inválido | Pedir para o usuário revisar o telefone |
NO_COVERAGE, NETWORK_ERROR |
Problema de rota ou rede | Liberar o reenvio ou trocar de canal |
NOT_RECEIVED |
O destino não recebeu | Oferecer o código por outro canal |
Como o webhook de conta tem retentativas, trate os eventos de forma idempotente, usando o messageId e o nome do evento como chave. O status final muda uma única vez por mensagem, o que simplifica o modelo: o pedido de código nasce como “enviado” e vira “entregue” ou “falhou”. A lista completa de códigos está em webhook de SMS e na documentação da D-API.
SMS e WhatsApp para o mesmo código
Como SMS e WhatsApp estão na mesma conta da D-API, o fallback de canal fica inteiro no seu backend. Dois arranjos comuns em SaaS:
- WhatsApp primeiro, SMS depois. O código sai por WhatsApp e, se o usuário clicar em “não recebi” ou o envio falhar, sai por SMS com
route: "otp". Pela API Oficial, códigos usam templates do WhatsApp da categoria de autenticação, com a tarifa da Meta cobrada na conta do seu cliente. - SMS primeiro, WhatsApp como alternativa. Para bases com muitos números sem WhatsApp, o SMS é o padrão e o WhatsApp aparece como opção na tela.
Em qualquer arranjo, use o mesmo código nos dois canais durante a validade e invalide o anterior quando o usuário pedir um novo. Guarde por qual canal cada pedido saiu: com o tempo, esse dado mostra qual combinação entrega mais rápido para a base do seu cliente. A visão geral do canal está no hub de API de SMS, e o desenho de fallback com prazos por tipo de aviso no artigo API de SMS para SaaS.
Time D-API. Atualizado em .
Perguntas frequentes
A D-API gera e valida o código de verificação?
Não. Na D-API o SMS é um canal de envio: o seu backend gera o código, guarda a versão protegida, controla validade e tentativas e valida o que o usuário digita. A API entrega a mensagem e informa o status de entrega.
O que é o endpoint de OTP que aparece na referência da API?
O POST /api/v1/sessions/{sessionId}/migration-otp gera um código de 8 caracteres para migrar uma sessão de WhatsApp Web já autenticada para a D-API pela extensão Assistente de Integração. Ele não envia SMS e não serve para login do seu usuário.
Posso mandar o código por WhatsApp em vez de SMS?
Pode, na mesma conta. Pela API Oficial, códigos usam templates da categoria de autenticação, com tarifa da Meta cobrada na conta do seu cliente. Muitos SaaS mandam por WhatsApp primeiro e usam o SMS como alternativa, ou o contrário.
Por que o meu código chegou sem acento?
Antes do envio, a D-API converte o texto para o alfabeto GSM-7, removendo acentos e trocando caracteres fora dele por interrogação. Escreva o template do código sem acento e sem emoji para ter controle do texto final e caber em um segmento.
Quanto custa cada SMS de código?
O SMS é cobrado por segmento no saldo da carteira, e a rota otp tem categoria de preço própria. O preço não está publicado no site; fale com o time comercial para receber a tabela do seu volume.