API para validação de telefone

Você tem números de telefone vindo de formulários, checkouts e CRMs, e precisa saber se são válidos, se são móveis ou não, a qual país pertencem e como formatá-los corretamente antes de enviar. Ao final deste artigo, você validará um número de telefone e extrairá operadora, país, tipo de linha, formatos padrão (E.164, internacional, nacional), fusos horários e mais usando uma única requisição HTTP GET.

O que esta API retorna e quando usá-la

A API de Validação de Telefone fornece validação instantânea e metadados ricos para um número de telefone específico. Você passa um parâmetro (o número de telefone) e recebe campos como:

• is_valid, is_possible: flags de validação que você pode usar para controlar fluxos
• provider, line_type, is_mobile: decisões de roteamento e canal de mensagens
• country, country_code, country_iso2/3, continent, country_flag: localização e conformidade
• format_national, format_e164, format_international, format_rfc3966: formatos de armazenamento e exibição
• time_zones, utc_offset: janelas de mensagens e agendamento
• currency_code, location, national_number: enriquecimento para faturamento ou CRM

Usos comuns incluem validação de formulários de inscrição, verificações de entregabilidade de SMS, normalização de telefone em bancos de dados de usuários, roteamento de clientes cientes do país e mensagens cientes do fuso horário.

Começando no Zyla API Hub

A API está disponível no Zyla API Hub, um marketplace de APIs com uma única conta, uma chave de API e um modelo de assinatura + cota em mais de 10.000 APIs públicas. Para começar:

1. Abra a listagem: Comece o teste de 7 dias na API de Validação de Telefone.
2. Clique em Assinar (ou comece o teste de 7 dias quando disponível) e obtenha sua chave de API. Não há Plano Gratuito; o acesso é por assinatura + cota, não por chamada. Verifique a página da API para opções de acesso e preços atuais.
3. Chame o endpoint com Authorization: Bearer YOUR_API_KEY.

Endpoint que você usará

Esta API expõe um endpoint de leitura simples.

• Método: GET
• URL: https://zylalabs.com/api/10138/phone-validator-api/26579/phone-validation
• Parâmetros de consulta:
  • phone (string, obrigatório): um número de telefone, por exemplo, +41799530236

exemplo cURL (copiar/colar)

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

Resposta de exemplo 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"
}

O que você provavelmente usará primeiro:

• is_valid e is_possible para aceitar ou rejeitar entradas na borda
• format_e164 para armazenamento canônico (uma única fonte de verdade)
• line_type e is_mobile para controlar SMS vs. voz vs. WhatsApp
• country_iso2, country_code e time_zones/utc_offset para roteamento e agendamento
• provider para regras específicas de operadora ou enriquecimento downstream

Exemplo em Python: validar e normalizar um número de telefone

Este exemplo chama o mesmo endpoint, verifica a validade e, em seguida, armazena o formato E.164 e alguns metadados que você pode querer em seu perfil de usuário.

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()

# Verificações mínimas para controlar inscrições ou enviar OTPs
if not data.get("is_valid") or not data.get("is_possible"):
return {
"accepted": False,
"reason": "Número inválido ou impossível",
"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 implementação que economizam tempo

• Armazenamento canônico: Use format_e164 como o campo de telefone canônico. Mantenha a entrada original separadamente se precisar de auditabilidade ou reexibição de UX.
• Exibição vs. discagem: Mostre format_national para usuários no mesmo país; use format_international para exibição transfronteiriça; use E.164 para discar ou enviar mensagens programaticamente.
• Agendamento de mensagens: Use time_zones e utc_offset para suprimir mensagens durante horários fora do expediente. Armazene ambos ao lado do usuário para que você possa agendar sem revalidar em cada envio.
• Controle de país: Se seu produto tiver restrições de país, controle durante a inscrição com country_iso2 e country_code.
• Seleção de canal: Use is_mobile e line_type para escolher SMS, voz ou canais alternativos.
• Cache: Armazene buscas bem-sucedidas por E.164 por uma janela razoável para reduzir a latência e o uso de cota para números frequentemente contatados.
• Tratamento de erros: Trate não-2xx como transitórios ou permanentes dependendo do contexto. Para ações de usuário síncronas (por exemplo, OTP), retorne uma mensagem legível; para trabalhos em lote, tente novamente com backoff.

Fluxos de ponta a ponta que você pode enviar esta semana

Formulário de inscrição: validar ao enviar

1. Ao enviar o formulário, envie o número inserido para o endpoint.
2. Rejeite se is_valid ou is_possible for falso. Exiba format_national para mostrar o formato corrigido.
3. Armazene format_e164, country_iso2 e line_type para fluxos downstream.

Roteamento de mensagens: escolha o canal certo

1. Observe is_mobile e line_type para determinar a elegibilidade para SMS.
2. Use provider se você tiver regras de envio baseadas em operadora.
3. Controle ou agende por time_zones/utc_offset para respeitar os horários locais.

Enriquecimento de CRM: padronizar números entre sistemas

1. Processar seus campos de telefone, chamando a API para cada número único.
2. Substitua formatos inconsistentes por format_e164 e mantenha national_number para pesquisa de UI ou chamadas locais.
3. Adicione country_iso2 e currency_code para habilitar operações e relatórios específicos da região.

Chamadas via MCP de agentes de IA

Você pode roteirizar chamadas através do endpoint MCP da Zyla, que funciona com Claude Code, Cursor, Windsurf e outros clientes compatíveis com MCP. Configure seu agente ou cliente para acessar:

MCP

Forneça sua chave de API Zyla (apikey=YOUR_API_KEY) para o endpoint MCP. A partir daí, seu agente pode invocar a mesma operação da API de Validação de Telefone sem embutir a lógica HTTP bruta em seus prompts. Isso é útil quando você deseja que um assistente valide números fornecidos pelo usuário durante um chat ou sessão de código.

Lista de verificação de produção

• Autenticação: envie Authorization: Bearer YOUR_API_KEY em cada requisição.
• Normalização de entrada: aceite a entrada do usuário com ou sem um + inicial, mas sempre armazene format_e164.
• Privacidade: trate números de telefone como PII. Registre minimamente e redija em rastros.
• Idempotência: de-duplicate chamadas por E.164 em seus trabalhadores de fila para evitar cobrança dupla de cota.
• Observabilidade: registre is_valid, is_possible, distribuição de line_type para capturar anomalias na entrada.
• Fallback UX: em timeouts da API, deixe os usuários prosseguirem com um aviso ou prompt para confirmar o número.

Dicas de solução de problemas

• 401/403 inesperado: certifique-se de que o cabeçalho Authorization usa Bearer YOUR_API_KEY e que a chave está ativa para sua assinatura.
• Nenhum dado retornado: verifique se o parâmetro phone está codificado em URL e inclui um prefixo de país quando disponível.
• Desajuste de formatação: prefira o formato canônico format_e164 da API em vez de bibliotecas de formatação de cliente local para consistência.

Referência: detalhes do endpoint

Validação de Telefone

• Método: GET
• URL: https://zylalabs.com/api/10138/phone-validator-api/26579/phone-validation
• Parâmetro de consulta: phone (string, obrigatório)
• Cabeçalho de autenticação: Authorization: Bearer YOUR_API_KEY
• Retorna: flags de validação, operadora, país e códigos ISO, continente, fusos horários e offset UTC, formatos nacional e internacional, URI RFC3966, tipo de linha, flag móvel, número nacional, flag do país e código de moeda.

Como avaliar custo e acesso

O acesso é por assinatura + cota, não por chamada. Não há Plano Gratuito. Um teste de 7 dias pode estar disponível; verifique a listagem para opções atuais. Se você estiver testando um novo fluxo, comece com o teste, implante atrás de uma bandeira de recurso e monitore o uso da cota antes de aumentar o tráfego.

FAQ

A API aceita números sem um + inicial?
Passe o parâmetro phone como você o recebe, mas para resultados confiáveis, inclua o código do país (por exemplo, +41...). A resposta fornece formatos padronizados, incluindo E.164.

Qual formato devo armazenar em meu banco de dados?
Armazene format_e164 como o valor canônico. Mantenha format_national ou format_international apenas se precisar exibi-los diretamente para os usuários.

Como posso decidir se envio SMS ou voz?
Use is_mobile e line_type. Envie SMS apenas quando is_mobile for verdadeiro e line_type indicar um número móvel.

Posso agendar mensagens com base no horário local do usuário?
Sim. Use time_zones e utc_offset para agendar no horário local. Persista esses campos para que você não precise revalidar em cada envio.

Onde consigo uma chave de API e como é feito o faturamento?
Inscreva-se na página de listagem para obter sua chave. O faturamento é por assinatura + cota. Comece com o teste de 7 dias quando disponível na listagem.

Envie isso

Você pode validar e normalizar números de telefone hoje com uma única chamada GET e um parâmetro obrigatório. Crie sua chave, insira o cabeçalho Authorization e padronize em E.164 em seu modelo de dados. Quando estiver pronto, comece aqui: Comece o teste de 7 dias na API de Validação de Telefone.