Verificación síncrona
Cómo encaja una verificación de registro de WhatsApp en tiempo real en un flujo de trabajo síncrono
Aprenda a comprobar si un número de teléfono está registrado en WhatsApp y a usar el resultado en la misma respuesta síncrona de la API.
Qué significa «tiempo real» en este producto
Tiempo real significa que la decisión de registro se devuelve en la misma solicitud HTTP, y no mediante un trabajo en segundo plano, un webhook o una exportación posterior.
El cliente envía un número de teléfono normalizado y espera la respuesta. Cuando la verificación finaliza, data.registered indica si ese número estaba registrado en WhatsApp en el momento de la solicitud. El cliente puede usar el resultado de inmediato sin consultar periódicamente otro endpoint.
Se trata de un contrato de producto acotado. WA Lookup verifica el estado de registro; no identifica a la persona detrás del número, no supervisa la actividad de la cuenta ni opera un servicio de mensajería. Mantener ese alcance explícito facilita el uso correcto del campo devuelto.
| Datos devueltos | Significado | Acción recomendada |
|---|---|---|
code=0, registered=true |
La verificación completada indicó registrado | Use el resultado booleano devuelto por esta solicitud |
code=0, registered=false |
La verificación completada indicó no registrado | Use false como resultado completado |
| Código de negocio distinto de cero | El servicio no devolvió ninguna decisión de registro | No invente un booleano; gestione el error o reintente según la documentación de la API |
Por qué son útiles las verificaciones síncronas
Un resultado síncrono es útil cuando el siguiente paso del software depende de una respuesta de registro actual. La aplicación no necesita crear un trabajo, conservar un token de sondeo ni esperar una devolución de llamada antes de poder clasificar el número.
Las integraciones típicas incluyen un formulario interno que verifica un número, una herramienta de soporte que comprueba un registro bajo demanda o un proceso de backend. Para listas pequeñas, el endpoint síncrono por lotes acepta hasta 100 identificadores E.164 y devuelve el lote completado en la respuesta inicial. Aun así, los clientes deben controlar su propia concurrencia.
La principal ventaja arquitectónica es el determinismo: una respuesta completada contiene una única decisión booleana de registro. Los errores de la API y las verificaciones indeterminadas utilizan el envoltorio externo code, msg y data en lugar de añadir más valores a registered.
El recorrido de la solicitud, paso a paso
- Normalice el número de teléfono: convierta un prefijo internacional bien conocido y un número nacional al formato E.164. No adivine el contexto de país que falte.
- Envíe una verificación: llame al endpoint de verificación autenticado con el número normalizado y
service_type=ws. - Lea el resultado completado: use
data.registeredcuandocode=0; déjelo sin asignar cuando la API devuelva un código de negocio distinto de cero. - Guarde el momento de la observación: el registro es un resultado puntual, así que guarde cuándo se verificó.
- Gestione por separado los no resultados: una solicitud no válida o un fallo temporal requieren corrección o reintento, no un valor de registro false.
Modele el resultado sin perder significado
Evite un campo genérico como valid. No permite distinguir una entrada mal formada de un número válido que se completó como no registrado. Un registro pequeño y explícito es más seguro:
| Campo | Propósito |
|---|---|
source_phone |
Conserva el valor proporcionado por el sistema de origen |
e164_phone |
Almacena el número canónico enviado para su verificación |
outcome |
La clasificación de su aplicación: completado, reintentable o solicitud fallida |
registered |
Almacena true o false solo para una verificación completada |
checked_at |
Registra cuándo se realizó la observación puntual |
service_type |
Registra qué contrato de producto generó el resultado |
Los errores HTTP no son valores adicionales de este registro. Si una aplicación los registra, debe guardar el estado HTTP devuelto y el code de la API por separado de las observaciones de registro.
Una regla práctica de integración
Ramifique la lógica según data.registered solo cuando la respuesta externa tenga code=0.
Esa única regla evita el error de interpretación más común: tratar un tiempo de espera agotado, una solicitud rechazada o un número mal formado como si WhatsApp hubiera informado que el número no está registrado. Si la decisión debe estar actualizada en un momento posterior, realice una nueva verificación síncrona y guárdela como una nueva observación en lugar de cambiar silenciosamente la marca de tiempo anterior.