API de validación de teléfono: distinguir desconocido de fallo del proveedor

El problema: dos nulos que significan cosas distintas

Tu manejador de registro recibe un resultado de teléfono con valid null y line_type null. La decisión es qué ocurre con la persona que espera en el formulario. Un atajo común trata todo nulo como rechazo. Eso mezcla dos situaciones. En una, la comprobación se ejecutó y no pudo decir nada útil sobre el número. En la otra, la llamada al proveedor falló, así que no se aprendió nada. Rechazar en el segundo caso castiga al usuario por una caída. Aceptar a ciegas en cualquiera de los dos finge que hubo una comprobación que no existió. El ejemplo descargable hace explícita la diferencia en el campo next, y tu aplicación también debería mantenerla explícita.

Salidas exactas del fixture para las dos ramas ambiguas

Todas las ramas del ejemplo local devuelven mode synthetic_fixture, otp_sent false y live_line_type_available false. 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. Como comparación, normal devuelve state simulated, valid true, line_type mobile y next continue_customer_policy, y otp devuelve state unsupported, valid null, line_type null y next customer_otp_provider. Un nombre de rama no admitido lanza UNSUPPORTED_FIXTURE. El campo state por sí solo no separa unknown de provider_failure; si tu código solo evalúa state, ya perdiste la distinción. El line_type mobile de la rama normal es un valor sintético: la ruta gratuita actual de Basic Lookup no solicita tipo de línea, por eso live_line_type_available es false en todas las ramas.

Un escenario hipotético

Imagina un pequeño equipo B2B cuyo formulario recoge un teléfono de contacto. Es un diseño hipotético, no la descripción de un despliegue real. Un usuario envía un número. En pruebas, el equipo ejecuta la rama unknown: el manejador propuesto guarda el intento, deja que el registro continúe hacia una cola de revisión y, opcionalmente, activa el flujo OTP que el equipo ya tenga. Luego ejecuta provider_failure: el manejador propuesto reintenta un número limitado de veces con una breve espera y, si la respuesta sigue sin llegar, envía el intento a revisión en lugar de rechazarlo. Por último ejecuta otp y confirma que la pantalla no espera un código, porque otp_sent es false y el fixture nunca envía nada. El número de reintentos, la espera y las reglas de revisión son decisiones del equipo; el fixture solo nombra el siguiente paso.

Qué está implementado y qué diseñas tú

Implementado: una función de Python sin dependencias que asigna un nombre de rama a un diccionario fijo, sin llamadas de red ni credenciales, más pruebas unitarias. No implementado: bucle de reintentos, cola de revisión, envío de OTP ni adaptador real de proveedor. Eso pertenece a quien integra. La prueba HTTP anónima es una comprobación aparte de tres escenarios y no debe confundirse con este ejemplo descargable de cuatro ramas. Basic Lookup, cuando una empresa elegible se inscribe, es una señal complementaria con un límite técnico de 60 solicitudes por minuto; no establece posesión, titularidad, alcanzabilidad ni entrega de OTP. Si necesitas probar que la persona recibe un código, usa tu propio proveedor de OTP. Si necesitas identidad, es una comprobación completamente distinta.

Reglas de manejo de fallos que conviene conservar

Limita los reintentos: un fallo del proveedor que se repite sin fin se convierte en un registro colgado. Registra qué rama produjo cada decisión, para que un revisor vea después que un nulo vino de un fallo y no de un veredicto. Nunca conviertas unknown o provider_failure en un rechazo automático. Trata una rama o un error no reconocido como parada obligatoria en pruebas, igual que UNSUPPORTED_FIXTURE. No permitas que un valid true sintético desbloquee nada real; un resultado del fixture no es permiso de negocio en vivo. El interés de búsqueda en APIs de validación de teléfono no demuestra que un diseño concreto funcione para tus usuarios.

Lista de aceptación

Antes de decidir si una integración en sandbox encaja con tu tarea, confirma: las cuatro ramas se ejecutan localmente y coinciden campo por campo con las salidas anteriores; tu manejador distingue unknown de provider_failure usando next, no state; provider_failure tiene límite de reintentos y revisión como respaldo; ninguna rama lleva a un rechazo automático solo porque valid es null; tu interfaz nunca espera un código cuando otp_sent es false; ningún camino lee line_type de un resultado real de Basic Lookup; los registros guardan mode synthetic_fixture para que los datos de prueba no se confundan con producción; y el equipo acuerda por escrito que una comprobación de teléfono no prueba posesión, titularidad ni identidad. Si todo se cumple, el siguiente paso es una solicitud de sandbox guardada opcional, no un despliegue en vivo.

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/signup-phone-check/ 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.