API de validação de telefones

GET

curl --request GET \
  --url https://phonevalidation.cleariflow.com/v1

{
  "phone": "14155552671",
  "valid": true,
  "format": {
    "international": "+14155552671",
    "local": "(415) 555-2671"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1"
  },
  "location": "San Francisco, CA",
  "type": "Landline_or_Mobile",
  "carrier": ""
}

É muito simples de usar: envie a sua chave API e um número de telefone. A API devolve se o número é estruturalmente válido (segundo o Google libphonenumber) e, quando válido, formatos E.164 normalizados mais metadados opcionais como tipo de linha, indicações de geocodificação e dados da operadora quando disponíveis.

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 HLR/SMS 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

https://phonevalidation.cleariflow.com/v1/

O que significa `valid`

`valid`	Significado
`true`	O número é estruturalmente válido para a região detetada (libphonenumber `IsValidNumber`).
`false`	O número não pôde ser analisado ou não cumpre as regras de formato regional. `format`, `country`, `location`, `type` e `carrier` estão sempre vazios; `phone` contém apenas os dígitos da sua entrada.

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:

https://phonevalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& phone = 14155552671
& country = US

Resposta válida (phone=14155552671, country=US):

{
  "phone": "14155552671",
  "valid": true,
  "format": {
    "international": "+14155552671",
    "local": "(415) 555-2671"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1"
  },
  "location": "San Francisco, CA",
  "type": "Landline_or_Mobile",
  "carrier": ""
}

Resposta inválida (phone=123, country=US):

{
  "phone": "123",
  "valid": false,
  "format": {
    "international": "",
    "local": ""
  },
  "country": {
    "code": "",
    "name": "",
    "prefix": ""
  },
  "location": "",
  "type": "Unknown",
  "carrier": ""
}

Parâmetros de pedido

api_key

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.

phone

String

obrigatório

O número de telefone a validar (verificação estrutural segundo libphonenumber).

country

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.

phone

String

Dígitos E.164 normalizados (sem +) quando valid é true. Quando valid é false, apenas os dígitos da sua entrada.

valid

Boolean

true quando o número é estruturalmente válido segundo libphonenumber. Isto não é verificação de estado da linha ou do assinante.

format

Object

Formatos international e local. Cadeias vazias quando valid é false.

format.international

String

Formato E.164 com + inicial. Vazio quando valid é false.

format.local

String

Formato nacional para a região detetada. Vazio quando valid é false.

country

Object

País/território detetado. Campos vazios quando valid é false.

country.code

String

Código de duas letras ISO 3166-1 alpha-2 para a região detetada.

country.name

String

Nome de apresentação em inglês para country.code.

country.prefix

String

Prefixo de chamada internacional (p. ex. +1).

location

String

Indicação de geocodificação dos metadados libphonenumber (região, estado/província ou cidade). Muitas vezes vazio fora de US/CA. Vazio quando valid é false.

type

String

Tipo de linha quando valid é true: Landline, Mobile, Landline_or_Mobile, Toll_Free, Premium, Paging, Special ou Unknown. Sempre Unknown quando valid é false.

carrier

String

Nome da operadora dos metadados libphonenumber quando disponível (mais frequentemente US/CA). Cadeia vazia caso contrário, incluindo 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.

Code	Type	Details
200	OK	Tudo funcionou como esperado.
400	Bad request	Pedido incorreto.
401	Unauthorized	O pedido não foi aceite. Normalmente devido a chave API em falta ou incorreta.
422	Quota reached	O pedido foi interrompido por créditos API insuficientes. (Planos gratuitos)
429	Too many requests	O pedido foi interrompido por atingir o limite de pedidos por segundo. Nos planos gratuitos os pedidos estão limitados a 1 por segundo.
500	Internal server error	O pedido não pôde ser concluído devido a um erro no servidor.
503	Service unavailable	O servidor não estava disponível.

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.

IntroduçãoA API de validação de IVA da Cleariflow oferece soluções abrangentes de conformidade fiscal através de uma interface RESTful JSON moderna — para validação e cálculo fluidos em negócios nacionais e internacionais.

API de validação de telefones

curl --request GET \
  --url https://phonevalidation.cleariflow.com/v1

{
  "phone": "14155552671",
  "valid": true,
  "format": {
    "international": "+14155552671",
    "local": "(415) 555-2671"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1"
  },
  "location": "San Francisco, CA",
  "type": "Landline_or_Mobile",
  "carrier": ""
}

​Primeiros passos

​REST

​HTTPS

​Versões da API

​A sua chave API

​URL base

​O que significa valid

​Endpoint de validação

​Parâmetros de pedido

​Parâmetros de resposta

​Carregamento em massa (CSV)

​Códigos de resposta e erro

​Outras notas

Primeiros passos

REST

HTTPS

Versões da API

A sua chave API

URL base

O que significa `valid`

Endpoint de validação

Parâmetros de pedido

Parâmetros de resposta

Carregamento em massa (CSV)

Códigos de resposta e erro

Outras notas