Gerador de Números de Telefone Virtual API no Zyla API Hub: Primeiro Pedido com curl e JSON

Você precisa de números virtuais descartáveis para receber SMS de uma única vez para fluxos de inscrição, QA ou testes de integração, e você precisa que isso funcione esta semana. Ao final deste guia, você listará os países suportados, buscará números disponíveis para um país e lerá o histórico de SMS para um número específico—usando curl primeiro, depois um script compacto em Node.js que você pode inserir em seu serviço.

O que o Gerador de Números de Telefone Virtual API faz

A Gerador de Números de Telefone Virtual API fornece:

Ilustração: Gerador de Números de Telefone Virtual API no Zyla API Hub: Primeiro Pedido com curl e JSON

Uma lista de países atualmente disponíveis de onde você pode obter números virtuais.
Números de telefone disponíveis para um código de país selecionado.
Histórico de SMS para um número de telefone e código de país dados (para que você possa ler os códigos de verificação recebidos).

Usos típicos incluem testes automatizados de contas, fluxos de integração em várias regiões ou construção de ferramentas internas para selecionar programaticamente um número e ler SMS recebidos. Você pode acessá-lo com a única chave do Zyla API Hub que você usa em todo o marketplace.

O Zyla API Hub agrega mais de 10.000 APIs públicas por trás de uma conta, uma chave de API e um modelo de assinatura. Explore o marketplace em zylalabs.com.

Começando no Zyla API Hub

Abra a página do Gerador de Números de Telefone Virtual API no Zyla API Hub e clique em Inscrever-se. O Zyla usa um modelo de assinatura + cota (não pague por chamada). Para esta API, a primeira assinatura oferece um teste de 7 dias ou 50 solicitações. Não há Plano Gratuito. Verifique a página da API para opções de acesso e preços atuais.

Após se inscrever, você receberá uma chave de API. Todas as solicitações usam o cabeçalho de Autorização: Authorization: Bearer YOUR_API_KEY

Se você ainda não tem uma conta, pode criar uma aqui: Registrar.

Endpoints que você usará

Todas as solicitações vão para as URLs do Hub do Zyla. Não chame domínios de fornecedores de origem. Passe sua chave no cabeçalho de Autorização.

1) Obter Países

Retorna a lista de países atualmente disponíveis.

Método: GET
URL: https://zylalabs.com/api/1813/virtual-phone-number-generator-api/1466/get-countries
Parâmetros: nenhum 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"

Resposta de exemplo oficial:

{
"status": 200,
"success": true,
"message": "",
"data": [
{
"countryCode": "1",
"countryName": "Estados Unidos
"
},
{
"countryCode": "1",
"countryName": "Canadá
"
},
{
"countryCode": "44",
"countryName": "Reino Unido
"
},
{
"countryCode": "34",
"countryName": "Espanha
"
},
{
"countryCode": "972",
"countryName": "Israel
"
},
{
"countryCode": "230",
"countryName": "Maurício
"
},
{
"countryCode": "91",
"countryName": "Índia
"
},
{
"countryCode": "385",
"countryName": "Croácia
"
},
{
"countryCode": "351",
"countryName": "Portugal
"
},
{
"countryCode": "381",
"countryName": "Sérvia
"
},
{
"countryCode": "52",
"countryName": "México
"
},
{
"countryCode": "55",
"countryName": "Brasil
"
},
{
"countryCode": "234",
"countryName": "Nigéria
"
}
]
}

O que ler:

status e success: status básico da solicitação.
data: array de países. Cada item inclui:
- countryCode: string do prefixo de discagem internacional (por exemplo, "44").
- countryName: string do nome do país; observe que inclui espaços em branco/novas linhas no final—remova isso em seu código.

2) Obter Número por ID do País

Retorna os números atualmente disponíveis para um código de país dado. Números deste endpoint podem ser usados com o endpoint de Verificar histórico 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 necessário:
- countryCode (string): por exemplo, 44

curl:

Resposta de exemplo:

O que ler:

data: array de números de telefone como strings. Para verificar o histórico de SMS, você pode precisar remover o prefixo do código do país antes de enviar o número (veja a nota sob o endpoint de histórico de SMS).

3) Verificar histórico de SMS

Retorna mensagens SMS recebidas pelo número de telefone e 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 necessários:
- countryCode (string): por exemplo, 1
- phoneNumber (string): por exemplo, 8578329806

Nota importante da API: Se você usar um número de telefone retornado por Obter Número por ID do País, remova o código do país antes de passá-lo aqui. Para a maioria dos países, remova os primeiros 2 dígitos do número completo. Sempre certifique-se de passar apenas a parte do número local junto com o countryCode correto.

curl:

O endpoint retorna o histórico de SMS para esse número. Os campos exatos da resposta não estão documentados aqui; registre o JSON bruto e analise o conteúdo da mensagem e os timestamps conforme necessário para seu fluxo de trabalho.

Node.js quickstart (fetch + parsing mínimo)

O seguinte exemplo em Node.js percorre o fluxo usual: listar países, escolher um código de país, buscar números disponíveis, normalizar o número para o histórico de SMS e, em seguida, buscar a caixa de entrada. Ele usa os mesmos endpoints e cabeçalhos descritos acima.

/**
* Node.js 18+ (fetch global). Defina YOUR_API_KEY via env ou substitua inline.
* Este script:
* 1) Lista países
* 2) Busca números para um código de país selecionado
* 3) Normaliza o número para o histórico de SMS
* 4) Busca o JSON do histórico de SMS e o 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;
}

// Remova o prefixo do código do país de uma string completa no formato E.164 quando necessário.
// A API observa: Para a maioria dos países, remova os primeiros 2 dígitos.
// O comportamento pode variar; verifique seu país-alvo.
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);

// Escolha um código de país (exemplo: use o Reino Unido "44" se disponível)
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 esse 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) Normalize para histórico de SMS conforme orientação da API
const localNumber = stripCountryCode(fullNumber, countryCode);
console.log('Full number:', fullNumber, 'Local for history:', localNumber);

// 4) Histórico de SMS
const inbox = await checkSmsHistory(countryCode, localNumber);
console.log('SMS history raw:', inbox);

// Como a forma da resposta não está documentada aqui,
// processe a carga com base na estrutura observada.
})();

Primeiras chamadas com curl

Os desenvolvedores costumam começar com curl para validar a autenticação e as formas de resposta. Esses três comandos cobrem o caminho comum.

Listar países:
Obter números do Reino Unido (countryCode=44): Forma esperada:
Verificar histórico de SMS (exemplo com código dos EUA 1 e número local 8578329806):

Notas práticas de integração

Cabeçalho de autenticação: Sempre envie Authorization: Bearer YOUR_API_KEY. Não envie chaves como parâmetros de consulta.
Nomes de países: os valores de countryName podem incluir espaços em branco ou caracteres de nova linha no final. Remova antes de comparar ou exibir.
Normalização de números: Quando você obtiver um número de Obter Número por ID do País, remova o código do país antes de chamar Verificar histórico de SMS. Para a maioria dos países, remova os primeiros 2 dígitos. Valide com solicitações de teste para sua região-alvo.
Cache: A lista de países geralmente muda com menos frequência do que os dados da caixa de entrada. Armazene em cache Obter Países por minutos a horas, dependendo do seu caso de uso e estratégia de cota.
Cotas: As APIs do Zyla funcionam em um modelo de assinatura + cota. Para esta API, a primeira assinatura inclui um teste de 7 dias ou 50 solicitações. Monitore o uso em seu painel do Zyla.
Tratamento de erros: Verifique os códigos de status HTTP e os campos de status/sucesso do JSON. Registre respostas brutas durante o desenvolvimento para entender quaisquer erros de validação.
Ambientes: Use chaves separadas para projetos de desenvolvimento e produção para isolar cotas e logs.

Fluxos de trabalho comuns

Criação automatizada de contas de teste

Chame Obter Países e selecione o país onde a integração do seu produto deve ser testada.
Busque um número com Obter Número por ID do País.
Acione seu aplicativo-alvo para enviar um SMS para esse número.
Chame Verificar histórico de SMS com countryCode + número local para ler o código de verificação.

Integração em várias regiões

Pré-carregue uma lista de códigos de países de Obter Países.
Para cada região, alterne entre os números disponíveis de Obter Número por ID do País.
Busque e analise o conteúdo do SMS via Verificar histórico de SMS para desbloquear fluxos transfronteiriços.

Ferramentas internas

Construa um pequeno painel que envolva os três endpoints com o SSO da sua equipe.
Mostre a disponibilidade por país de Obter Países e Obter Número por ID do País.
Forneça um botão "ler último SMS" por número usando Verificar histórico de SMS.

Chame esta API de um agente de IA via MCP

Você também pode acessar esta API de ferramentas compatíveis com MCP (Claude Code, Cursor, Windsurf, etc.). Aponte seu agente para o gateway MCP:

Endpoint: https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY

Uma vez configurado, instrua o agente a realizar a mesma sequência que você usou acima: listar países, escolher um countryCode, buscar números, remover o código do país do número escolhido e, em seguida, chamar o endpoint de histórico de SMS com o número local. Para obter informações sobre o acesso ao MCP, veja a página MCP.

Onde explorar e próximos passos

Comece pela listagem da API e teste os exemplos de curl diretamente no console do Hub: Gerador de Números de Telefone Virtual API. Navegue por outras categorias em zylalabs.com—existem mais de 10.000 APIs públicas sob uma conta e uma chave de API.

FAQ

Como faço para autenticar solicitações?
Envie um cabeçalho HTTP: Authorization: Bearer YOUR_API_KEY em cada solicitação para as URLs do Zyla Hub.

Qual código de país devo passar para Obter Número por ID do País?
Use o valor countryCode retornado por Obter Países (por exemplo, "44" para o Reino Unido). É uma string; mantenha-a como está em seu parâmetro de consulta.

Por que Verificar histórico de SMS não funciona com o número completo de Obter Número por ID do País?
De acordo com a nota da API, remova o código do país ao passar phoneNumber para Verificar histórico de SMS. Para a maioria dos países, isso significa descartar os primeiros dois dígitos. Mantenha countryCode como o parâmetro de consulta separado.

Há um plano gratuito?
Não há Plano Gratuito. A primeira assinatura oferece um teste de 7 dias ou 50 solicitações. Verifique a página da API para opções de acesso e preços atuais.

Posso chamar essas APIs de um assistente de codificação de IA?
Sim. Use o endpoint MCP em https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY em um cliente compatível com MCP e emita as mesmas chamadas de endpoint via o agente.

Pronto para enviar sua integração? Crie sua conta, inscreva-se e obtenha sua chave agora: Registrar. Em seguida, abra a Gerador de Números de Telefone Virtual API para fazer seu primeiro pedido.