> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

É 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.

<Note>
  `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.
</Note>

## 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.                                                                                                                                                                                                                                                                                                                       |
| `false` | O número não pôde ser analisado ou não cumpre as regras de formato regionais. `format`, `country`, `location`, `type`, `carrier`, `carrier_display`, `timezones`, `geographical` e `internationally_dialable` estão sempre vazios ou false; `possible` e `invalid_reason` são preenchidos quando a entrada pôde ser analisada. `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`):

<ResponseExample>
  ```json theme={"system"}
  {
    "phone": "14155552671",
    "valid": true,
    "possible": 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": "",
    "carrier_display": "",
    "timezones": ["America/Los_Angeles"],
    "geographical": true,
    "internationally_dialable": true
  }
  ```
</ResponseExample>

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

```json theme={"system"}
{
  "phone": "123",
  "valid": false,
  "possible": false,
  "invalid_reason": "too_short",
  "format": {
    "international": "",
    "local": ""
  },
  "country": {
    "code": "",
    "name": "",
    "prefix": ""
  },
  "location": "",
  "type": "Unknown",
  "carrier": "",
  "carrier_display": "",
  "timezones": null,
  "geographical": false,
  "internationally_dialable": false
}
```

### Parâmetros de pedido

<ParamField query="api_key" type="String" required>
  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.
</ParamField>

<ParamField query="phone" type="String" required>
  O número de telefone a validar.
</ParamField>

<ParamField query="country" type="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`).
</ParamField>

### Parâmetros de resposta

A resposta da API é devolvida num formato [JSON](https://www.json.org/json-en.html) universal e leve.

<ResponseField name="phone" type="String">
  Dígitos E.164 normalizados (sem `+`) quando `valid` é true. Quando `valid` é false, apenas os dígitos da sua entrada.
</ResponseField>

<ResponseField name="valid" type="Boolean">
  `true` quando o número é estruturalmente válido. Isto **não** é verificação de estado da linha ou do assinante.
</ResponseField>

<ResponseField name="possible" type="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.
</ResponseField>

<ResponseField name="invalid_reason" type="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.
</ResponseField>

<ResponseField name="format" type="Object">
  Formatos `international` e `local`. Cadeias vazias quando `valid` é false.
</ResponseField>

<ResponseField name="format.international" type="String">
  Formato E.164 com `+` inicial. Vazio quando `valid` é false.
</ResponseField>

<ResponseField name="format.local" type="String">
  Formato nacional para a região detetada. Vazio quando `valid` é false.
</ResponseField>

<ResponseField name="country" type="Object">
  País/território detetado. Campos vazios quando `valid` é false.
</ResponseField>

<ResponseField name="country.code" type="String">
  Código de duas letras [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) para a região detetada.
</ResponseField>

<ResponseField name="country.name" type="String">
  Nome de apresentação em inglês para `country.code`.
</ResponseField>

<ResponseField name="country.prefix" type="String">
  [Prefixo de chamada internacional](https://en.wikipedia.org/wiki/List_of_country_calling_codes) (p. ex. `+1`).
</ResponseField>

<ResponseField name="location" type="String">
  Indicação de geocodificação (região, estado/província ou cidade). Muitas vezes vazio fora de US/CA. Vazio quando `valid` é false.
</ResponseField>

<ResponseField name="type" 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.
</ResponseField>

<ResponseField name="carrier" type="String">
  Nome da operadora quando disponível (mais frequentemente US/CA). Cadeia vazia caso contrário, incluindo quando `valid` é false.
</ResponseField>

<ResponseField name="carrier_display" type="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.
</ResponseField>

<ResponseField name="timezones" type="Array">
  Identificadores de fuso horário IANA (ex. `America/New_York`). Array vazio se `valid` é true sem mapeamento; `null` se `valid` é false.
</ResponseField>

<ResponseField name="geographical" type="Boolean">
  Indica se o número está associado a uma região geográfica. Sempre `false` quando `valid` é false.
</ResponseField>

<ResponseField name="internationally_dialable" type="Boolean">
  Indica se o número pode ser marcado de fora da região de origem. Sempre `false` quando `valid` é false.
</ResponseField>

## 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.