Guía de producto
API de WhatsApp Lookup: Explicación de las verificaciones de registro en tiempo real
Explore la API de WhatsApp Lookup para verificaciones sincrónicas en tiempo real, endpoints múltiples, análisis de respuestas y flujos de trabajo masivos.
Aprenda cómo la API de WhatsApp Lookup gestiona las verificaciones de registro sincrónicas en tiempo real, el análisis de respuestas y los flujos de trabajo de alto volumen para optimizar los canales de comunicación.
La API de WA Lookup proporciona una verificación sincrónica en tiempo real para confirmar si un número de teléfono está registrado en WhatsApp en el momento de la consulta. Al realizar consultas a endpoints REST dedicados, los equipos reciben señales inmediatas de presencia en la cuenta dentro de la respuesta HTTP inicial. Esta arquitectura admite verificaciones de un solo número y solicitudes múltiples sincrónicas, lo que ayuda a las organizaciones a limpiar las colas de enrutamiento, proteger los flujos de trabajo de entrega y evitar el envío de mensajes a números no asignados.
Comprensión de las señales de registro en WhatsApp
Una verificación de registro evalúa si un identificador específico mantiene una cuenta en la plataforma en el momento de la consulta. Esta señal de presencia en la plataforma proporciona un contexto de alcance técnico antes de iniciar la comunicación.
Los números de teléfono deben seguir el formato internacional de telecomunicaciones públicas descrito en la ITU-T Recommendation E.164, que exige códigos de país y limita la longitud a 15 dígitos. Evaluar los números en la estructura E.164 estandariza los datos de entrada en todos los sistemas internacionales.
Desde una perspectiva operativa, los datos de registro informan sobre el enrutamiento de la audiencia en lugar de establecer la identidad, la propiedad de la línea o el consentimiento del destinatario. Las organizaciones que realizan actividades comerciales deben mantener registros de consentimiento opt-in separados para cumplir con la WhatsApp Business Messaging Policy. Alinear las verificaciones de presencia en la cuenta con los requisitos de minimización de datos del GDPR Article 5 (Regulation (EU) 2016/679) garantiza que los sistemas procesen solo los indicadores de alcance técnico necesarios para los flujos de trabajo de entrega.
Flujos de trabajo de verificación sincrónica en tiempo real
La API de WhatsApp Lookup expone endpoints sincrónicos diseñados para tuberías de decisión inmediatas e integradas. Debido a que estos endpoints operan de forma sincrónica, la solicitud HTTP inicial recibe los atributos de verificación directamente en el payload de respuesta sin requerir ciclos de sondeo secundarios.
Verificación de un solo número
Para eventos transaccionales como formularios de registro o captación de leads individuales, la integración llama a POST /api/v1/check utilizando el encabezado de autenticación X-API-Key. La solicitud envía una cadena de teléfono E.164 y selecciona el tipo de servicio objetivo.
Verificación múltiple sincrónica
Cuando los flujos de trabajo requieren validar colas más pequeñas simultáneamente, POST /api/v1/batch-check acepta hasta 100 números de teléfono en una sola llamada. El endpoint evalúa el lote completo de forma sincrónica y devuelve el conjunto unificado de resultados en la respuesta inicial.
Los desarrolladores que gestionan el volumen de solicitudes deben revisar la documentación oficial sobre los parámetros de concurrencia y tiempo de espera por usuario, ya que la plataforma gestiona la capacidad mediante controles de concurrencia en lugar de límites fijos de solicitudes por minuto.
Comparación de los tipos de servicio de verificación en tiempo real
La API de Lookup estructura las consultas de registro en tres tipos de servicio específicos en tiempo real para respaldar diferentes requisitos de riesgo y enriquecimiento.
| Tipo de servicio | Nombre del servicio | Capacidades documentadas | Campos de datos devueltos |
|---|---|---|---|
| ws | Verificación de registro en WhatsApp | Evalúa el estado de registro en la plataforma | registered |
| ws_avatar | Verificación de avatar de WhatsApp | Evalúa el registro, la presencia de avatar y el enlace al avatar | registered, avatar, avatar_url |
| ws_business | Verificación de cuenta de WhatsApp Business | Evalúa el registro y el indicador de cuenta de WhatsApp Business | registered, business |
Seleccionar ws proporciona el indicador central de alcance. Para flujos de trabajo que requieren enriquecimiento de perfil, ws_avatar añade la disponibilidad del avatar y el enlace a la imagen alojada cuando es accesible. La opción ws_business identifica si el teléfono registrado opera en la plataforma WhatsApp Business, lo que permite la segmentación entre cuentas de consumo y comerciales.
Interpretación de los códigos de estado y consumo de saldo
Las respuestas de la API pública formatean las verificaciones completadas utilizando campos de sobre estándar que contienen code, msg y data. Analizar correctamente los resultados decididos frente a los errores de servicio es fundamental para obtener tuberías de datos fiables.
Una verificación completada produce un código de respuesta de éxito con data.registered establecido en true o false. Tanto los registros decididos como true o false representan búsquedas completadas y consumen saldo en consecuencia.
Un estado indeterminado o una interrupción del servicio ascendente devuelve un código de negocio distinto de cero en lugar de un valor registered=false. Los sistemas descendentes deben aislar los códigos distintos de cero para la lógica de reintento en lugar de tratarlos como números de teléfono no asignados. Los usuarios registrados pueden contactar con soporte para recibir 100 verificaciones gratuitas para validar el manejo de respuestas en entornos de desarrollo.
Tareas masivas asincrónicas para el procesamiento de listas
Aunque los endpoints sincrónicos manejan interacciones con clientes en vivo, las migraciones de datos grandes requieren un flujo de trabajo asincrónico. Para la validación basada en archivos, los equipos utilizan POST /api/v1/bulk-tasks para enviar conjuntos de datos y GET /api/v1/bulk-tasks/{id} para realizar un seguimiento del progreso del procesamiento.
Los archivos de tareas masivas deben enviarse como documentos TXT o CSV que contengan un número de teléfono por línea. El archivo debe centrarse en un único destino de país, ya que las listas con un 10% o más de números fuera del país objetivo activan el rechazo de la preverificación. Se aplican límites de archivo por producto, y los equipos deben consultar la documentación oficial para conocer las reglas actuales de tamaño de archivo.
La cobertura regional también difiere entre los flujos de trabajo. Las verificaciones de un solo número en tiempo real admiten números de China continental (+86), Hong Kong (+852) y Macao (+853) en volúmenes más bajos, mientras que las tareas de archivos masivos asincrónicos excluyen esos destinos. La cobertura de Taiwán sigue sin confirmarse en todos los modos de procesamiento.
Preguntas frecuentes
¿En qué se diferencian las verificaciones sincrónicas en tiempo real de las tareas masivas asincrónicas?
Las verificaciones en tiempo real envían números directamente a POST /api/v1/check o POST /api/v1/batch-check y entregan los resultados inmediatamente en la misma respuesta HTTP. Las tareas masivas asincrónicas aceptan archivos formateados a través de POST /api/v1/bulk-tasks, devuelven primero un ID de tarea y generan un CSV de resultados descargable al finalizar el procesamiento.
¿Cómo gestiona la API los cargos por verificaciones indeterminadas?
Tanto las evaluaciones completadas como registradas y no registradas incurren en el uso estándar de verificación. Por el contrario, un resultado indeterminado o de error de servicio devuelve un código de estado distinto de cero en lugar de un resultado falso, y las verificaciones fallidas no consumen saldo.
Más información
Elija la información del producto que se ajuste al siguiente paso en su flujo de trabajo.