API de Validação e Formatação de Números de Telefone

A API de Validação de Telefones é compatível com 242 países.

A API de Validação e Formatação de Números de Telefone permite processar facilmente números de telefone inseridos pelos usuários em uma ampla variedade de formatos. Seja a entrada tão irregular quanto 1(212)-867-53-09, +1 212 8675309, 001-212.867.5309 ou simplesmente 2128675309, nossa API detectará inteligentemente a estrutura e retornará uma versão padronizada.

Esta ferramenta converte automaticamente a entrada fornecida para o formato E.164, que é o padrão reconhecido globalmente para números de telefone internacionais. Por exemplo, +1 212 867 5309 é retornado como +12128675309, tornando-o adequado para sistemas de chamadas internacionais e integrações.

Além da formatação, a API fornece recursos detalhados de validação de número de telefone. Ela verifica se o número é isValid: true — ou seja, um número válido de acordo com os planos nacionais de numeração. Também oferece a verificação isPossible: true, que indica se um número poderia existir, mesmo que não esteja atualmente atribuído. Isso é útil para validação prévia antes de salvar ou processar dados.

O parâmetro numberType ajuda a identificar se o número de telefone é celular, fixo ou VoIP. Isso é especialmente útil em cenários onde você deseja permitir apenas números móveis para verificações por SMS ou telefones fixos para contatos corporativos.

Com suporte para reconhecimento de código de área, a API também pode detectar a origem geográfica do número. Por exemplo, um número começando com o código de área 212 é automaticamente mapeado para Nova York (Manhattan). Esse recurso é perfeito para aplicativos que exigem segmentação ou análise baseada em localização.

Cada número também é associado a metadados detalhados por país, como o código de região ISO (por exemplo, US) e o código numérico do país (por exemplo, 1), permitindo lógica e formatos de exibição específicos por região em seus aplicativos.

✅ Resposta da API

Exemplo de resposta JSON:

{
  "status": true,
  "remaining_credits": 15709,
  "expires": 0,
  "duration": "18ms",
  "regionCode": "US",
  "countryCode": 1,
  "country": "Unites States",
  "national": "(212) 867-5309",
  "international": "+1 212-867-5309",
  "e164": "+12128675309",
  "isValid": true,
  "isPossible": true,
  "numberType": "FIXED_LINE_OR_MOBILE",
  "nationalSignificantNumber": "2128675309",
  "rawInput": "+1 212 867 5309",
  "isGeographical": true,
  "areaCode": "212",
  "location": "New York City (Manhattan)"
}

Teste a API de Validação de Telefone Você Mesmo

Uso Básico

Envie um número de telefone para o seguinte endpoint:

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309

Você pode obter sua chave de API gratuita diária com 200 créditos através deste link.

Parâmetro Address

A API também suporta um parâmetro opcional address, que pode ser extremamente útil em casos onde o número de telefone é fornecido sem um código de país internacional. Esse campo ajuda o sistema a detectar a região pretendida e interpretar corretamente o número. Por exemplo, se o número de entrada for 2128675309 e nenhum código de país for especificado, definir address=US, address=United States ou até mesmo address=New York pode ajudar a API a determinar que o número pertence aos Estados Unidos.

O parâmetro address aceita entradas em vários formatos, incluindo:

• Códigos ISO 3166-1 alpha-2 como US, DE ou TR
• Nomes de países como Alemanha, Turquia ou América
• Nomes de cidades ou regiões como Berlim, Istambul ou Nova York

Embora opcional, o parâmetro address torna-se obrigatório se o número de telefone não começar com um sinal de mais e um código de discagem internacional (por exemplo, +1, +44, +90). Sem essas informações contextuais, a API pode não conseguir interpretar corretamente o formato do número nacional.

Exemplo com parâmetro address:

https://api.genderapi.io/api/phone?key=YOUR_API_KEY&number=12128675309&address=US

Campos de Resposta

Valores do Tipo de Número

curl "https://api.genderapi.io/api/phone?number=+49 151 12345678&address=United States&key=YOUR_API_KEY"

curl "https://api.genderapi.io/api/phone?number=%2B49%20151%2012345678&address=United%20States&key=YOUR_API_KEY"

Validação de Telefone via Requisição POST

Você pode usar o método POST para validar um número de telefone dos Estados Unidos. Basta fornecer o número no formato E.164, nacional ou internacional junto com o país/endereço. Sua chave de API deve ser enviada como um token Bearer.

Exemplo com cURL

curl -X POST "https://api.genderapi.io/api/phone" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{"number": "+12128675309", "address": "US"}'

Exemplo de cURL em PHP

<?php
$url = "https://api.genderapi.io/api/phone";

$data = array(
    "number" => "+12128675309",
    "address" => "US"
);

$payload = json_encode($data);

$ch = curl_init($url);
curl_setopt($ch, CURLOPT_HTTPHEADER, array(
    "Content-Type: application/json",
    "Authorization: Bearer YOUR_API_KEY"
));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, $payload);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

Exemplo com fetch em JavaScript

fetch("https://api.genderapi.io/api/phone", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
  },
  body: JSON.stringify({
    number: "+12128675309",
    address: "United States"
  })
})
.then(response => response.json())
.then(data => console.log(data));

Exemplo com requests em Python

import requests

url = "https://api.genderapi.io/api/phone"

payload = {
    "number": "+12128675309",
    "address": "United States"
}

headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_API_KEY"
}

response = requests.post(url, headers=headers, json=payload)

print(response.json())

Bibliotecas Cliente

Para facilitar ainda mais a integração, oferecemos uma variedade de bibliotecas cliente oficiais e mantidas pela comunidade para diferentes linguagens de programação. Essas bibliotecas permitem que você interaja com os endpoints do GenderAPI — como a API de Validação de Número de Telefone — sem precisar lidar manualmente com requisições HTTP ou parsing de JSON. Basta escolher a biblioteca apropriada para seu ambiente, instalá-la e começar a fazer requisições com configuração mínima.

Você pode encontrar as bibliotecas disponíveis e instruções de instalação na seguinte página:
https://www.genderapi.io/pt/docs-client-libraries

Perguntas Frequentes (FAQ)

1. O que é a API de Validação e Formatação de Número de Telefone?

A API de Validação e Formatação de Número de Telefone é uma ferramenta que permite validar, formatar e analisar números de telefone de todo o mundo. Ela pode converter números para o formato padronizado E.164 e determinar metadados como região, tipo (celular/fixo), validade e muito mais.

2. Para que serve a Validação de Número de Telefone?

Serve para verificar se um número é válido, formatá-lo para uso internacional, identificar o tipo (por exemplo, celular, VoIP), detectar metadados baseados em região e garantir entradas limpas e padronizadas para CRM, ferramentas de marketing ou cadastros de usuários.

3. Quantos países são suportados?

A API suporta números de telefone de 242 países e territórios ao redor do mundo. Isso garante cobertura global para qualquer aplicação internacional ou regional.

4. Quais formatos são suportados?

A API aceita números em vários formatos, como nacional, internacional ou E.164. Ela detecta e normaliza automaticamente esses formatos.

5. O que acontece se eu omitir o parâmetro de país ou endereço?

Se o número não começar com um '+' e nenhum país/endereço for fornecido, a API pode não conseguir interpretar corretamente o número. É recomendado incluir o parâmetro address (como US, United States ou New York).

6. A API consegue detectar o tipo do número?

Sim. A API retorna o campo numberType, que indica se o número é MOBILE, FIXED_LINE, VOIP, etc.

7. Qual a diferença entre isValid e isPossible?

isValid significa que o número está oficialmente atribuído e segue todas as regras regionais. isPossible verifica se o número poderia existir teoricamente com base na estrutura, mesmo que ainda não tenha sido atribuído.

8. Que tipo de resposta a API retorna?

Uma resposta bem-sucedida inclui status, variantes do número formatado (nacional, internacional, E.164), dados de região, tipo de número, uso de créditos e mais. Veja a seção de exemplo de resposta da API para uma saída completa.

9. Como devo enviar minha chave de API?

Para requisições GET, adicione a chave como ?key=YOUR_API_KEY. Para requisições POST, use o token Bearer no cabeçalho assim:
"Authorization: Bearer YOUR_API_KEY".

10. O que significa uma resposta com status: false?

Isso significa que a solicitação falhou. O campo message incluirá o motivo do erro, como parâmetros ausentes, número inválido ou créditos insuficientes.

11. Caracteres especiais ou espaços são permitidos na entrada?

Sim, mas devem ser codificados em URL para requisições GET. Por exemplo, use %20 no lugar de espaços. Veja a seção de aviso acima para uso correto.

12. Posso usar endereços em diferentes formatos ou idiomas?

Sim. Além de códigos ISO 3166-1 alpha-2 (como US, DE, TR), o parâmetro address também aceita nomes completos de países ou cidades — mesmo em outros idiomas. A API utiliza inteligência artificial integrada para detectar e interpretar corretamente o país ou região. Por exemplo:

address=Deutschland
address=États-Unis
address=İstanbul
address=New York
address=Estados Unidos

Todas essas entradas serão corretamente mapeadas para seus respectivos países ou regiões pela API sem qualquer problema.