Você precisa verificar números de telefone antes de enviar OTPs, notificações SMS ou habilitar o cadastro de usuários. Ao final deste guia, você validará um número de telefone, inspecionará metadados de operadora/país/formato e testará tudo no Postman usando a API de Validação de Telefone no Zyla API Hub.
O que a API de Validação de Telefone faz
A API de Validação de Telefone verifica se um número de telefone é válido e retorna metadados ricos que você pode usar para roteamento, formatação ou bloqueio de mensagens. A resposta inclui bandeiras de validade, operadora/provedor, códigos de país e ISO, formatos nacional/internacional, fusos horários, tipo de linha (por exemplo, móvel) e mais.
Casos de uso típicos:
- Bloquear números inválidos ou descartáveis antes de criar contas.
- Formatar números no estilo E.164 ou internacional para processamento consistente a montante.
- Decidir se deve enviar SMS ou voz com base no tipo de linha.
- Exibir informações geográficas (país, fuso horário) nas ferramentas administrativas.
Como todos os serviços no Zyla API Hub, você usa uma conta e uma chave de API em todo o marketplace, com um modelo de assinatura e cota (não pago por chamada). Para esta API, o primeiro plano oferece um teste de 7 dias ou 50 solicitações, e não há Plano Gratuito. Verifique a página da API para opções de acesso e preços atuais.
Começando no Zyla API Hub
Para experimentar a API de Validação de Telefone em minutos:
- Abra a página da API: API de Validação de Telefone.
- Clique em Assinar (ou Começar Teste Gratuito quando disponível). O primeiro plano fornece um teste de 7 dias ou 50 solicitações; não há Plano Gratuito.
- Copie sua chave de API do seu painel. Todas as chamadas usam o cabeçalho Authorization: Bearer YOUR_API_KEY.
Se você ainda não tem uma conta, pode Registrar para criar uma e obter uma chave de API.
Endpoint que você usará
A API de Validação de Telefone expõe este endpoint no Zyla API Hub:
-
Validação de Telefone
Método: GET
URL: https://zylalabs.com/api/10138/phone-validator-api/26579/phone-validation
Parâmetro de consulta necessário:phone(string): Número de telefone a ser validado, por exemplo,+41799530236
Teste com Postman
1) Crie uma solicitação
Configure uma nova solicitação GET no Postman com o seguinte:
- Método: GET
- URL:
https://zylalabs.com/api/10138/phone-validator-api/26579/phone-validation?phone=%2B41799530236
2) Adicione autorização
Em Cabeçalhos, adicione:
Authorization:Bearer YOUR_API_KEY
3) Envie e inspecione a resposta
Clique em Enviar. Você deve receber uma resposta JSON com validade e metadados para o número.
cURL oficial que você pode copiar
curl -s -X GET "https://zylalabs.com/api/10138/phone-validator-api/26579/phone-validation?phone=%2B41799530236" \
-H "Authorization: Bearer YOUR_API_KEY"Exemplo de resposta oficial
{
"is_valid": true,
"is_disposable": false,
"provider": "Swisscom",
"location": "Suíça",
"country": "Suíça",
"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óvel",
"is_mobile": true,
"is_possible": true,
"national_number": "799530236",
"country_flag": "🇨🇭",
"currency_code": "CHF",
"utc_offset": "+02:00"
}Destaques de campos que você provavelmente usará:
is_valideis_possible: Controle a criação de contas e o envio de mensagens.line_typeeis_mobile: Roteie notificações via SMS ou canais alternativos.format_e164eformat_international: Persista um formato canônico em seu DB e mostre uma versão amigável ao usuário nas UIs administrativas.providerecountry_iso2: Análises e lógica de roteamento.time_zoneseutc_offset: Evite enviar mensagens à noite no local do destinatário.
Exemplo de JavaScript (Node.js)
Este exemplo chama o mesmo endpoint e usa os campos que você normalmente precisará para decidir se deve prosseguir com um SMS:
import fetch from "node-fetch";
async function validatePhone(phone) {
const url = new URL("https://zylalabs.com/api/10138/phone-validator-api/26579/phone-validation");
url.searchParams.set("phone", phone);
const res = await fetch(url.toString(), {
method: "GET",
headers: {
"Authorization": "Bearer YOUR_API_KEY"
}
});
if (!res.ok) {
const text = await res.text();
throw new Error(`HTTP ${res.status}: ${text}`);
}
const data = await res.json();
// Lógica mínima de controle
if (!data.is_valid || !data.is_possible) {
return { ok: false, reason: "Número inválido ou impossível", data };
}
if (data.line_type !== "mobile" || !data.is_mobile) {
return { ok: false, reason: "Linha não móvel; SMS pode falhar", data };
}
// Use E.164 canônico para armazenamento e sistemas a montante
return {
ok: true,
e164: data.format_e164,
provider: data.provider,
country: data.country,
iso2: data.country_iso2,
timeZones: data.time_zones,
rfc3966: data.format_rfc3966,
data
};
}
validatePhone("+41799530236")
.then(result => console.log(JSON.stringify(result, null, 2)))
.catch(err => console.error(err));Padrões de fluxo de trabalho que funcionam
- Controle de cadastro: Na inscrição do usuário, chame o endpoint. Se
!is_validou!is_possible, bloqueie a submissão e solicite correção. - Normalização de números: Armazene
format_e164como o valor canônico. Useformat_internationalpara visualizações voltadas para o operador eformat_nationalpara exibição local. - Guardiões de mensagens: Enfileire SMS apenas quando
is_mobile === trueeline_type === "mobile". Opcionalmente, atrase mensagens até que ostime_zoneslocais estejam dentro do horário comercial. - Roteamento e consciência de custo: Segmente o tráfego por
country_iso2,country_codeeproviderpara análises ou estratégias de envio por região.
Notas de implementação que economizam tempo
- Autorização: Sempre inclua
Authorization: Bearer YOUR_API_KEYnas solicitações. - Idempotência: A validação é somente leitura; você pode tentar novamente com segurança em erros de rede transitórios.
- Cache: Como os metadados do número são relativamente estáveis, armazene em cache validações positivas indexadas por
format_e164para reduzir buscas repetidas. - Formatação internacional: Prefira
format_e164para uso programático. Ele remove espaços e hífens e inclui o “+” inicial. - Hora e local:
utc_offseté retornado como uma string (por exemplo, +02:00). Usetime_zonespara conversões precisas. - Tratamento de erros: Trate respostas HTTP não-2xx como falhas operacionais; registre os corpos das respostas para ajudar a diagnosticar problemas de cota ou autorização.
- Modelo de assinatura: Zyla usa assinatura + cota, não pago por chamada. O primeiro plano desta API oferece um teste de 7 dias ou 50 solicitações; não há Plano Gratuito. Monitore seu uso no seu painel Zyla.
Lista de verificação de solução de problemas
- 401/403? Confirme se o cabeçalho de Autorização está presente e se a chave da API é válida.
- 4xx com conteúdo de mensagem? Verifique se o parâmetro de consulta
phoneestá fornecido e codificado na URL. - Campos vazios ou inesperados? Valide com um número diferente para descartar casos extremos. Persista
format_e164e execute novamente. - Problemas específicos do aplicativo? Registre a resposta JSON bruta para comparação rápida com o código de análise local.
Chame a API de agentes de IA via MCP
Toda API no Zyla pode ser chamada de ferramentas compatíveis com MCP, como Claude Code, Cursor e Windsurf. Aponte seu agente ou cliente para o endpoint MCP e passe sua chave de API na string de consulta:
https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY
A partir daí, seu agente pode invocar o mesmo endpoint de Validação de Telefone usando o roteamento do marketplace. Para detalhes de integração e configuração do cliente, consulte a documentação do MCP. Isso é útil quando você deseja que um assistente de IA valide números inline durante a geração de código ou execuções de teste.
Receita Postman de ponta a ponta que você pode reutilizar
Configuração da solicitação
- Nova Solicitação → GET
- URL:
https://zylalabs.com/api/10138/phone-validator-api/26579/phone-validation?phone=%2B41799530236 - Cabeçalhos:
Authorization: Bearer YOUR_API_KEY - Enviar
Scripts de teste rápidos (opcional)
Se você usar testes do Postman, pode adicionar afirmações rápidas como:
pm.test("HTTP 200", function () {
pm.response.to.have.status(200);
});
const body = pm.response.json();
pm.test("Número móvel válido", function () {
pm.expect(body.is_valid).to.eql(true);
pm.expect(body.is_mobile).to.eql(true);
});Por que usar o Zyla API Hub para esta integração
- Uma conta, uma chave de API, um modelo de assinatura em mais de 10.000 APIs públicas no hub.
- Faturamento centralizado com assinatura + cota (não pago por chamada) e painéis para monitorar o uso.
- Autenticação consistente em todos os endpoints: cabeçalho de Autorização com sua chave.
Explore serviços adicionais no Zyla API Hub quando estiver pronto para expandir este fluxo de trabalho (por exemplo, mensagens, enriquecimento ou ferramentas de fraude) sem mudar os modelos de autenticação.
FAQ
Qual é o endpoint exato para validação?
Use GET https://zylalabs.com/api/10138/phone-validator-api/26579/phone-validation com o parâmetro de consulta phone.
Como eu me autentico?
Passe sua chave no cabeçalho: Authorization: Bearer YOUR_API_KEY.
Há um plano gratuito?
Não. O primeiro plano 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.
Quais campos devo armazenar?
Persista format_e164 como o número canônico. Armazene is_valid, is_possible, line_type, country_iso2 e provider se forem relevantes para seu roteamento ou análises.
Posso chamar isso de um agente de IA?
Sim, via o endpoint MCP em https://mcp.zylalabs.com/mcp?apikey=YOUR_API_KEY. Consulte a documentação do MCP para detalhes do cliente.
Pronto para testar a API de Validação de Telefone em sua pilha? Abra a página da API de Validação de Telefone, assine e comece a chamá-la do Postman ou do código. Se você precisar de uma conta, Registre-se para obter sua chave de API e implemente sua integração esta semana.
