> ## 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 validación de teléfono

> API REST JSON rápida de Cleariflow para validación estructural de teléfonos, normalización E.164 y datos opcionales de operador, ubicación, zona horaria y marcación.

Es muy sencillo: envíe su clave API y un número de teléfono. La API indica si el número es **estructuralmente válido** y, si es válido, devuelve formatos E.164 normalizados y metadatos opcionales como tipo de línea, geocodificación, operador, zonas horarias y datos de marcación cuando estén disponibles.

<Note>
  `valid: true` significa que el número cumple las reglas de formato regional (longitud, prefijo, sintaxis). **No** confirma que la línea esté activa, asignada a un abonado o sea alcanzable. Para el estado de línea en tiempo real necesita carrier lookup, que queda fuera del alcance de esta API.
</Note>

## Primeros pasos

### REST

La API de validación de números de teléfono, como todas las API de Cleariflow, está organizada en torno a REST. Está diseñada para usar URL predecibles orientadas a recursos y códigos de estado HTTP para indicar errores.

### HTTPS

La API de validación de números de teléfono requiere que todas las comunicaciones estén protegidas con TLS 1.2 o superior.

### Versiones de la API

Todas las API de Cleariflow están versionadas. La API de validación de números de teléfono está actualmente en la versión 1.

### Su clave API

Su clave API es su clave de autenticación única para la API de validación de números de teléfono de Cleariflow. Tenga en cuenta que cada API de Cleariflow tiene una clave API única, por lo que necesitará claves diferentes para acceder a la validación de teléfono y la validación de correo electrónico, por ejemplo. Para autenticar sus solicitudes, añada su clave API a la URL base.

### URL base

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

### Qué significa `valid`

| `valid` | Significado                                                                                                                                                                                                                                                                                                                                                                |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `true`  | El número es estructuralmente válido para su región detectada.                                                                                                                                                                                                                                                                                                             |
| `false` | El número no pudo analizarse o no cumple las reglas de formato regionales. `format`, `country`, `location`, `type`, `carrier`, `carrier_display`, `timezones`, `geographical` e `internationally_dialable` siempre están vacíos o en false; `possible` e `invalid_reason` se rellenan cuando se pudo analizar la entrada. `phone` contiene solo los dígitos de su entrada. |

Los números ficticios 555 de EE. UU. y otros rangos estructuralmente válidos pero no asignados pueden seguir devolviendo `valid: true`. `carrier` y `location` se rellenan principalmente con metadatos de US/CA y a menudo están vacíos en otras regiones.

### Endpoint de validación

La API requiere su clave API única y el número de teléfono a comprobar:

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

**Respuesta 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>

**Respuesta no vá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 solicitud

<ParamField query="api_key" type="String" required>
  Su clave API única. Tenga en cuenta que cada usuario tiene claves API únicas *para cada una de las API de Cleariflow*, por lo que su clave de Phone Validation no funcionará para su API de geolocalización IP, por ejemplo.
</ParamField>

<ParamField query="phone" type="String" required>
  El número de teléfono a validar.
</ParamField>

<ParamField query="country" type="String">
  Indicación opcional ISO 3166-1 alpha-2 para números en formato nacional sin `+` inicial. Por ejemplo, `country=US` ayuda a analizar `4155552671`. Los números con prefijo internacional se analizan según su código de país; el `country.code` detectado en la respuesta puede diferir de esta indicación (p. ej. `GG` para algunos rangos móviles `+44`).
</ParamField>

### Parámetros de respuesta

La respuesta de la API se devuelve en un formato [JSON](https://www.json.org/json-en.html) universal y ligero.

<ResponseField name="phone" type="String">
  Dígitos E.164 normalizados (sin `+`) cuando `valid` es true. Cuando `valid` es false, solo los dígitos de su entrada.
</ResponseField>

<ResponseField name="valid" type="Boolean">
  `true` cuando el número es estructuralmente válido. Esto **no** es verificación de estado de línea ni de abonado.
</ResponseField>

<ResponseField name="possible" type="Boolean">
  Comprobación de longitud permisiva (). `true` cuando los dígitos y la longitud podrían corresponder a un número real, incluso si `valid` es false.
</ResponseField>

<ResponseField name="invalid_reason" type="String">
  Presente cuando `valid` es false. Uno de: `not_a_number`, `possible`, `possible_local_only`, `invalid_country_code`, `too_short`, `invalid_length`, `too_long`, `unknown`. Omitido cuando `valid` es true.
</ResponseField>

<ResponseField name="format" type="Object">
  Formatos `international` y `local`. Cadenas vacías cuando `valid` es false.
</ResponseField>

<ResponseField name="format.international" type="String">
  Formato E.164 con `+` inicial. Vacío cuando `valid` es false.
</ResponseField>

<ResponseField name="format.local" type="String">
  Formato nacional para la región detectada. Vacío cuando `valid` es false.
</ResponseField>

<ResponseField name="country" type="Object">
  País/territorio detectado. Campos vacíos cuando `valid` es false.
</ResponseField>

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

<ResponseField name="country.name" type="String">
  Nombre para mostrar en inglés de `country.code`.
</ResponseField>

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

<ResponseField name="location" type="String">
  Indicación de geocodificación (región, estado/provincia o ciudad). A menudo vacío fuera de US/CA. Vacío cuando `valid` es false.
</ResponseField>

<ResponseField name="type" type="String">
  Tipo de línea cuando `valid` es true: `Landline`, `Mobile`, `Landline_or_Mobile`, `Toll_Free`, `Premium`, `Paging`, `Special` o `Unknown`. Siempre `Unknown` cuando `valid` es false.
</ResponseField>

<ResponseField name="carrier" type="String">
  Nombre del operador cuando esté disponible (más a menudo US/CA). Cadena vacía en caso contrario, incluido cuando `valid` es false.
</ResponseField>

<ResponseField name="carrier_display" type="String">
  Nombre seguro del operador para mostrar al usuario (cuando es válido y la región no usa portabilidad móvil). Vacío si `valid` es false o el operador no puede mostrarse de forma segura.
</ResponseField>

<ResponseField name="timezones" type="Array">
  Identificadores de zona horaria IANA (p. ej. `America/New_York`). Array vacío si `valid` es true sin mapeo; `null` si `valid` es false.
</ResponseField>

<ResponseField name="geographical" type="Boolean">
  Si el número está asociado a una región geográfica. Siempre `false` cuando `valid` es false.
</ResponseField>

<ResponseField name="internationally_dialable" type="Boolean">
  Si el número puede marcarse desde fuera de su región de origen. Siempre `false` cuando `valid` es false.
</ResponseField>

## Carga masiva (CSV)

Buenas prácticas al cargar masivamente un archivo CSV:

* Asegúrese de que la primera columna contenga los números de teléfono a analizar.
* Elimine las filas vacías del archivo.
* Incluya solo un número de teléfono por fila.
* El tamaño máximo permitido del archivo es de 50.000 filas.

## Códigos de respuesta y error

Siempre que realice una solicitud que falle por algún motivo, también se devuelve un error en formato JSON. Los errores incluyen un código y una descripción, que puede consultar en detalle a continuación.

| Code | Type                  | Details                                                                                                                                             |
| ---- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200  | OK                    | Todo funcionó como se esperaba.                                                                                                                     |
| 400  | Bad request           | Solicitud incorrecta.                                                                                                                               |
| 401  | Unauthorized          | La solicitud no fue aceptable. Normalmente por clave API ausente o incorrecta.                                                                      |
| 422  | Quota reached         | La solicitud se interrumpió por créditos API insuficientes. (Planes gratuitos)                                                                      |
| 429  | Too many requests     | La solicitud se interrumpió por alcanzar el límite de solicitudes por segundo. En planes gratuitos las solicitudes están limitadas a 1 por segundo. |
| 500  | Internal server error | La solicitud no pudo completarse por un error en el servidor.                                                                                       |
| 503  | Service unavailable   | El servidor no estaba disponible.                                                                                                                   |

## Otras notas

Nota sobre facturación por uso: cada número de teléfono individual que envíe cuenta como un crédito utilizado. Los créditos también se cuentan por solicitud, no por respuesta exitosa. Por lo tanto, si envía una solicitud con el número (no válido) «kasj8929hs», eso sigue contando como 1 crédito.