API de verificación telefónica frente a validación de números: ¿dónde encaja el OTP?

El problema: una palabra, tres pruebas

"Verificar el teléfono" puede significar tres cosas. La validación del número describe sus propiedades: si está bien formado, si es válido y qué tipo de línea podría ser. El envío de OTP prueba el acceso a un canal: si quien escribe puede recibir un código en ese canal ahora. La verificación de identidad comprueba la afirmación de una persona, normalmente mediante un recorrido alojado de documento y prueba de vida. Ninguna sustituye a otra. Un número móvil válido no prueba la titularidad, un código recibido no prueba quién es alguien y un resultado Approved no es un permiso incondicional. Su decisión es qué prueba necesita realmente la tarea de registro y qué componente es responsable de cada una.

Qué responde cada prueba y qué cubre GridZen hoy

Propiedades del número: la ruta gratuita Basic Lookup, disponible para empresas elegibles, es un complemento de la aplicación. No solicita tipo de línea, titularidad, alcanzabilidad ni envío de OTP, y aplica un límite técnico de 60 solicitudes por minuto. Acceso al canal: el envío de OTP no está soportado en el ejemplo local ni forma parte de la ruta gratuita actual. Si su tarea necesita probar que alguien recibe un código, mantenga o elija su propio proveedor de OTP autorizado. Identidad: la incorporación de identidad alojada es una tarea aparte, con su propio ejemplo sintético y su propia inscripción. Trátelas como tres componentes con tres responsables en su diseño, no como una llamada que devuelve "verificado".

Escenario hipotético: un registro B2B pequeño

Imagine un equipo hipotético cuyo formulario de registro pide un teléfono de trabajo. Su diseño propuesto: llamar primero a una comprobación del número, pasar el resultado por su propia política y enviar un código mediante un proveedor de OTP existente solo cuando la política exija prueba de canal. Los pagos a vendedores, si alguna vez hacen falta, pasarían más tarde por la incorporación de identidad. Esto es diseño de aplicación propuesto, no comportamiento implementado de GridZen. Lo implementado es el fixture telefónico local de cuatro ramas en delivery.py, que devuelve un siguiente paso por rama para que el equipo conecte sus manejadores antes de cualquier consulta real. Funciona con Python 3.10 o superior, sin credenciales ni red.

Salidas esperadas del fixture por rama

Todas las ramas devuelven mode synthetic_fixture, otp_sent false y live_line_type_available false. La rama normal devuelve state simulated, valid true, line_type mobile y next continue_customer_policy; el valor mobile es sintético y no dice nada de una línea real. La rama unknown devuelve state unknown, valid null, line_type null y next review_or_existing_otp. La rama provider_failure devuelve state unknown, valid null, line_type null y next bounded_retry_then_review. La rama otp devuelve state unsupported, valid null, line_type null y next customer_otp_provider. Ese último valor nombra un componente que usted debe aportar; no se envía ningún mensaje. Una rama no reconocida lanza UNSUPPORTED_FIXTURE. Este ejemplo descargable de cuatro ramas es distinto de la prueba HTTP anónima de tres escenarios.

Manejo de fallos que corresponde a su aplicación

No convierta unknown ni provider_failure en inválido. Unknown significa que la comprobación no pudo responder: derive a revisión o a un paso de OTP que ya opere. Provider failure significa que la llamada falló: reintente un número acotado de veces y luego revise. Unsupported significa que la prueba solicitada no existe en esta ruta: pase a su propio proveedor de OTP en lugar de esperar un código. Nunca interprete valid true como titularidad o alcanzabilidad. Si más adelante añade incorporación de identidad, tenga en cuenta que su fixture solo acepta eventos sintéticos fixture_callback, no firmas reales, y que su paso recover expira sesiones localmente sin consultar a ningún proveedor. Los registros de permiso del fixture no son permisos reales de negocio.

Lista de aceptación

Antes de considerar la integración lista para una solicitud de sandbox, confirme: las cuatro ramas se ejecutan localmente y coinciden con las salidas anteriores; otp_sent es false en todos los resultados y ninguna pantalla espera un código de este fixture; unknown y provider_failure llegan cada uno a un manejador distinto, no al rechazo; customer_otp_provider se asigna a un proveedor de OTP autorizado y con nombre que usted controla, o la tarea no requiere prueba de canal; ningún texto ni registro afirma titularidad, alcanzabilidad o identidad a partir de una comprobación del número; las necesidades de identidad se definen como tarea aparte; y cualquier ruta real se confirma por separado, porque los resultados sintéticos y las pruebas anónimas no son aprobación de producción. Las pruebas cubren solo transiciones simuladas, no el éxito en producción.

Ejecutar el ejemplo sintético comprobado

Descargue y extraiga https://gridzen.ai/downloads/verification-delivery.zip, entre en verification_delivery y ejecute con Python 3.10+. El ejemplo local no hace llamadas de red. Use una base nueva para otra prueba de identidad.

python3 delivery.py phone --branch unknown
python3 delivery.py phone --branch provider_failure

Fuentes y alcance

https://gridzen.ai/guides/phone-otp-identity/ https://gridzen.ai/guides/current-capabilities/ Basado en las fuentes comprobadas y el ejemplo local; las reglas propuestas son recomendaciones de diseño, no comportamiento de producción demostrado. Redacción asistida por IA con revisión independiente.