> ## 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 di validazione numeri di telefono

> API REST JSON veloce Cleariflow per validazione strutturale dei numeri, normalizzazione E.164 e dettagli opzionali su operatore, posizione, fuso orario e composizione.

L'uso è molto semplice: inviate la chiave API e un numero di telefono. L'API restituisce se il numero è **strutturalmente valido** e, se valido, formati E.164 normalizzati e metadati opzionali come tipo di linea, geocodifica, operatore, fusi orari e indicazioni di composizione quando disponibili.

<Note>
  `valid: true` significa che il numero rispetta le regole di formato regionale (lunghezza, prefisso, sintassi). **Non** conferma che la linea sia attiva, assegnata a un abbonato o raggiungibile. Per lo stato della linea in tempo reale serve carrier lookup, che esula da questa API.
</Note>

## Per iniziare

### REST

L'API di validazione dei numeri di telefono, come tutte le API Cleariflow, è organizzata attorno a REST. È progettata per usare URL prevedibili orientati alle risorse e codici di stato HTTP per indicare gli errori.

### HTTPS

L'API di validazione dei numeri di telefono richiede che tutte le comunicazioni siano protette con TLS 1.2 o superiore.

### Versioni API

Tutte le API Cleariflow sono versionate. L'API di validazione dei numeri di telefono è attualmente alla versione 1.

### La vostra chiave API

La chiave API è la chiave di autenticazione univoca per l'API di validazione dei numeri di telefono Cleariflow. Ogni API Cleariflow ha una chiave API univoca, quindi serviranno chiavi diverse per accedere alla validazione telefonica e alla validazione e-mail, ad esempio. Per autenticare le richieste, aggiungete la chiave API all'URL di base.

### URL di base

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

### Cosa significa `valid`

| `valid` | Significato                                                                                                                                                                                                                                                                                                                                                                       |
| ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `true`  | Il numero è strutturalmente valido per la regione rilevata.                                                                                                                                                                                                                                                                                                                       |
| `false` | Il numero non è stato analizzato o non rispetta le regole di formato regionali. `format`, `country`, `location`, `type`, `carrier`, `carrier_display`, `timezones`, `geographical` e `internationally_dialable` sono sempre vuoti o false; `possible` e `invalid_reason` vengono compilati quando l'input ha potuto essere analizzato. `phone` contiene solo le cifre dell'input. |

I numeri fittizi 555 statunitensi e altri intervalli strutturalmente validi ma non assegnati possono comunque restituire `valid: true`. `carrier` e `location` sono popolati principalmente dai metadati US/CA e spesso sono vuoti altrove.

### Endpoint di validazione

L'API richiede la chiave API univoca e il numero di telefono da verificare:

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

**Risposta valida** (`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>

**Risposta non valida** (`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
}
```

### Parametri di richiesta

<ParamField query="api_key" type="String" required>
  La vostra chiave API univoca. Ogni utente ha chiavi API univoche *per ciascuna delle API Cleariflow*, quindi la chiave Phone Validation non funzionerà per l'API di geolocalizzazione IP, ad esempio.
</ParamField>

<ParamField query="phone" type="String" required>
  Il numero di telefono da validare.
</ParamField>

<ParamField query="country" type="String">
  Suggerimento opzionale ISO 3166-1 alpha-2 per numeri in formato nazionale senza `+` iniziale. Ad esempio, `country=US` aiuta ad analizzare `4155552671`. I numeri con prefisso internazionale vengono analizzati dal codice paese; il `country.code` rilevato nella risposta può differire da questo suggerimento (es. `GG` per alcuni intervalli mobili `+44`).
</ParamField>

### Parametri di risposta

La risposta dell'API viene restituita in un formato [JSON](https://www.json.org/json-en.html) universale e leggero.

<ResponseField name="phone" type="String">
  Cifre E.164 normalizzate (senza `+`) quando `valid` è true. Quando `valid` è false, solo le cifre del vostro input.
</ResponseField>

<ResponseField name="valid" type="Boolean">
  `true` quando il numero è strutturalmente valido. Questo **non** è verifica dello stato della linea o dell'abbonato.
</ResponseField>

<ResponseField name="possible" type="Boolean">
  Controllo di lunghezza permissivo (). `true` quando cifre e lunghezza potrebbero appartenere a un numero reale, anche se `valid` è false.
</ResponseField>

<ResponseField name="invalid_reason" type="String">
  Presente quando `valid` è false. Uno tra: `not_a_number`, `possible`, `possible_local_only`, `invalid_country_code`, `too_short`, `invalid_length`, `too_long`, `unknown`. Omesso quando `valid` è true.
</ResponseField>

<ResponseField name="format" type="Object">
  Formati `international` e `local`. Stringhe vuote quando `valid` è false.
</ResponseField>

<ResponseField name="format.international" type="String">
  Formato E.164 con `+` iniziale. Vuoto quando `valid` è false.
</ResponseField>

<ResponseField name="format.local" type="String">
  Formato nazionale per la regione rilevata. Vuoto quando `valid` è false.
</ResponseField>

<ResponseField name="country" type="Object">
  Paese/territorio rilevato. Campi vuoti quando `valid` è false.
</ResponseField>

<ResponseField name="country.code" type="String">
  Codice a due lettere [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) per la regione rilevata.
</ResponseField>

<ResponseField name="country.name" type="String">
  Nome visualizzato in inglese per `country.code`.
</ResponseField>

<ResponseField name="country.prefix" type="String">
  [Prefisso telefonico internazionale](https://en.wikipedia.org/wiki/List_of_country_calling_codes) (es. `+1`).
</ResponseField>

<ResponseField name="location" type="String">
  Indicazione di geocodifica (regione, stato/provincia o città). Spesso vuota al di fuori di US/CA. Vuota quando `valid` è false.
</ResponseField>

<ResponseField name="type" type="String">
  Tipo di linea quando `valid` è true: `Landline`, `Mobile`, `Landline_or_Mobile`, `Toll_Free`, `Premium`, `Paging`, `Special` o `Unknown`. Sempre `Unknown` quando `valid` è false.
</ResponseField>

<ResponseField name="carrier" type="String">
  Nome dell'operatore quando disponibile (più spesso US/CA). Stringa vuota altrimenti, incluso quando `valid` è false.
</ResponseField>

<ResponseField name="carrier_display" type="String">
  Nome operatore sicuro per la visualizzazione utente (numero valido e regione senza portabilità mobile). Vuoto se `valid` è false o l'operatore non può essere mostrato in modo sicuro.
</ResponseField>

<ResponseField name="timezones" type="Array">
  Identificatori di fuso orario IANA (es. `America/New_York`). Array vuoto se `valid` è true senza mapping; `null` se `valid` è false.
</ResponseField>

<ResponseField name="geographical" type="Boolean">
  Indica se il numero è associato a una regione geografica. Sempre `false` quando `valid` è false.
</ResponseField>

<ResponseField name="internationally_dialable" type="Boolean">
  Indica se il numero può essere chiamato dall'esterno della regione di origine. Sempre `false` quando `valid` è false.
</ResponseField>

## Caricamento massivo (CSV)

Buone pratiche per il caricamento massivo di un file CSV:

* Assicuratevi che la prima colonna contenga i numeri di telefono da analizzare.
* Rimuovete le righe vuote dal file.
* Includete un solo numero di telefono per riga.
* La dimensione massima consentita del file è di 50.000 righe.

## Codici di risposta ed errore

Quando una richiesta fallisce per qualche motivo, viene restituito anche un errore in formato JSON. Gli errori includono un codice e una descrizione, dettagliati di seguito.

| Code | Type                  | Details                                                                                                                                             |
| ---- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200  | OK                    | Tutto ha funzionato come previsto.                                                                                                                  |
| 400  | Bad request           | Richiesta non valida.                                                                                                                               |
| 401  | Unauthorized          | La richiesta non era accettabile. Di solito per chiave API mancante o errata.                                                                       |
| 422  | Quota reached         | La richiesta è stata interrotta per crediti API insufficienti. (Piani gratuiti)                                                                     |
| 429  | Too many requests     | La richiesta è stata interrotta per aver raggiunto il limite di richieste al secondo. Nei piani gratuiti le richieste sono limitate a 1 al secondo. |
| 500  | Internal server error | La richiesta non è stata completata a causa di un errore lato server.                                                                               |
| 503  | Service unavailable   | Il server non era disponibile.                                                                                                                      |

## Altre note

Nota sulla fatturazione a consumo: ogni singolo numero di telefono inviato conta come un credito utilizzato. I crediti vengono conteggiati per richiesta, non per risposta riuscita. Quindi, se inviate una richiesta per il numero (non valido) «kasj8929hs», conta comunque come 1 credito.