Necesitas números virtuales desechables para recibir SMS de un solo uso para flujos de registro, QA o pruebas de incorporación, y necesitas que funcione esta semana. Al final de esta guía, listarás los países soportados, obtendrás números disponibles para un país y leerás el historial de SMS para un número específico, utilizando curl primero, luego un script compacto de Node.js que puedes integrar en tu servicio.
Qué hace el Generador de Números de Teléfono Virtual API
El Generador de Números de Teléfono Virtual API proporciona:
- Una lista de los países actualmente disponibles de los cuales puedes obtener números virtuales.
- Números de teléfono disponibles para un código de país seleccionado.
- Historial de SMS para un número de teléfono y código de país dados (para que puedas leer los códigos de verificación recibidos).
Los usos típicos incluyen pruebas automatizadas de cuentas, flujos de incorporación en múltiples regiones o la construcción de herramientas internas para seleccionar programáticamente un número y leer SMS entrantes. Puedes acceder a ello con la única clave de Zyla API Hub que utilizas en todo el mercado.
Zyla API Hub agrega más de 10,000 APIs públicas detrás de una cuenta, una clave API y un modelo de suscripción. Explora el mercado en zylalabs.com.
Comenzando en Zyla API Hub
Abre la página del Generador de Números de Teléfono Virtual API en Zyla API Hub y haz clic en Suscribirse. Zyla utiliza un modelo de suscripción + cuota (no pago por llamada). Para esta API, la primera suscripción ofrece una prueba de 7 días o 50 solicitudes. No hay Plan Gratuito. Consulta la página de la API para las opciones de acceso y precios actuales.
Después de suscribirte, recibirás una clave API. Todas las solicitudes utilizan el encabezado de Autorización: Authorization: Bearer YOUR_API_KEY
Si aún no tienes una cuenta, puedes crear una aquí: Registrarse.
Puntos finales que usarás
Todas las solicitudes van a las URL del Hub de Zyla. No llames a los dominios de los proveedores de origen. Pasa tu clave en el encabezado de Autorización.
1) Obtener Países
Devuelve la lista de países actualmente disponibles.
- Método: GET
- URL: https://zylalabs.com/api/1813/virtual-phone-number-generator-api/1466/get-countries
- Params: ninguno documentado
curl:
curl -s -X GET "https://zylalabs.com/api/1813/virtual-phone-number-generator-api/1466/get-countries" \
-H "Authorization: Bearer YOUR_API_KEY"Respuesta de muestra oficial:
{
"status": 200,
"success": true,
"message": "",
"data": [
{
"countryCode": "1",
"countryName": "Estados Unidos
"
},
{
"countryCode": "1",
"countryName": "Canadá
"
},
{
"countryCode": "44",
"countryName": "Reino Unido
"
},
{
"countryCode": "34",
"countryName": "España
"
},
{
"countryCode": "972",
"countryName": "Israel
"
},
{
"countryCode": "230",
"countryName": "Mauricio
"
},
{
"countryCode": "91",
"countryName": "India
"
},
{
"countryCode": "385",
"countryName": "Croacia
"
},
{
"countryCode": "351",
"countryName": "Portugal
"
},
{
"countryCode": "381",
"countryName": "Serbia
"
},
{
"countryCode": "52",
"countryName": "México
"
},
{
"countryCode": "55",
"countryName": "Brasil
"
},
{
"countryCode": "234",
"countryName": "Nigeria
"
}
]
}Qué leer:
- status y success: estado básico de la solicitud.
- data: array de países. Cada elemento incluye:
- countryCode: prefijo de marcado internacional como cadena (por ejemplo, "44").
- countryName: nombre del país como cadena; ten en cuenta que incluye espacios en blanco/nuevas líneas al final—recórtalo en tu código.
2) Obtener Número por ID de País
Devuelve los números actualmente disponibles para un código de país dado. Los números de este punto final pueden ser utilizados con el punto final de Verificar historial de SMS.
- Método: GET
- URL: https://zylalabs.com/api/1813/virtual-phone-number-generator-api/1467/get-number-by-country-id
- Parámetro de consulta requerido:
- countryCode (cadena): por ejemplo, 44
curl:
Respuesta de ejemplo:
Qué leer:
- data: array de números de teléfono como cadenas. Para Verificar historial de SMS, es posible que debas eliminar el prefijo del código de país antes de enviar el número (consulta la nota bajo el punto final de historial de SMS).
3) Verificar historial de SMS
Devuelve los mensajes SMS recibidos por el número de teléfono y el código de país especificados.
- Método: GET
- URL: https://zylalabs.com/api/1813/virtual-phone-number-generator-api/1469/check-sms-history
- Parámetros de consulta requeridos:
- countryCode (cadena): por ejemplo, 1
- phoneNumber (cadena): por ejemplo, 8578329806
Nota importante de la API: Si usas un número de teléfono devuelto por Obtener Número por ID de País, elimina el código de país antes de pasarlo aquí. Para la mayoría de los países, elimina los primeros 2 dígitos del número completo. Siempre asegúrate de pasar solo la parte del número local junto con el countryCode correcto.
curl:
El punto final devuelve el historial de SMS para ese número. Los campos de respuesta exactos no están documentados aquí; registra el JSON en bruto y analiza el contenido del mensaje y las marcas de tiempo según sea necesario para tu flujo de trabajo.
Inicio rápido de Node.js (fetch + análisis mínimo)
El siguiente ejemplo de Node.js recorre el flujo habitual: listar países, elegir un código de país, obtener números disponibles, normalizar el número para el historial de SMS y luego obtener la bandeja de entrada. Utiliza los mismos puntos finales y encabezados descritos anteriormente.
/**
* Node.js 18+ (fetch global). Establece YOUR_API_KEY a través de env o reemplaza en línea.
* Este script:
* 1) Lista países
* 2) Obtiene números para un código de país seleccionado
* 3) Normaliza el número para el historial de SMS
* 4) Obtiene JSON del historial de SMS y lo imprime
*/
const API_KEY = process.env.ZYLA_API_KEY || 'YOUR_API_KEY';
const BASE = 'https://zylalabs.com/api/1813/virtual-phone-number-generator-api';
async function getCountries() {
const res = await fetch(`${BASE}/1466/get-countries`, {
headers: { Authorization: `Bearer ${API_KEY}` }
});
if (!res.ok) throw new Error(`get-countries failed: ${res.status}`);
const json = await res.json();
return json;
}
async function getNumbersByCountryCode(countryCode) {
const url = `${BASE}/1467/get-number-by-country-id?countryCode=${encodeURIComponent(countryCode)}`;
const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
if (!res.ok) throw new Error(`get-number-by-country-id failed: ${res.status}`);
const json = await res.json();
return json;
}
async function checkSmsHistory(countryCode, phoneNumber) {
const url = `${BASE}/1469/check-sms-history?countryCode=${encodeURIComponent(countryCode)}&phoneNumber=${encodeURIComponent(phoneNumber)}`;
const res = await fetch(url, { headers: { Authorization: `Bearer ${API_KEY}` } });
if (!res.ok) throw new Error(`check-sms-history failed: ${res.status}`);
const json = await res.json();
return json;
}
// Elimina el prefijo del código de país de una cadena completa similar a E.164 cuando sea necesario.
// La API nota: Para la mayoría de los países, elimina los primeros 2 dígitos.
// El comportamiento puede variar; verifica tu país objetivo.
function stripCountryCode(fullNumber, countryCode) {
const cc = String(countryCode);
return fullNumber.startsWith(cc) ? fullNumber.slice(cc.length) : fullNumber;
}
function trimCountryName(name) {
return String(name).trim();
}
(async () => {
// 1) Países
const countries = await getCountries();
console.log('Countries raw:', countries);
// Elige un código de país (ejemplo: usa Reino Unido "44" si está disponible)
const uk = (countries.data || []).find(c => trimCountryName(c.countryName) === 'Reino Unido');
const countryCode = uk ? uk.countryCode : '44';
console.log('Using countryCode:', countryCode);
// 2) Números para ese país
const numbers = await getNumbersByCountryCode(countryCode);
console.log('Numbers raw:', numbers);
if (!numbers.data || numbers.data.length === 0) {
console.log('No numbers available for countryCode', countryCode);
return;
}
const fullNumber = numbers.data[0];
// 3) Normaliza para el historial de SMS según la guía de la API
const localNumber = stripCountryCode(fullNumber, countryCode);
console.log('Full number:', fullNumber, 'Local for history:', localNumber);
// 4) Historial de SMS
const inbox = await checkSmsHistory(countryCode, localNumber);
console.log('SMS history raw:', inbox);
// Debido a que la forma de respuesta no está documentada aquí,
// procesa la carga útil según la estructura que observaste.
})();Primeras llamadas con curl
Los desarrolladores a menudo comienzan con curl para validar la autenticación y las formas de respuesta. Estos tres comandos cubren el camino común.
- Listar países:
- Obtener números del Reino Unido (countryCode=44): Forma esperada:
- Verificar historial de SMS (ejemplo con código de EE. UU. 1 y número local 8578329806):
Notas de integración práctica
- Encabezado de autenticación: Siempre envía Authorization: Bearer YOUR_API_KEY. No envíes claves como parámetros de consulta.
- Nombres de países: los valores de countryName pueden incluir espacios en blanco o caracteres de nueva línea al final. Recórtalos antes de comparar o mostrar.
- Normalización de números: Cuando obtienes un número de Obtener Número por ID de País, elimina el código de país antes de llamar a Verificar historial de SMS. Para la mayoría de los países, elimina los primeros 2 dígitos. Valida con solicitudes de prueba para tu región objetivo.
- Cacheo: La lista de países generalmente cambia con menos frecuencia que los datos de bandeja de entrada. Cachea Obtener Países durante minutos a horas dependiendo de tu caso de uso y estrategia de cuotas.
- Cuotas: Las APIs de Zyla funcionan con un modelo de suscripción + cuota. Para esta API, la primera suscripción incluye una prueba de 7 días o 50 solicitudes. Monitorea el uso en tu panel de Zyla.
- Manejo de errores: Verifica los códigos de estado HTTP y los campos de estado/success de JSON. Registra las respuestas en bruto durante el desarrollo para entender cualquier error de validación.
- Entornos: Usa claves separadas para proyectos de desarrollo y producción para aislar cuotas y registros.
Flujos de trabajo comunes
Creación de cuentas de prueba automatizadas
- Llama a Obtener Países y selecciona el país donde debe probarse la incorporación de tu producto.
- Obtén un número con Obtener Número por ID de País.
- Activa tu aplicación objetivo para enviar un SMS a ese número.
- Llama a Verificar historial de SMS con countryCode + número local para leer el código de verificación.
Incorporación en múltiples regiones
- Precarga una lista permitida de códigos de país desde Obtener Países.
- Para cada región, rota a través de los números disponibles desde Obtener Número por ID de País.
- Obtén y analiza el contenido de SMS a través de Verificar historial de SMS para desbloquear flujos transfronterizos.
Herramientas internas
- Crea un pequeño panel que envuelva los tres puntos finales con el SSO de tu equipo.
- Muestra la disponibilidad por país desde Obtener Países y Obtener Número por ID de País.
- Proporciona un botón de “leer el último SMS” por número usando Verificar historial de SMS.
Llama a esta API desde un agente de IA a través de MCP
También puedes acceder a esta API desde herramientas compatibles con MCP (Claude Code, Cursor, Windsurf, etc.). Dirige tu agente a la puerta de enlace MCP:
Punto final: https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
Una vez configurado, instruye al agente para que realice la misma secuencia que usaste arriba: lista países, elige un countryCode, obtiene números, elimina el código de país del número elegido, y luego llama al punto final del historial de SMS con el número local. Para más información sobre el acceso a MCP, consulta la página de MCP.
Dónde explorar y próximos pasos
Comienza desde la lista de API y prueba las muestras de curl directamente en la consola del Hub: Generador de Números de Teléfono Virtual API. Navega por otras categorías en zylalabs.com—hay más de 10,000 APIs públicas bajo una cuenta y una clave API.
FAQ
¿Cómo autentico las solicitudes?
Envía un encabezado HTTP: Authorization: Bearer YOUR_API_KEY en cada solicitud a las URL del Hub de Zyla.
¿Qué código de país debo pasar a Obtener Número por ID de País?
Usa el valor de countryCode devuelto por Obtener Países (por ejemplo, "44" para Reino Unido). Es una cadena; mantenlo tal cual en tu parámetro de consulta.
¿Por qué no funciona Verificar historial de SMS con el número completo de Obtener Número por ID de País?
Según la nota de la API, elimina el código de país al pasar phoneNumber a Verificar historial de SMS. Para la mayoría de los países, eso significa eliminar los primeros dos dígitos. Mantén countryCode como el parámetro de consulta separado.
¿Hay un plan gratuito?
No hay Plan Gratuito. La primera suscripción ofrece una prueba de 7 días o 50 solicitudes. Consulta la página de la API para las opciones de acceso y precios actuales.
¿Puedo llamar a estas APIs desde un asistente de codificación de IA?
Sí. Usa el punto final de MCP en https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY en un cliente compatible con MCP y emite las mismas llamadas a los puntos finales a través del agente.
¿Listo para enviar tu integración? Crea tu cuenta, suscríbete y obtén tu clave ahora: Registrarse. Luego abre el Generador de Números de Teléfono Virtual API para hacer tu primera solicitud.
