> For the complete documentation index, see [llms.txt](https://docs.geeknums.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.geeknums.io/dhl-checknumber-api-comprobacion-masiva.md).

# DHL CheckNumber API: Comprobación masiva

DHL CheckNumber: Procese los valores de entrada mediante la API por lotes y obtenga los campos de resultado que se indican a continuación.

## Formato de entrada

Cargue un archivo de texto con un número de teléfono por línea. Normalice los valores antes de cargarlo; se recomienda el formato E.164 para teléfonos.

```
+14155552671+442071838750
```

{% stepper %}
{% step %}

## Crear una tarea

`POST https://api.checknumber.ai/v1/tasks`

*Ventana de terminal*

```bash
curl --location 'https://api.checknumber.ai/v1/tasks' \--header 'X-API-Key: YOUR_API_KEY' \--form 'file=@"./input.txt"' \--form 'task_type="dhl"'
```

La API devuelve un ID de tarea. Guárdelo y úselo para consultar el estado.
{% endstep %}

{% step %}

## Comprobar el estado de la tarea

`POST https://api.checknumber.ai/v1/gettasks`

*Ventana de terminal*

```bash
curl --location 'https://api.checknumber.ai/v1/gettasks' \--header 'X-API-Key: YOUR_API_KEY' \--form 'task_id="d4g8o46p2jvh04o9uolg"'
```

Consulte hasta que `status` sea `exported`. No considere `pending` ni `processing` como resultados completos.
{% endstep %}
{% endstepper %}

## Respuesta de carga

```json
{  "task_id": "d4g8o46p2jvh04o9uolg",  "status": "pending",  "total": 5000,  "estimated_amount": {    "amount": "0.500000",    "currency": "USD"  },  "message": "Task created successfully"}
```

## Respuesta en proceso

```json
{  "task_id": "d4g8o46p2jvh04o9uolg",  "status": "processing",  "total": 5000,  "success": 2500,  "failure": 0}
```

## Respuesta exportada

```json
{  "task_id": "d4g8o46p2jvh04o9uolg",  "status": "exported",  "total": 5000,  "success": 5000,  "failure": 0,  "result_url": "https://example-link-to-results.zip",  "actual_amount": {    "amount": "2.000000",    "currency": "USD"  }}
```

## Campos del resultado

| Campo       | Descripción                                               | Ejemplo      |
| ----------- | --------------------------------------------------------- | ------------ |
| `number`    | Número de teléfono de la entrada enviada.                 | +14155552671 |
| `activated` | Indica si la entrada se detectó como activa o registrada. | yes          |

## Procesamiento del archivo de resultados

Descargue el archivo desde `result_url` solo después de exportar la tarea. Conserve los nombres de columna devueltos al procesar el archivo.

## Campos de respuesta

| Campo              | Descripción                                     |
| ------------------ | ----------------------------------------------- |
| `created_at`       | Marca de tiempo de creación de la tarea.        |
| `updated_at`       | Marca de tiempo de la última actualización.     |
| `task_id`          | Identificador único de la tarea.                |
| `status`           | `pending`, `processing`, `exported` o `failed`. |
| `total`            | Total de valores de entrada procesados.         |
| `success`          | Valores procesados correctamente.               |
| `failure`          | Valores cuyo procesamiento falló.               |
| `result_url`       | URL de descarga cuando la tarea se exporta.     |
| `actual_amount`    | Importe final liquidado, si está disponible.    |
| `estimated_amount` | Importe estimado devuelto al crear la tarea.    |

## Códigos de estado

| Status | Descripción                                                                  |
| ------ | ---------------------------------------------------------------------------- |
| `200`  | Solicitud correcta.                                                          |
| `202`  | Tarea creada correctamente y cargo estimado aplicado.                        |
| `400`  | Archivo no válido, tipo de tarea no compatible o muy pocas entradas válidas. |
| `401`  | Falta la clave API o no es válida.                                           |
| `402`  | Saldo insuficiente.                                                          |
| `404`  | Tarea no encontrada.                                                         |
| `413`  | El archivo cargado es demasiado grande.                                      |
| `500`  | Error interno del servidor; inténtelo más tarde.                             |

## Notas operativas

* La tarea es asíncrona; use el ID para consultar su estado.
* Compruebe los límites de entrada del producto antes de cargar el archivo.
* Las filas fallidas aparecen en el resultado exportado y se reflejan en los contadores.
* Los campos anteriores se basan en el sample actual y pueden cambiar si cambia el esquema de exportación.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.geeknums.io/dhl-checknumber-api-comprobacion-masiva.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.