Validação
API de validação de telefones
API REST JSON rápida da Cleariflow para validação estrutural de telefones, normalização E.164 e detalhes opcionais de operadora, localização, fuso horário e marcação.
GET
API de validação de telefones
É muito simples: envie a sua chave API e um número de telefone. A API indica se o número é estruturalmente válido e, quando válido, devolve formatos E.164 normalizados e metadados opcionais como tipo de linha, geocodificação, operadora, fusos horários e indicadores de marcação quando disponíveis.
O que significa
Resposta válida (
Resposta inválida (
valid: true significa que o número corresponde às regras de formato regional (comprimento, prefixo, sintaxe). Não confirma que a linha está ativa, atribuída a um assinante ou é contactável. Para o estado da linha em tempo real precisa de carrier lookup, que fica fora do âmbito desta API.Primeiros passos
REST
A API de validação de números de telefone, como todas as APIs Cleariflow, está organizada em torno de REST. Foi concebida para usar URLs previsíveis orientadas a recursos e códigos de estado HTTP para indicar erros.HTTPS
A API de validação de números de telefone exige que todas as comunicações sejam protegidas com TLS 1.2 ou superior.Versões da API
Todas as APIs Cleariflow são versionadas. A API de validação de números de telefone está atualmente na versão 1.A sua chave API
A chave API é a chave de autenticação única para a API de validação de números de telefone Cleariflow. Note que cada API Cleariflow tem uma chave API única, pelo que precisará de chaves diferentes para aceder à validação telefónica e à validação de e-mail, por exemplo. Para autenticar os seus pedidos, adicione a chave API ao URL base.URL base
O que significa valid
Números fictícios 555 dos EUA e outros intervalos estruturalmente válidos mas não atribuídos podem continuar a devolver
valid: true. carrier e location são preenchidos principalmente a partir de metadados US/CA e muitas vezes estão vazios noutras regiões.
Endpoint de validação
A API exige a sua chave API única e o número de telefone a verificar:phone=14155552671, country=US):
phone=123, country=US):
Parâmetros de pedido
String
obrigatório
A sua chave API única. Note que cada utilizador tem chaves API únicas para cada uma das APIs Cleariflow, pelo que a chave Phone Validation não funcionará para a API de geolocalização IP, por exemplo.
String
obrigatório
O número de telefone a validar.
String
Indicação opcional ISO 3166-1 alpha-2 para números em formato nacional sem
+ inicial. Por exemplo, country=US ajuda a analisar 4155552671. Números com prefixo internacional são analisados a partir do respetivo código de país; o country.code detetado na resposta pode diferir desta indicação (p. ex. GG para alguns intervalos móveis +44).Parâmetros de resposta
A resposta da API é devolvida num formato JSON universal e leve.String
Dígitos E.164 normalizados (sem
+) quando valid é true. Quando valid é false, apenas os dígitos da sua entrada.Boolean
true quando o número é estruturalmente válido. Isto não é verificação de estado da linha ou do assinante.Boolean
Verificação de comprimento permissiva ().
true quando os dígitos e o comprimento podem pertencer a um número real, mesmo com valid false.String
Presente quando
valid é false. Um de: not_a_number, possible, possible_local_only, invalid_country_code, too_short, invalid_length, too_long, unknown. Omitido quando valid é true.Object
Formatos
international e local. Cadeias vazias quando valid é false.String
Formato E.164 com
+ inicial. Vazio quando valid é false.String
Formato nacional para a região detetada. Vazio quando
valid é false.Object
País/território detetado. Campos vazios quando
valid é false.String
Código de duas letras ISO 3166-1 alpha-2 para a região detetada.
String
Nome de apresentação em inglês para
country.code.String
Prefixo de chamada internacional (p. ex.
+1).String
Indicação de geocodificação (região, estado/província ou cidade). Muitas vezes vazio fora de US/CA. Vazio quando
valid é false.String
Tipo de linha quando
valid é true: Landline, Mobile, Landline_or_Mobile, Toll_Free, Premium, Paging, Special ou Unknown. Sempre Unknown quando valid é false.String
Nome da operadora quando disponível (mais frequentemente US/CA). Cadeia vazia caso contrário, incluindo quando
valid é false.String
Nome seguro da operadora para exibição ao utilizador (número válido e região sem portabilidade móvel). Vazio se
valid é false ou a operadora não pode ser mostrada com segurança.Array
Identificadores de fuso horário IANA (ex.
America/New_York). Array vazio se valid é true sem mapeamento; null se valid é false.Boolean
Indica se o número está associado a uma região geográfica. Sempre
false quando valid é false.Boolean
Indica se o número pode ser marcado de fora da região de origem. Sempre
false quando valid é false.Carregamento em massa (CSV)
Boas práticas ao carregar em massa um ficheiro CSV:- Certifique-se de que a primeira coluna contém os números de telefone a analisar.
- Remova as linhas vazias do ficheiro.
- Inclua apenas um número de telefone por linha.
- O tamanho máximo permitido do ficheiro é de 50.000 linhas.
Códigos de resposta e erro
Sempre que um pedido falha por algum motivo, também é devolvido um erro em formato JSON. Os erros incluem um código e uma descrição, detalhados abaixo.Outras notas
Nota sobre faturação por utilização: cada número de telefone individual que submeter conta como um crédito utilizado. Os créditos também são contados por pedido, não por resposta bem-sucedida. Portanto, se submeter um pedido para o número (inválido) «kasj8929hs», isso ainda conta como 1 crédito.API de validação de telefones