Guía de producto
Cómo planificar un flujo de API de verificación telefónica en tiempo real para Telegram
Diseñe un flujo de API de verificación de Telegram con los endpoints en tiempo real de TG Validator: uno o hasta 100 números por solicitud, con E.164 y límites de concurrencia.
Una guía técnica para diseñar un flujo de API de verificación telefónica en tiempo real con TG Validator, que abarca los endpoints síncronos individual y múltiple, los límites de concurrencia, el formato E.164 y la interpretación de la señal.
Un flujo de verificación de TG Validator se basa en verificaciones en tiempo real: envíe un identificador E.164 a POST /api/v1/check, o hasta 100 identificadores al endpoint múltiple síncrono POST /api/v1/batch-check, y los resultados de registro completados se devuelven en la respuesta HTTP de la solicitud. Controle la concurrencia en el lado del cliente según la documentación de la API. Para una lista completa que supere con creces una solicitud en tiempo real, también está disponible una tarea masiva asíncrona como complemento.
El modelo de verificación síncrona
El modelo principal de TG Validator es síncrono. Utilice POST /api/v1/check para un identificador o el endpoint múltiple síncrono POST /api/v1/batch-check para hasta 100 identificadores; los resultados completados se devuelven en la misma respuesta HTTP, sin pasos de envío de tareas, consulta periódica, callback ni descarga, y sin exigir que los números sean del mismo país. Como alternativa para una lista grande completa, también está disponible una tarea masiva asíncrona (/api/v1/bulk-tasks): suba el archivo, reciba un id de tarea y, a continuación, consulte la tarea y descargue el archivo de resultados cuando termine. Al enviar una tarea, usted elige el país al que pertenecen los números, y la lista debe corresponder esencialmente a ese único país. El resto de esta guía se centra en la vía síncrona.
Cómo preparar sus datos para la verificación
Antes de iniciar las solicitudes, asegúrese de que todos los números de teléfono de su conjunto de datos tengan el formato del plan internacional de numeración E.164. La API requiere un encabezado X-API-Key y un encabezado Content-Type: application/json. Utilice POST /api/v1/check con service_type=tg y un identifier E.164, o utilice el endpoint múltiple síncrono POST /api/v1/batch-check con service_type=tg y una matriz identifiers de hasta 100 números E.164. Como TG Validator se centra exclusivamente en Telegram, el tipo de servicio debe ser siempre tg.
Cómo diseñar un flujo de API de verificación telefónica en tiempo real
La gestión del rendimiento es el componente más importante de un flujo de API de verificación telefónica en tiempo real. La API de TG Validator limita cuántas verificaciones puede tener en curso una misma cuenta a la vez, y la documentación de la API indica el límite vigente. Su aplicación en el lado del cliente debe regular las solicitudes para mantenerse dentro de ese límite. Si su sistema supera este umbral, la API rechazará las solicitudes. Los rechazos por límite de concurrencia no se cobran y no generan ningún resultado de verificación, por lo que su aplicación debe estar diseñada para pausar y reintentar estas solicitudes concretas de forma segura.
Cómo interpretar la señal de registro
La API devuelve un sobre de respuesta documentado con code, message y data. Dentro de este sobre, el estado de registro en Telegram se encuentra en el campo data.registered. Este resultado sirve estrictamente como señal de presencia de cuenta en el momento de la verificación. El producto no devuelve campos avatar ni business, de modo que la respuesta se centra por completo en el estado de registro.
Supervisión y gestión de errores
Utilice el código de respuesta de la API para gestionar los fallos que admiten reintento; consulte la documentación de la API para conocer los códigos de error y los límites vigentes.
Preguntas frecuentes
¿Qué debo hacer si alcanzo el límite de concurrencia?
La API permite a cada cuenta solo un número limitado de verificaciones simultáneas, según se indica en la documentación de la API. Si lo supera, la API rechaza la solicitud sin cargar su saldo ni generar un resultado. Su aplicación debe capturar el código de error de concurrencia, hacer una breve pausa y reintentar la solicitud.
¿Un estado 'registered' confirma que se puede contactar con el usuario?
No. La señal de registro solo indica la presencia de una cuenta de Telegram en el momento exacto de la verificación.
¿Cómo debe gestionar el flujo una lista mayor que una solicitud?
Mantenga el endpoint múltiple síncrono como vía principal, hasta 100 identificadores por solicitud, dentro del límite de concurrencia documentado. Para una lista completa que supere con creces esa cifra, también está disponible una tarea masiva asíncrona (subir, esperar, descargar); al enviarla, usted elige el país al que pertenecen los números, la lista debe corresponder esencialmente a ese único país, y las cantidades mínimas y máximas de cada producto figuran en la documentación de la API.
¿Cómo se gestionan en la facturación las verificaciones fallidas?
Las verificaciones fallidas, agotadas por tiempo o indeterminadas no conservan el cargo. Consulte la página de precios para conocer los detalles vigentes de planes y saldo.