API de verificación de número de teléfono

Verificar un número de teléfono es demostrar que la persona que tienes enfrente controla realmente el número que escribió. Un número en un formulario es una afirmación; la verificación lo convierte en evidencia. Sin ella, un campo de registro acepta erratas, números desechables, números ajenos y cualquier cosa que un script decida pegar.

Esa evidencia vale la pena por tres razones distintas. Te da un canal de contacto que funciona, de modo que los restablecimientos de contraseña y las notificaciones llegan a un teléfono real. Te da un identificador estable para una cuenta, que es lo que encarece el multicuenta y el abuso de bonos. Y te da un segundo factor al que recurrir más adelante, sin pedirle al usuario que registre nada nuevo.

Todo flujo de verificación se apoya en la misma idea: algo tiene que ocurrir en el teléfono que solo su titular pudo provocar. La versión clásica envía un código de un solo uso por SMS y pide al usuario que lo escriba de vuelta. Phone-Verif invierte el sentido — el usuario envía un mensaje en lugar de recibirlo — pero la forma es la misma: crear una sesión, presentar un desafío, esperar la prueba, leer el resultado.

En la práctica eso son tres piezas de tu lado. Una llamada que abre una sesión de verificación y te da algo que mostrar. Una pantalla o widget donde el usuario actúa. Y una manera de conocer el resultado, por callback o leyendo el estado de la sesión.

WhatsApp es el canal principal. La API devuelve un enlace profundo de WhatsApp con un token de sesión corto; lo muestras como código QR en escritorio o como botón en móvil. El usuario lo toca, WhatsApp se abre con el mensaje ya escrito y lo envía. WhatsApp informa al servidor del número remitente y, como WhatsApp verificó ese número al crear la cuenta, heredas una prueba que no tuviste que construir.

Cuánto de tu tráfico cubre esto depende por completo del mercado. El uso de WhatsApp es casi universal en Brasil, India y buena parte de Europa y África, y marginal en Estados Unidos, Japón y Corea del Sur. Conviene mirar dónde están realmente tus usuarios antes de decidir cuánto respaldo necesitas.

Para usuarios sin WhatsApp, la misma sesión acepta el mismo token por SMS: el usuario envía el token como mensaje de texto al número de verificación. La sesión, el token y el estado que lees después son idénticos, así que tu integración no se bifurca — solo cambia la instrucción que se muestra.

Eso importa más de lo que parece. Un flujo solo de WhatsApp pierde en silencio a todos en mercados de baja adopción; un flujo solo de SMS paga a un operador en cada intento, incluidos los que dispara un bot. Mantener ambos en una sola sesión permite priorizar el canal barato y seguro sin dejar de alcanzar al resto.

En un flujo OTP convencional el servidor envía un secreto y confía en que llegue al teléfono correcto y a ningún otro. Esa suposición es lo que explotan el SIM swap y el phishing de OTP, y es lo que hace rentable el tráfico inflado artificialmente: cada intento te cuesta un mensaje, haya o no un usuario real detrás.

El Reverse OTP elimina la suposición. No se envía ningún secreto al usuario: nada que interceptar, nada que sacarle mediante engaño y ningún mensaje saliente que un defraudador pueda hacerte pagar. El propio acto de enviar es la prueba.

Una sesión empieza en estado pending. Pasa por whatsapp_previewed cuando el usuario ve el mensaje precargado, opened cuando abre el enlace y verified en cuanto el mensaje llega y se asocia a la sesión. Si nadie actúa a tiempo, termina en expired.

Solo el estado verified lleva el número de teléfono; antes de eso el campo es nulo. Trata el estado como la señal y el número como su carga útil, nunca al revés — esa sola regla elimina la mayoría de las condiciones de carrera que aparecen en la primera integración.

La integración son dos llamadas REST. POST /start-verification abre una sesión y devuelve el número de WhatsApp, el enlace profundo y una URL web alojada por si prefieres redirigir en lugar de construir tu pantalla. GET /check-verification-status devuelve el estado de la sesión y, una vez verificada, el número.

También puedes prescindir de la interfaz e incrustar la página de verificación alojada en un iframe, que es el camino más rápido a algo que funcione. En cualquier caso, prefiere el callback a un bucle de sondeo en producción, y consulta el estado solo durante el desarrollo o cuando el usuario vuelva explícitamente a tu página.

Las sesiones son de corta duración y cada token está ligado a una sola de ellas, así que un mensaje reproducido no coincide con nada. El número que recibes procede de la propia infraestructura de WhatsApp y no de una entrada del usuario, lo que cierra el hueco por el que alguien simplemente escribe el número de otra persona y espera un código interceptado.

En cuanto a privacidad, el flujo mueve menos datos personales que el que sustituye: ningún código atraviesa una red de telecomunicaciones camino del usuario, y guardas el número verificado en lugar de un rastro de intentos de entrega.

Las verificaciones se facturan como créditos prepago. No hay suscripción y los créditos no caducan, así que un pico estacional de registros cuesta lo que cuesta y un mes tranquilo no cuesta nada. Las cuentas nuevas empiezan con créditos gratuitos, suficientes para recorrer el flujo completo en un entorno de pruebas antes de comprometerse.