API para validación de teléfonos

Tienes números de teléfono que llegan de formularios, procesos de compra y CRM, y necesitas saber si son válidos, si son móviles o no, a qué país pertenecen y cómo formatearlos correctamente antes de enviarlos. Al final de este artículo, validarás un número de teléfono y extraerás el proveedor, país, tipo de línea, formatos estándar (E.164, internacional, nacional), zonas horarias y más utilizando una sola solicitud HTTP GET.

Qué devuelve esta API y cuándo usarla

La API de Validación de Teléfonos proporciona validación instantánea y metadatos ricos para un número de teléfono dado. Pasas un parámetro (el número de teléfono) y recibes campos como:

• is_valid, is_possible: indicadores de validación en los que puedes basar flujos
• provider, line_type, is_mobile: decisiones de enrutamiento y canal de mensajería
• country, country_code, country_iso2/3, continent, country_flag: localización y cumplimiento
• format_national, format_e164, format_international, format_rfc3966: formatos de almacenamiento y visualización
• time_zones, utc_offset: ventanas de mensajería y programación
• currency_code, location, national_number: enriquecimiento para facturación o CRM

Los usos comunes incluyen validación de formularios de registro, verificación de entregabilidad de SMS, normalización de teléfonos en bases de datos de usuarios, enrutamiento de clientes consciente del país y mensajería consciente de la zona horaria.

Comenzando en Zyla API Hub

La API está disponible en Zyla API Hub, un mercado de API con una sola cuenta, una clave de API y un modelo de suscripción + cuota en más de 10,000 API públicas. Para comenzar:

1. Abre la lista: Comienza prueba de 7 días en la API de Validación de Teléfonos.
2. Haz clic en Suscribirse (o comienza la prueba de 7 días cuando esté disponible) y obtén tu clave de API. No hay Plan Gratuito; el acceso es por suscripción + cuota, no por llamada. Consulta la página de la API para las opciones de acceso y precios actuales.
3. Llama al endpoint con Authorization: Bearer YOUR_API_KEY.

Endpoint que usarás

Esta API expone un endpoint de lectura sencillo.

• Método: GET
• URL: https://zylalabs.com/api/10138/phone-validator-api/26579/phone-validation
• Parámetros de consulta:
  • phone (string, requerido): un número de teléfono, por ejemplo, +41799530236

Ejemplo de cURL (copia/pega)

curl -s -X GET "https://zylalabs.com/api/10138/phone-validator-api/26579/phone-validation?phone=%2B41799530236" \
-H "Authorization: Bearer YOUR_API_KEY"

Respuesta de muestra oficial

{
"is_valid": true,
"is_disposable": false,
"provider": "Swisscom",
"location": "Suiza",
"country": "Suiza",
"country_iso2": "CH",
"country_iso3": "CHE",
"country_code": 41,
"continent": "Europa",
"time_zones": [
"Europe/Zurich"
],
"format_national": "079 953 02 36",
"format_e164": "+41799530236",
"format_international": "+41 79 953 02 36",
"format_rfc3966": "tel:+41-79-953-02-36",
"line_type": "móvil",
"is_mobile": true,
"is_possible": true,
"national_number": "799530236",
"country_flag": "🇨🇭",
"currency_code": "CHF",
"utc_offset": "+02:00"
}

Lo que probablemente usarás primero:

• is_valid e is_possible para aceptar o rechazar la entrada en el límite
• format_e164 para almacenamiento canónico (única fuente de verdad)
• line_type e is_mobile para decidir entre SMS, voz o WhatsApp
• country_iso2, country_code y time_zones/utc_offset para enrutamiento y programación
• provider para reglas específicas del proveedor o enriquecimiento posterior

Ejemplo en Python: validar y normalizar un número de teléfono

Este ejemplo llama al mismo endpoint, verifica la validez y luego almacena el formato E.164 y algunos metadatos que podrías querer en tu perfil de usuario.

import requests

API_URL = "https://zylalabs.com/api/10138/phone-validator-api/26579/phone-validation"
API_KEY = "YOUR_API_KEY"

def validate_phone(phone: str) -> dict:
params = {"phone": phone}
headers = {"Authorization": f"Bearer {API_KEY}"}
resp = requests.get(API_URL, params=params, headers=headers, timeout=10)
resp.raise_for_status()
data = resp.json()

# Comprobaciones mínimas para limitar registros o enviar OTPs
if not data.get("is_valid") or not data.get("is_possible"):
return {
"accepted": False,
"reason": "Número inválido o imposible",
"raw": data
}

normalized = {
"accepted": True,
"e164": data.get("format_e164"),
"national": data.get("format_national"),
"international": data.get("format_international"),
"rfc3966": data.get("format_rfc3966"),
"is_mobile": data.get("is_mobile"),
"line_type": data.get("line_type"),
"carrier": data.get("provider"),
"country": data.get("country"),
"country_iso2": data.get("country_iso2"),
"country_code": data.get("country_code"),
"continent": data.get("continent"),
"time_zones": data.get("time_zones"),
"utc_offset": data.get("utc_offset"),
"currency_code": data.get("currency_code"),
"national_number": data.get("national_number"),
"country_flag": data.get("country_flag"),
"is_disposable": data.get("is_disposable"),
}
return normalized

if __name__ == "__main__":
result = validate_phone("+41799530236")
print(result)

Notas de implementación que ahorran tiempo

• Almacenamiento canónico: Usa format_e164 como el campo de teléfono canónico. Mantén la entrada original por separado si necesitas auditabilidad o re-mostrado de UX.
• Visualización vs. marcado: Muestra format_national a los usuarios en el mismo país; usa format_international para visualización transfronteriza; usa E.164 para marcar o enviar mensajes programáticamente.
• Programación de mensajes: Usa time_zones y utc_offset para suprimir mensajes durante horas no laborales. Almacena ambos junto al usuario para que puedas programar sin revalidar en cada envío.
• Limitación por país: Si tu producto tiene restricciones por país, limita durante el registro con country_iso2 y country_code.
• Selección de canal: Usa is_mobile y line_type para elegir SMS, voz o canales alternativos.
• Cacheo: Almacena búsquedas exitosas por E.164 durante un tiempo razonable para reducir la latencia y el uso de cuota para números contactados frecuentemente.
• Manejo de errores: Trata los códigos no 2xx como transitorios o permanentes dependiendo del contexto. Para acciones de usuario sincrónicas (por ejemplo, OTP), devuelve un mensaje legible; para trabajos por lotes, reintenta con retroceso.

Flujos de extremo a extremo que puedes enviar esta semana

Formulario de registro: validar al enviar

1. Al enviar el formulario, envía el número ingresado al endpoint.
2. Rechaza si is_valid o is_possible es falso. Muestra format_national para mostrar el formato corregido.
3. Almacena format_e164, country_iso2 y line_type para flujos posteriores.

Enrutamiento de mensajería: elige el canal correcto

1. Mira is_mobile y line_type para determinar la elegibilidad de SMS.
2. Usa provider si tienes reglas de envío basadas en el proveedor.
3. Controla o programa por time_zones/utc_offset para respetar las horas locales.

Enriquecimiento de CRM: estandariza números en todos los sistemas

1. Procesa tus campos de teléfono, llamando a la API para cada número único.
2. Reemplaza formatos inconsistentes con format_e164 y mantén national_number para búsqueda en UI o marcaciones locales.
3. Agrega country_iso2 y currency_code para habilitar operaciones y reportes específicos de la región.

Llamadas a través de MCP desde agentes de IA

Puedes enrutar llamadas a través del endpoint MCP de Zyla, que funciona con Claude Code, Cursor, Windsurf y otros clientes compatibles con MCP. Configura tu agente o cliente para alcanzar:

MCP

Proporciona tu clave de API de Zyla (apikey=YOUR_API_KEY) al endpoint MCP. Desde allí, tu agente puede invocar la misma operación de la API de Validación de Teléfonos sin incrustar lógica HTTP cruda en tus mensajes. Esto es útil cuando deseas que un asistente valide números proporcionados por el usuario durante un chat o sesión de código.

Lista de verificación de producción

• Autenticación: envía Authorization: Bearer YOUR_API_KEY en cada solicitud.
• Normalización de entrada: acepta la entrada del usuario con o sin un + inicial, pero siempre almacena format_e164.
• Privacidad: trata los números de teléfono como PII. Registra mínimamente y oculta en los rastros.
• Idempotencia: elimina duplicados de llamadas por E.164 en tus trabajadores de cola para evitar cargos dobles de cuota.
• Observabilidad: registra is_valid, is_possible, distribución de line_type para detectar anomalías en la entrada.
• UX de respaldo: en tiempos de espera de API, permite que los usuarios continúen con una advertencia o aviso para confirmar el número.

Consejos de solución de problemas

• 401/403 inesperados: asegúrate de que el encabezado Authorization use Bearer YOUR_API_KEY y que la clave esté activa para tu suscripción.
• Sin datos devueltos: verifica que el parámetro phone esté codificado en URL e incluya un prefijo de país cuando esté disponible.
• Desajuste de formato: prefiere el formato canónico format_e164 de la API sobre las bibliotecas de formato de cliente local para consistencia.

Referencia: detalles del endpoint

Validación de Teléfonos

• Método: GET
• URL: https://zylalabs.com/api/10138/phone-validator-api/26579/phone-validation
• Parámetro de consulta: phone (string, requerido)
• Encabezado de autenticación: Authorization: Bearer YOUR_API_KEY
• Devuelve: indicadores de validación, proveedor, país y códigos ISO, continente, zonas horarias y offset UTC, formatos nacional e internacional, URI RFC3966, tipo de línea, indicador móvil, número nacional, bandera del país y código de moneda.

Cómo evaluar costo y acceso

El acceso es por suscripción + cuota, no por llamada. No hay Plan Gratuito. Puede haber una prueba de 7 días disponible; consulta la lista para las opciones actuales. Si estás probando un nuevo flujo, comienza con la prueba, despliega detrás de una bandera de función y monitorea el uso de cuota antes de aumentar el tráfico.

FAQ

¿La API acepta números sin un + inicial?
Pasa el parámetro phone tal como lo recibes, pero para resultados confiables incluye el código de país (por ejemplo, +41...). La respuesta proporciona formatos estandarizados, incluyendo E.164.

¿Qué formato debo almacenar en mi base de datos?
Almacena format_e164 como el valor canónico. Mantén format_national o format_international solo si necesitas mostrarlos directamente a los usuarios.

¿Cómo puedo decidir si enviar SMS o voz?
Usa is_mobile y line_type. Solo envía SMS cuando is_mobile sea verdadero y line_type indique un número móvil.

¿Puedo programar mensajes basados en la hora local del usuario?
Sí. Usa time_zones y utc_offset para programar en hora local. Persiste estos campos para que no necesites revalidar en cada envío.

¿Dónde obtengo una clave de API y cómo se maneja la facturación?
Suscríbete en la página de la lista para obtener tu clave. La facturación es por suscripción + cuota. Comienza con la prueba de 7 días cuando esté disponible en la lista.

Envíalo

Puedes validar y normalizar números de teléfono hoy con una sola llamada GET y un parámetro requerido. Crea tu clave, conecta el encabezado de autorización y estandariza en E.164 en tu modelo de datos. Cuando estés listo, comienza aquí: Comienza prueba de 7 días en la API de Validación de Teléfonos.