API de consulta de teléfonos: ¿qué decisión de registro admiten las propiedades básicas?
Una API de consulta de teléfonos responde a una pregunta limitada sobre un número, no sobre la persona que lo escribe. Antes de integrarla en el registro, decida qué decisiones puede respaldar una propiedad básica y qué hace su código cuando la respuesta es desconocida o falla la llamada al proveedor. Este artículo usa el ejemplo sintético de cuatro ramas para asignar a cada salida un siguiente paso que controla quien llama, sin tratar la consulta como prueba de posesión ni de identidad.
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
Su formulario de registro recoge un número de teléfono y su equipo quiere una consulta antes de crear la cuenta. El diseño tentador es binario: lo válido pasa y todo lo demás se rechaza. Ese diseño falla de dos maneras. Rechaza a personas cada vez que la consulta no puede responder y convierte, sin decirlo, una comprobación de propiedades en prueba de que el usuario posee el número. La decisión real es más estrecha: qué paso del registro puede influir una propiedad básica y qué resultados deben ir a revisión, a un proveedor de OTP existente o a un reintento acotado en lugar de un rechazo. Una consulta describe el número. No demuestra que la persona pueda recibir mensajes en él ni dice quién es.
Qué devuelve realmente el ejemplo comprobado
El ejemplo descargable se ejecuta localmente con Python 3.10 o superior, sin credenciales ni llamadas de red. Su tarea phone recibe una entrada, branch, con cuatro valores: normal, unknown, provider_failure y otp. Cada salida incluye mode igual a synthetic_fixture, el nombre de la rama, otp_sent igual a false y live_line_type_available igual a false. La rama normal devuelve state simulated, valid true, line_type mobile y next continue_customer_policy. 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. Cualquier otra rama lanza UNSUPPORTED_FIXTURE. El valor line_type mobile aparece solo en la rama sintética normal: la ruta gratuita actual de Basic Lookup no solicita tipo de línea, titularidad, alcanzabilidad ni envío de OTP, y eso es lo que indica live_line_type_available false. Este ejemplo de cuatro ramas es distinto de la prueba HTTP anónima de tres escenarios; no confunda una con otra.
Desconocido frente a fallo del proveedor
Ambas ramas comparten state unknown y propiedades nulas, así que un código que solo lea state no puede distinguirlas. La diferencia está en next. Unknown significa que la consulta se ejecutó pero no pudo caracterizar el número; repetir la misma llamada de inmediato probablemente no ayude, por eso el ejemplo apunta a revisión o al flujo de OTP que usted ya opera. Provider failure significa que la llamada no llegó a completarse; un reintento puede funcionar, por eso el ejemplo sugiere un reintento acotado y luego revisión. Ninguna de las dos prueba que el número sea malo y ninguna debe convertirse en rechazo automático. En el diseño de aplicación que proponemos, registre qué rama ocurrió, limite los reintentos con un número fijo y espera progresiva, y envíe los reintentos agotados a la misma cola de revisión que los resultados desconocidos. Ese diseño lo implementa usted; el fixture solo nombra el siguiente paso.
Un escenario hipotético
Hipotéticamente, una pequeña herramienta B2B permite que nuevos administradores de espacios de trabajo se registren con un teléfono que luego se usa para avisos de cuenta. Su política propuesta: un resultado válido permite continuar el registro según las reglas existentes del equipo; nada de la consulta concede permisos de vendedor ni de pagos. Se ejecutan las cuatro ramas. En normal, el equipo espera valid true y next continue_customer_policy, y su código continúa el registro etiquetando el número como no verificado. En unknown, espera next review_or_existing_otp y envía al usuario a su paso de OTP existente. En provider_failure, espera next bounded_retry_then_review, reintenta dos veces en su propio código y después marca revisión mientras deja terminar el formulario. En otp, espera state unsupported y next customer_otp_provider, y llama a su propio proveedor de OTP; otp_sent false confirma que el ejemplo no envió nada. Las aserciones del equipo comparan cada campo exactamente, incluidos los valores nulos.
Manejo de fallos y límites
Trate un UNSUPPORTED_FIXTURE lanzado como un error de programación, no como un resultado del usuario. Nunca permita que valid null se convierta en false. Mantenga acotado el reintento por fallo del proveedor para que un proveedor degradado no bloquee el registro indefinidamente. Recuerde los límites: el fixture es sintético, sus resultados no son un permiso de negocio real y las pruebas de ingeniería que cubren transiciones no demuestran éxito en producción. Las empresas elegibles pueden inscribirse por su cuenta en Basic Lookup gratuito con un límite técnico de 60 solicitudes por minuto, pero la disponibilidad de la ruta real para su caso requiere confirmación aparte, y esa ruta no devuelve tipo de línea.
Lista de aceptación
Antes de pasar del ejemplo sintético a una solicitud de sandbox, confirme: las cuatro ramas se ejecutan y coinciden exactamente con los campos esperados; unknown y provider_failure llevan a pasos distintos y ninguna rechaza; los reintentos tienen límite y terminan en revisión; otp_sent false nunca se interpreta como código enviado; se respeta live_line_type_available false, de modo que ninguna lógica real depende de line_type; ningún resultado se guarda como titularidad o identidad; las ramas no admitidas fallan de forma visible. Si todo se cumple, una integración de sandbox encaja con la tarea; si su decisión necesita posesión o identidad, use OTP o verificación de identidad.
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.