Solução · SMS OTP
API de SMS OTP para autenticação no Brasil
Em autenticação, o envio do código é apenas uma parte do controle. O backend também precisa limitar tentativas, expirar o desafio, impedir reutilização e separar a evidência de transmissão da validação do código.
O que o provedor de SMS comprova
O Mandaí registra a intenção, as tentativas e as confirmações recebidas do provedor. delivered indica um recibo positivo; não comprova que a pessoa leu o SMS nem que o código foi validado.
A aplicação continua responsável pelo ciclo do desafio OTP e nunca deve registrar o código em logs, metadados ou webhooks.
Controles mínimos do desafio
Trate o desafio de autenticação como um recurso próprio e separado da mensagem.
- Código aleatório, curto prazo de validade e uso único.
- Limites por conta, destino, IP e dispositivo.
- Comparação segura e invalidação após sucesso.
- Idempotência no comando de envio para evitar códigos concorrentes.
- Alternativa de recuperação quando o resultado permanecer inconclusivo.
Não reenvie por ausência de DLR
Um recibo pode atrasar ou nunca chegar. Se o provedor já reconheceu a tentativa, um novo envio automático pode entregar dois códigos e confundir a pessoa. O estado unknown preserva essa incerteza sem declarar sucesso ou falha inexistentes.
Teste todos os resultados na Sandbox
Automatize testes para entrega, falha explícita, recibo atrasado e resultado unknown. Verifique que o seu produto apresenta mensagens adequadas e não cria loops de reenvio.
Perguntas frequentes
Delivered significa que o código foi usado?
Não. Delivered representa um recibo positivo de entrega. A aplicação é quem comprova a validação correta e o uso único do código.
O código OTP deve ir em metadados?
Não. Códigos e outros segredos não devem ser registrados em metadados, logs, tickets ou payloads de webhook.