# Migrar Verify desde otro proveedor

Usa esta guía para migrar códigos de verificación de un solo uso (OTP) de teléfono y correo electrónico desde otro proveedor de verificación a Bird Verify. La migración es pequeña, porque la superficie es pequeña: dos llamadas reemplazan cualquier par create-and-check de tu proveedor, y Bird se encarga del código, el mensaje y el canal de entrega detrás de ellas.

Una diferencia estructural define la forma del trabajo. Bird no tiene objeto de servicio por aplicación ni ID de verificación que debas rastrear. Una verificación se identifica por su destinatario, así que ambas llamadas reciben el mismo `to`, y el estado que tu integración necesita mantener se reduce a nada.

Lista de pasos de la migración:

1. [Mapea las llamadas create y check](#1-mapea-las-llamadas-create-y-check)
2. [Configura tus canales, países y remitente](#2-configura-tus-canales-países-y-remitente)
3. [Porta el ciclo de vida de la verificación](#3-porta-el-ciclo-de-vida-de-la-verificación)
4. [Cambia los webhooks](#4-cambia-los-webhooks)
5. [Haz el corte un tiempo de vida de código a la vez](#5-cortar-una-vida-de-código-a-la-vez)

Los pasos 1 y 3 dependen del proveedor que estés dejando. Tu [guía del proveedor](#migrar-desde-un-proveedor-específico) tiene el mapeo campo por campo y la traducción de estados.

## 1. Mapea las llamadas create y check

[`POST /v1/verify/verifications`](/docs/api/reference/create-verification) envía un código de verificación. La solicitud mínima es un destinatario:

```bash
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`](/docs/api/reference/create-verification-check) envía lo que el usuario escribió, identificado por el mismo destinatario más el código. Los payloads completos están en [Envío de verificaciones](/docs/guides/verify/sending-verifications).

Cuatro diferencias que debes manejar durante la migración:

- **El destinatario es la clave.** Los proveedores que devuelven un SID o ID de verificación lo esperan de vuelta en el check. Bird hace coincidencia por el conjunto de direcciones, y debe coincidir exactamente: una verificación creada con un correo electrónico y un número de teléfono no se encuentra con uno solo de ellos. Puedes eliminar cualquier columna que almacene el ID de verificación del proveedor.
- **Un código incorrecto devuelve `200`.** La respuesta incluye `success: false`, un `reason` de `incorrect_code`, `expired` o `attempts_exhausted`, y `attempts_remaining`. Reserva tu ruta de error para fallos en la solicitud. Una vez que una verificación alcanza un estado final, los checks posteriores devuelven `404` en lugar de `success: false`.
- **Bird genera el código y nunca lo devuelve.** No existe un parámetro de código personalizado, así que una integración con un proveedor que proporcionaba su propio código de verificación, o lo leía de vuelta para enviarlo por su cuenta, no tiene equivalente aquí.
- **Ambos endpoints aceptan `Idempotency-Key`.** Una repetición después de un timeout devuelve la respuesta original sin enviar otro código ni consumir un intento.

Las opciones por solicitud son pocas a propósito: `options.code_length` y `options.channels`, que reordena o reduce los canales para una solicitud. Todo lo demás es configuración del espacio de trabajo, no un campo en el envío.

## 2. Configura tus canales, países y remitente

Bird entrega códigos por correo electrónico, SMS, WhatsApp y Telegram. Para un destinatario telefónico, la mayoría de los países intentan WhatsApp primero con SMS como respaldo, y la entrega avanza al siguiente canal del plan cuando un envío falla. Configura el orden, o desactiva un canal, por país en la página [**Countries**](https://bird.com/dashboard/w/verify/countries); desactiva los países que no atiendes mientras estés ahí, porque un destino sin uso es exposición al bombeo de SMS en lugar de alcance.

Dos carencias que vale la pena revisar contra tu flujo actual antes de comprometerte con una fecha:

- **No hay canal de llamada de voz ni autenticación silenciosa de red.** Un flujo que recurre a una llamada telefónica para usuarios que no pueden recibir SMS necesita una solución diferente aquí.
- **Elige el remitente antes de la migración.** El correo electrónico, SMS y WhatsApp usan Bird Verify de forma predeterminada y pueden usar Authifly en su lugar. También puedes usar tu dominio de correo electrónico verificado, un Sender ID de SMS existente o un número de WhatsApp conectado con una plantilla de autenticación aprobada. Telegram usa su propia cuenta de notificaciones verificada. Si quieres conservar un remitente de SMS que tus usuarios ya reconocen, comprueba que esté registrado y admitido en cada país de destino. [Remitentes y marca](/docs/guides/verify/senders) cubre las opciones y el comportamiento de respaldo.

Si usas tu propio número de WhatsApp, selecciona una plantilla de autenticación aprobada existente en tu configuración de Verify. Bird controla el texto del correo electrónico y de los mensajes de SMS. No puedes pasar un ID de plantilla ni un cuerpo de mensaje personalizado en una solicitud de verificación individual.

## 3. Porta el ciclo de vida de la verificación

Una verificación está en estado `pending` hasta que se resuelve: `verified` cuando llega un código correcto a tiempo, `failed` con razón `attempts_exhausted` o `undeliverable`, o `expired` con razón `ttl_elapsed`. Mapea los estados terminales de tu proveedor a esos tres, y trata `reason` como un enum abierto.

Los tiempos que dan forma a tu UI son configuraciones del espacio de trabajo en la página [**Configure**](https://bird.com/dashboard/w/verify/configure): cuánto tiempo es válido un código, cuántos intentos de check tiene el usuario y cuánto dura el cooldown de reenvío. Configúralos para que coincidan con lo que tus usuarios experimentan hoy, en lugar de reescribir el texto de tu UI. La longitud del código es el único valor que también puedes definir por solicitud. Los valores por defecto y los rangos están en [Configuración de verificación](/docs/guides/verify/sending-verifications#verification-settings).

Dos comportamientos suelen reemplazar código que ya tienes:

- **Reenviar es la llamada create de nuevo.** Llama a create con el mismo destinatario: dentro del cooldown devuelve la verificación activa sin enviar, y después de él se envía un código nuevo. Cada código enviado para una verificación activa sigue siendo válido hasta que la verificación se resuelve, así que un usuario que ingresa el primero después de que llega el segundo no es penalizado por ello.
- **"I didn't get a code" tiene su propio endpoint.** [`POST /v1/verify/verifications/next-channel`](/docs/api/reference/create-verification-next-channel) avanza al siguiente canal del plan y envía ahí de inmediato, ignorando el cooldown de reenvío pero conservando la expiración, el presupuesto de intentos y la verificación. Conéctalo al botón en lugar de repetir reenvíos en un canal que no está llegando.

Sobre tu configuración hay barreras de la plataforma que no configuras: un límite de envíos por hora por dirección y un límite de checks por destinatario, ambos respondidos con un `429` y un `Retry-After`. Si tu proveedor actual te permitía aumentar los límites de solicitudes por endpoint y lo hiciste, compara tu pico con las cifras en [Barreras contra abuso](/docs/guides/verify/sending-verifications#abuse-guardrails) antes del corte.

## 4. Cambia los webhooks

Verify emite eventos en dos ejes. Los eventos de sesión, `verify.verification.created`, `verify.verification.verified` y `verify.verification.failed`, siguen la verificación en sí. Los eventos de intento, `verify.attempt.sent`, `verify.attempt.delivered` y `verify.attempt.undelivered`, siguen cada envío individual de código de verificación, así que un reenvío o un failover de canal añade intentos a la misma sesión. Suscribe un endpoint a los tipos que necesites con [`POST /v1/webhooks`](/docs/api/reference/create-webhook); los payloads están en [Eventos de Verify](/docs/guides/verify/events).

Suscríbete a los eventos de sesión que tu integración necesite. `verify.verification.failed` cubre el punto muerto de entrega: se dispara con `reason: "undeliverable"` cuando el plan se agota y los fallos registrados indican que no se envió ningún código de verificación, y su `last_attempt_reason` indica el fallo en el último canal intentado. Una verificación que expira o agota sus intentos de comprobación no emite evento de sesión, así que toma esos dos resultados de la respuesta de comprobación.

Estos eventos sirven para analíticas, alertas y herramientas de soporte. Tu decisión de autenticación viene de la llamada de comprobación, que responde de forma síncrona, y un flujo de inicio de sesión nunca debe esperar un webhook para dejar entrar al usuario. La entrega es at-least-once y sin orden garantizado, firmada según [Standard Webhooks](https://www.standardwebhooks.com), así que deduplica con el header `webhook-id` del mismo modo que con cualquier otro evento de Bird.

## 5. Cortar una vida de código a la vez

Verify no tiene destinatarios simulados: lo que vale la pena probar es que el código llegue, así que ejecuta la integración con un número de teléfono y un buzón que controles, en cada canal que hayas habilitado, antes de tocar producción.

El corte en sí tiene una regla fácil de pasar por alto. **Un código emitido por tu proveedor anterior no se puede comprobar con Bird, ni a la inversa.** Haz el cambio en la llamada de creación y, durante la duración de una vida de código, dirige cada comprobación al proveedor que emitió esa verificación. En la práctica:

1. Registra qué proveedor creó cada verificación en curso.
2. Empieza a enviar una parte de las verificaciones nuevas a través de Bird y compruébalas contra Bird.
3. Sigue comprobando las verificaciones anteriores contra el proveedor antiguo hasta que la última expire, lo que toma una ventana de validez de código más un margen.
4. Aumenta la proporción de Bird una vez que las tasas de conversión de la primera cohorte se vean bien, y luego retira la ruta antigua.

Observa la conversión, no solo la entrega. La página [**Verifications**](https://bird.com/dashboard/w/verify/verifications) y las métricas de Verify muestran envíos, entregas y cuántas verificaciones alcanzaron `verified`, que es el número que te indica si un orden de canales o una nueva identidad de remitente te está costando registros.

## Migrar desde un proveedor específico

- [Twilio Verify](/docs/guides/verify/migrate/twilio): los Services pasan a ser configuración del espacio de trabajo, `VerificationCheck` pasa a ser una comprobación por destinatario, traducción de canales y estados
- [Prelude](/docs/guides/verify/migrate/prelude): una estructura de creación y comprobación casi idéntica, con señales de enrutamiento y verificación silenciosa como las partes que no se portan

## Próximos pasos

- [Envío de verificaciones](/docs/guides/verify/sending-verifications): el contrato completo de solicitud y respuesta, estados y límites
- [Configuración por país](/docs/guides/verify/countries): orden y disponibilidad de canales por país
- [Remitentes y marca](/docs/guides/verify/senders): cómo se ve cada mensaje y el remitente de correo con marca
- [Eventos de Verify](/docs/guides/verify/events): payloads de eventos de sesión y de intento

## Related resources

- [Verify phone numbers at signup](/learn/series/verify-phone-numbers-at-signup) (video)
- [What does OTP mean? One-time passwords explained](/explained/verify/what-does-otp-mean) (answer)
- [Customer verification](/verify-api) (product)
- [Build your first integration](/learn/paths/integration) (course)

[Get an implementation brief](/learn/workspace?topic=verify)