API de validación de números de teléfono: gestionar resultados válidos, desconocidos y fallidos
Estás añadiendo una llamada a una API de validación de números de teléfono en un formulario de registro y debes decidir qué hace tu código con cada respuesta antes de ejecutar una consulta real. La trampa es tratar todo resultado como aprobar o rechazar. Este artículo recorre las cuatro ramas sintéticas del ejemplo descargable, muestra las salidas exactas del fixture y separa lo que implementa el ejemplo del diseño de aplicación que proponemos. Un límite desde el principio: la ruta gratuita actual Basic Lookup no solicita tipo de línea, titularidad, alcanzabilidad ni entrega de OTP, así que tu diseño no debe depender de ellos.
curl https://gridzen.ai/console/api/quickstart/trial \
-H 'Content-Type: application/json' \
-d '{"task": "signup_phone", "scenario": "success"}'El problema y la decisión
Un manejador de registro llama a una verificación de teléfono y recibe un resultado. A veces es una respuesta válida y limpia. A veces la respuesta es desconocida, a veces falló la llamada al proveedor y a veces la pregunta es una que la ruta no puede responder, como si se entregó un código. Si tu manejador rechaza todo lo que no sea un aprobado limpio, una caída temporal se convierte en un registro perdido y una pregunta no soportada en una acusación falsa de número incorrecto. Tu decisión es concreta: qué rama lleva a continuar bajo tu propia política, cuál a una recuperación acotada o revisión, y cuál pasa a un proveedor de OTP independiente que ya operas. El ejemplo permite tomar esa decisión frente a salidas fijas y comprobadas antes de solicitar una integración sandbox.
Qué implementa el ejemplo
El ejemplo de cuatro ramas es un script Python 3.10+ sin dependencias, en el directorio verification_delivery del ZIP descargable. No requiere credenciales ni hace llamadas de red. Ejecutas la tarea phone con una de cuatro ramas: normal, unknown, provider_failure y otp. La única entrada es la rama; los campos de salida son mode, branch, state, valid, line_type, next, otp_sent y live_line_type_available. Toda salida incluye mode synthetic_fixture, otp_sent false y live_line_type_available false. Una rama no reconocida lanza UNSUPPORTED_FIXTURE. Es un fixture sintético, no un adaptador de proveedor real. También es distinto de la prueba HTTP anónima de tres escenarios: no uses resultados de una como evidencia sobre la otra. Las pruebas unitarias incluidas cubren transiciones simuladas; no demuestran éxito en producción.
Escenario hipotético y salidas esperadas
Hipotéticamente, un pequeño equipo B2B conecta su formulario al fixture y ejecuta cada rama. Salidas esperadas: normal devuelve state simulated, valid true, line_type mobile, next continue_customer_policy. El valor mobile existe solo en el fixture; la ruta real Basic Lookup no devuelve tipo de línea, por eso live_line_type_available sigue en false. unknown devuelve state unknown, valid null, line_type null, next review_or_existing_otp. provider_failure devuelve state unknown, valid null, line_type null, next bounded_retry_then_review. otp devuelve state unsupported, valid null, line_type null, next customer_otp_provider, y otp_sent sigue en false: no se envía ningún mensaje. El equipo registra estos ocho campos por rama como fixtures de aceptación y los verifica exactamente, incluidos los valores null, para que un cambio posterior no convierta en silencio unknown en inválido.
Manejo de fallos propuesto en tu aplicación
Lo siguiente es diseño propuesto, no comportamiento implementado. Trata valid true como permiso para continuar solo bajo tu propia política de registro, nunca como prueba de titularidad o identidad. Envía unknown a una cola de revisión o al paso de OTP que ya ejecutas en otro lugar. Envía provider_failure a un número pequeño y fijo de reintentos con espera creciente y luego a revisión; no reintentes indefinidamente ni rechaces al usuario porque falló tu dependencia. Envía unsupported a tu proveedor de OTP existente y espera su propia confirmación, no la del fixture. Mantén valid null distinto de valid false en almacenamiento y registros. Registra branch y next para que los revisores vean por qué se pausó un registro. La ruta real tiene un límite técnico de 60 solicitudes por minuto; una respuesta por límite de tasa va al camino de fallo, no al de inválido.
Límites que deben quedar visibles
Las salidas del fixture son resultados sintéticos comprobados, no respuestas reales. Una señal de validez no establece quién tiene el número, si puede recibir SMS ni si llegó un código. Las empresas elegibles pueden inscribirse por su cuenta en el Basic Lookup gratuito como complemento de la aplicación, pero la disponibilidad de la ruta real para tu caso requiere confirmación aparte. El interés de búsqueda en este tema no es evidencia de demanda, y superar el fixture no prueba que una integración en producción funcione.
Lista de aceptación
Antes de solicitar una integración sandbox, confirma: las cuatro ramas se ejecutan localmente y coinciden exactamente con los campos esperados; un nombre de rama desconocido falla con UNSUPPORTED_FIXTURE; ninguna ruta rechaza a un usuario por unknown o provider_failure; los reintentos están acotados y terminan en revisión; la rama otp nunca muestra un mensaje de código enviado basado en el fixture; otp_sent false se verifica en las pruebas; ninguna lógica lee line_type de la ruta real; valid null y valid false se guardan por separado; y las notas del equipo los registran como resultados sintéticos. Si todo se cumple, la solicitud sandbox es un siguiente paso razonable.
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_failureFuentes 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.
Probar por separado tres resultados del sandbox Crear una cuenta para continuar la integración
Una descarga no demuestra una ejecución correcta. Los ejemplos locales y el sandbox en línea se prueban por separado.