Sign inGet Started
Começar
Guias
Referência de API
SDKs
CLI
Base de conhecimento
Changelog

Migrar o Verify de outro provedor

Use este guia para mover códigos de verificação de uso único por telefone e e-mail (OTP) de outro provedor de verificação para o Bird Verify. A migração é pequena porque a superfície é pequena: duas chamadas substituem qualquer que seja o par create-and-check do seu provedor, e o Bird controla o código, a mensagem e o canal de entrega por trás deles.
Uma diferença estrutural define o formato do trabalho. O Bird não tem objeto de serviço por aplicação nem ID de verificação para você rastrear. Uma verificação é identificada pelo destinatário, então ambas as chamadas recebem o mesmo to, e o estado que sua integração precisa manter se reduz a nada.
Checklist da migração:
  1. Mapear as chamadas create e check
  2. Configurar seus canais, países e remetente
  3. Portar o ciclo de vida da verificação
  4. Trocar webhooks
  5. Fazer a transição um tempo de vida de código por vez
Os passos 1 e 3 dependem de qual provedor você está deixando. Seu guia do provedor tem o mapeamento campo a campo e a tradução de status.

1. Mapear as chamadas create e check

POST /v1/verify/verifications envia um código de verificação. A menor solicitação é um destinatário:
Exemplo de código
curl -X POST https://us1.platform.bird.com/v1/verify/verifications \
  -H "Authorization: Bearer $BIRD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to": {"phone_number": "+15551234567"}}'
POST /v1/verify/verifications/check envia o que o usuário digitou, identificado pelo mesmo destinatário mais o código. Os payloads completos estão em Enviando verificações.
Quatro diferenças para tratar durante a migração:
  • O destinatário é a chave. Provedores que retornam um SID ou ID de verificação esperam recebê-lo de volta no check. O Bird faz a correspondência pelo conjunto de endereços, e ela precisa ser exata: uma verificação criada com e-mail e número de telefone não é encontrada por apenas um deles. A coluna que guarda o ID de verificação do provedor pode ser removida.
  • Um código errado retorna 200. A resposta traz success: false, um reason de incorrect_code, expired ou attempts_exhausted, e attempts_remaining. Reserve seu caminho de erro para falhas de solicitação. Quando uma verificação atinge um estado final, checks posteriores retornam 404 em vez de success: false.
  • O Bird gera o código e nunca o retorna. Não existe um parâmetro de código personalizado, então uma integração com provedor que fornecia seu próprio código de verificação, ou lia o código de volta para enviá-lo por conta própria, não tem equivalente aqui.
  • Ambos os endpoints aceitam Idempotency-Key. Um replay após um timeout retorna a resposta original sem enviar outro código ou consumir uma tentativa.
As opções por solicitação são intencionalmente poucas: options.code_length e options.channels, que reordena ou restringe os canais para uma solicitação. Todo o resto é configuração do espaço de trabalho em vez de um campo no envio.

2. Configurar seus canais, países e remetente

O Bird entrega códigos por e-mail, SMS, WhatsApp e Telegram. Para um destinatário telefônico, a maioria dos países tenta WhatsApp primeiro com SMS como fallback, e a entrega avança para o próximo canal no plano quando um envio falha. Defina a ordem, ou desative um canal, por país na página Countries; desative os países que você não atende enquanto estiver lá, porque um destino não utilizado é exposição a SMS pumping, e não alcance.
Duas lacunas merecem ser verificadas em relação ao seu fluxo atual antes de você se comprometer com uma data:
  • Não há canal de chamada de voz nem autenticação silenciosa por rede. Um fluxo que recorre a uma chamada telefônica para usuários que não conseguem receber SMS precisa de uma solução diferente aqui.
  • Escolha o remetente antes da migração. E-mail, SMS e WhatsApp usam Bird Verify por padrão e podem usar o Authifly como alternativa. Você também pode usar seu domínio de e-mail verificado, um Sender ID SMS existente ou um número WhatsApp conectado com um template de autenticação aprovado. O Telegram usa sua própria conta de notificação verificada. Se você quiser manter um remetente SMS que seus usuários já reconhecem, verifique se ele é suportado e registrado em cada país de destino. Remetentes e identidade visual cobre as opções e o comportamento de fallback.
Se você usar seu próprio número WhatsApp, selecione um template de autenticação aprovado existente na configuração do Verify. Bird controla o texto do e-mail e da mensagem SMS. Você não pode passar um ID de template ou corpo de mensagem personalizado em uma solicitação de verificação individual.

3. Portar o ciclo de vida da verificação

Uma verificação fica pending até ser resolvida: verified quando um código correto chega a tempo, failed com razão attempts_exhausted ou undeliverable, ou expired com razão ttl_elapsed. Mapeie os estados terminais do seu provedor para esses três e trate reason como um enum aberto.
Os tempos que moldam sua UI são configurações do espaço de trabalho na página Configure: por quanto tempo um código permanece válido, quantas tentativas de check o usuário tem e por quanto tempo o cooldown de reenvio dura. Configure-os para corresponder ao que seus usuários experimentam hoje, em vez de reescrever o texto da sua UI. O tamanho do código é o único valor que você também pode definir por solicitação. Os padrões e os intervalos estão em Configurações de verificação.
Dois comportamentos geralmente substituem código que você já tem:
  • Reenviar é a chamada create de novo. Chame create com o mesmo destinatário: dentro do cooldown, ela retorna a verificação ativa sem enviar, e depois dele um novo código é enviado. Todo código enviado para uma verificação ativa permanece válido até a verificação ser resolvida, então um usuário que digita o primeiro depois que o segundo chega não é penalizado por isso.
  • O "I didn't get a code" tem seu próprio endpoint. POST /v1/verify/verifications/next-channel avança para o próximo canal no plano e envia imediatamente, ignorando o cooldown de reenvio, mas mantendo a expiração, o limite de tentativas e a verificação. Conecte-o ao botão em vez de repetir reenvios em um canal que não está chegando.
Acima das suas configurações estão guardrails da plataforma que você não configura: um limite de envios por hora por endereço e um limite de checks por destinatário, ambos respondidos com um 429 e um Retry-After. Se o seu provedor atual permitia aumentar limites de requisições por endpoint e você aumentou, verifique seu pico em relação aos valores em Guardrails contra abuso antes da transição.

4. Trocar webhooks

O Verify emite eventos em dois eixos. Eventos de sessão, verify.verification.created, verify.verification.verified e verify.verification.failed, acompanham a verificação em si. Eventos de tentativa, verify.attempt.sent, verify.attempt.delivered e verify.attempt.undelivered, acompanham cada envio individual de código de verificação, então um reenvio ou failover de canal adiciona tentativas à mesma sessão. Inscreva um endpoint nos tipos desejados com POST /v1/webhooks; os payloads estão em Eventos do Verify.
Inscreva-se nos eventos de sessão que a sua integração precisa. verify.verification.failed cobre o beco sem saída de entrega: ele dispara com reason: "undeliverable" quando o plano se esgota e as falhas registradas indicam que nenhum código de verificação foi enviado, e seu last_attempt_reason nomeia a falha no último canal tentado. Uma verificação que expira ou esgota suas tentativas de check não emite evento de sessão, então obtenha esses dois resultados da resposta do check.
Esses eventos servem para analytics, alertas e ferramentas de suporte. A decisão de autenticação vem da chamada de check, que responde de forma síncrona, e um fluxo de login nunca deve esperar um webhook para liberar o acesso do usuário. A entrega é at-least-once e sem ordem garantida, assinada conforme Standard Webhooks, então faça deduplicação pelo header webhook-id da mesma forma que para qualquer outro evento Bird.

5. Migre um tempo de vida de código por vez

O Verify não tem destinatários simulados: o que vale testar é o código chegando, então execute a integração com um número de telefone e uma caixa de e-mail que você controla, em cada canal habilitado, antes de mexer em produção.
A migração em si tem uma regra fácil de esquecer. Um código emitido pelo seu provedor antigo não pode ser verificado pelo Bird, e vice-versa. Então faça a troca na chamada de create e, pelo tempo de vida de um código, direcione cada check para o provedor que emitiu aquela verificação. Na prática:
  1. Registre qual provedor criou cada verificação em andamento.
  2. Comece a enviar uma parte das novas verificações pelo Bird e verifique-as contra o Bird.
  3. Continue verificando as verificações mais antigas contra o provedor antigo até que a última expire, o que leva uma janela de validade de código mais uma margem.
  4. Aumente a fatia do Bird quando as taxas de conversão do primeiro grupo estiverem corretas, e então desative o caminho antigo.
Acompanhe a conversão, não apenas a entrega. A página Verifications e as métricas do Verify mostram envios, entregas e quantas verificações chegaram a verified, que é o número que indica se a ordem de canais ou uma nova identidade de remetente está custando cadastros.

Migrando de um provedor específico

  • Twilio Verify: Services viram configurações do espaço de trabalho, VerificationCheck vira um check identificado pelo destinatário, tradução de canal e status
  • Prelude: um formato de create-and-check quase idêntico, com sinais de roteamento e verificação silenciosa como as partes que não são portáveis

Próximos passos

Recursos relacionados

Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.

Assista ao guiaVerify phone numbers at signupEntenda o conceitoWhat does OTP mean? One-time passwords explainedExplore a funcionalidadeCustomer verificationSiga o percurso de aprendizagemBuild your first integration
Experimente na prática e obtenha um resumo de implementação