# Exportación asíncrona de estadísticas de mensajes

`exportMessagesStatistics` exporta el historial de mensajes y las estadísticas a un archivo CSV en el servidor. Úsalo para extracciones grandes o de cuentas completas que [`messages:list`](/es/developer/api-reference/statistics-api/message-statistics-api/#messageslist) no puede manejar.

## Cuándo usar la exportación en lugar de messages:list

Usa `messages:list` para búsquedas en vivo y paginadas de un período delimitado. Usa `exportMessagesStatistics` cuando el resultado excedería el límite de paginación profunda de `messages:list` (`page × per_page > 100000`), o cuando el objetivo es un único archivo descargable en lugar de un JSON paginado. La exportación no tiene límite en `date_range` o en el número de filas, porque transmite el resultado a un archivo en el disco en lugar de mantenerlo en una sola respuesta.

## Cómo funciona el flujo de exportación

1.  Llama a [`export`](#export) con los mismos filtros que `messages:list`. La respuesta devuelve un identificador de tarea `uid` inmediatamente, antes de que se genere el archivo.
2.  Sondea [`status`](#status) con ese `uid` hasta que informe `STATUS_SUCCESS` (o `STATUS_FAILED`).
3.  Llama a [`result`](#result) con el mismo `uid` para obtener el nombre del archivo generado.
4.  [Descarga](#download) el archivo por su nombre.

Usa [`lastTasks`](#lasttasks) para buscar tareas de exportación recientes para una aplicación, y [`delete`](#delete) para cancelar una tarea o eliminar su archivo antes de tiempo.

## Métodos

El ciclo de vida de la exportación tiene cinco métodos, más un punto final de descarga simple:

| Método | Descripción |
|---|---|
| [`exportMessagesStatistics/export`](#export) | Pone en cola una exportación y devuelve un `uid` de tarea. |
| [`exportMessagesStatistics/status`](#status) | Comprueba el progreso de la tarea. |
| [`exportMessagesStatistics/result`](#result) | Devuelve el nombre del archivo generado una vez que la tarea ha finalizado. |
| [`exportMessagesStatistics/lastTasks`](#lasttasks) | Enumera las tareas de exportación recientes para una aplicación. |
| [`exportMessagesStatistics/delete`](#delete) | Cancela una tarea o elimina su archivo antes de que expire el período de retención. |
| [Descarga](#download) | Descarga el archivo CSV generado por su nombre. |

### export

Pone en cola una exportación del historial de mensajes y devuelve un identificador de tarea de inmediato.

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/export`

##### Cabeceras

La solicitud necesita un token de la API del servidor:

| Nombre | Requerido | Descripción |
|---|---|---|
| `Authorization` | Sí | [Token de la API del servidor](/es/developer/api-reference/api-access-token/#server-api-token). Debe proporcionarse en el siguiente formato: `Authorization: Api <Server Key>`. |

##### Parámetros del cuerpo de la solicitud

El cuerpo de la solicitud acepta los siguientes campos:

| Nombre | Requerido | Tipo | Descripción |
|---|---|---|---|
| `type` | Sí | String | Debe ser <code>"TASK_TYPE_EXPORT<wbr/>_MESSAGES_V2"</code>. |
| <code>export_messages<wbr/>_v2</code> | Sí | Object | Parámetros de exportación, descritos a continuación. |
| <code>export_messages<wbr/>_v2.application<wbr/>_code</code> | Ver nota | String | [Código de aplicación de Pushwoosh](/es/developer/api-reference/api-identifiers/#application-code). Requerido si `app_group_code` no está establecido. |
| <code>export_messages<wbr/>_v2.app<wbr/>_group_code</code> | Ver nota | String | Código de grupo de aplicaciones, exporta a través de cada aplicación en el grupo. Requerido si `application_code` no está establecido. |
| <code>export_messages<wbr/>_v2.search</code> | No | String | Búsqueda de texto libre en el título y contenido del mensaje. |
| <code>export_messages<wbr/>_v2.filters</code> | No | Object | Filtros de mensajes, descritos a continuación. Omita para exportar todo el historial de la cuenta. |
| <code>export_messages<wbr/>_v2.properties</code> | No | Array | Columnas a incluir en el CSV, descritas a continuación. |

`export_messages_v2.filters` acepta:

| Nombre <div style="width:150px"></div> | Tipo | Descripción |
|---|---|---|
| `statuses` | Array | Estados de los mensajes a incluir. <details><summary>Valores posibles</summary><ul><li><code>"MESSAGE_STATUS_CANCELED"</code></li><li><code>"MESSAGE_STATUS_CREATING"</code></li><li><code>"MESSAGE_STATUS_DONE"</code></li><li><code>"MESSAGE_STATUS_FAIL"</code></li><li><code>"MESSAGE_STATUS_PENDING"</code></li><li><code>"MESSAGE_STATUS_PROCESSING"</code></li><li><code>"MESSAGE_STATUS_WAITING"</code></li></ul></details> |
| `platforms` | Array | [Códigos de plataforma](/es/developer/api-reference/messages-api/api-prerequisites/#platforms) (numéricos, p. ej., `1` para iOS), no las cadenas de nombres de plataforma utilizadas por `messages:list`. |
| `sent_date` | Object | Período de informe filtrado por fecha de envío: `{"date_from": "YYYY-MM-DD", "date_to": "YYYY-MM-DD"}`. |
| `created_date` | Object | Período de informe filtrado por fecha de creación del mensaje, mismo formato que `sent_date`. |
| `created_via` | Array | Origen del mensaje. <details><summary>Valores posibles</summary><ul><li><code>"AB_TEST"</code></li><li><code>"API"</code></li><li><code>"AUTO_PUSH"</code></li><li><code>"CP"</code></li><li><code>"CSV"</code></li><li><code>"CUSTOMER_JOURNEY"</code></li><li><code>"EMAIL_API"</code></li><li><code>"EMAIL_CP"</code></li><li><code>"GEO_ZONE"</code></li><li><code>"PUSH_ON_EVENT"</code></li><li><code>"RSS"</code></li><li><code>"SYSTEM"</code></li></ul></details> |
| `segments` | Array | [Códigos de filtro](/es/developer/api-reference/api-identifiers/#segment--filter-code) a los que se envió el mensaje. |
| `campaigns` | Array | [Códigos de campaña](/es/developer/api-reference/api-identifiers/#campaign-code). A diferencia de `messages:list`, esto toma una lista, no un solo código. |
| `message_id` | String (uint64) | Un único ID de mensaje numérico, entre comillas. A diferencia de `messages:list`, la exportación toma un ID, no un array. |
| `message_code` | String | Un único [código de mensaje](/es/developer/api-reference/api-identifiers/#message-code). |

`export_messages_v2.properties` selecciona qué columnas contiene el CSV.

<details>
<summary>Valores posibles</summary>

- `"EXPORT_MESSAGE_PROPERTY_ID"`
- `"EXPORT_MESSAGE_PROPERTY_TIMESTAMP"`
- `"EXPORT_MESSAGE_PROPERTY_CONTENT"`
- `"EXPORT_MESSAGE_PROPERTY_TITLE"`
- `"EXPORT_MESSAGE_PROPERTY_APPLICATIONS"`
- `"EXPORT_MESSAGE_PROPERTY_STATUS"`
- `"EXPORT_MESSAGE_PROPERTY_PLATFORMS"`
- `"EXPORT_MESSAGE_PROPERTY_SOURCE"`
- `"EXPORT_MESSAGE_PROPERTY_FILTER"`
- `"EXPORT_MESSAGE_PROPERTY_SUBSCRIPTION_SEGMENTS"`
- `"EXPORT_MESSAGE_PROPERTY_SENT"`
- `"EXPORT_MESSAGE_PROPERTY_OPENED"`
- `"EXPORT_MESSAGE_PROPERTY_ERRORS"`
- `"EXPORT_MESSAGE_PROPERTY_RECIPIENTS"`
- `"EXPORT_MESSAGE_PROPERTY_DELIVERED"`
- `"EXPORT_MESSAGE_PROPERTY_TOTAL_DELIVERED"`
- `"EXPORT_MESSAGE_PROPERTY_TOTAL_OPENED"`
- `"EXPORT_MESSAGE_PROPERTY_TOTAL_CLICKS"`
- `"EXPORT_MESSAGE_PROPERTY_CLICKS"`
- `"EXPORT_MESSAGE_PROPERTY_UNSUBSCRIBED"`

</details>

<Aside type="caution" title="properties no es solo un filtro">
Una propiedad que no figure en `properties` no aparecerá en el archivo en absoluto, incluidas las columnas base (ID, fecha de envío, contenido, estado). Dejar `properties` vacío produce un CSV sin columnas. Enumere todas las columnas que la exportación debe contener, no solo las métricas que desea agregar además de un conjunto predeterminado.
</Aside>

##### Solicitud de ejemplo

```json
{
  "type": "TASK_TYPE_EXPORT_MESSAGES_V2",
  "export_messages_v2": {
    "application_code": "XXXXX-XXXXX",
    "filters": {
      "created_date": {
        "date_from": "2026-01-01",
        "date_to": "2026-06-30"
      },
      "statuses": ["MESSAGE_STATUS_DONE"],
      "platforms": [1, 3]
    },
    "properties": [
      "EXPORT_MESSAGE_PROPERTY_ID",
      "EXPORT_MESSAGE_PROPERTY_TIMESTAMP",
      "EXPORT_MESSAGE_PROPERTY_STATUS",
      "EXPORT_MESSAGE_PROPERTY_PLATFORMS",
      "EXPORT_MESSAGE_PROPERTY_SENT",
      "EXPORT_MESSAGE_PROPERTY_OPENED"
    ]
  }
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "uid": "177458"
}
```
</TabItem>
<TabItem label="401: Token de acceso a la API incorrecto">
```json
{
  "error": "account not found"
}
```
</TabItem>
</Tabs>

### status

Devuelve el progreso de una tarea de exportación.

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/status`

##### Parámetros del cuerpo de la solicitud

Pase el identificador de tarea devuelto por `export`:

| Nombre | Requerido | Tipo | Descripción |
|---|---|---|---|
| `uid` | Sí | String (int64) | Identificador de tarea de la respuesta de `export`, p. ej., `"177458"`. |

##### Solicitud de ejemplo

```json
{
  "uid": "177458"
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "status": "STATUS_SUCCESS",
  "progress": 1
}
```
</TabItem>
</Tabs>

`status` es uno de `"STATUS_PENDING"`, `"STATUS_SUCCESS"`, o `"STATUS_FAILED"`. `progress` es una fracción entre `0` y `1`; sondee `status` hasta que alcance `"STATUS_SUCCESS"` antes de llamar a `result`.

### result

Devuelve el nombre del archivo generado una vez que la tarea ha finalizado.

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/result`

##### Parámetros del cuerpo de la solicitud

Pase el mismo identificador de tarea devuelto por `export`:

| Nombre | Requerido | Tipo | Descripción |
|---|---|---|---|
| `uid` | Sí | String (int64) | Identificador de tarea de la respuesta de `export`, p. ej., `"177458"`. |

##### Solicitud de ejemplo

```json
{
  "uid": "177458"
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "export_messages_v2_result": {
    "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
  }
}
```
</TabItem>
</Tabs>

Llamar a `result` antes de que `status` informe `"STATUS_SUCCESS"` devuelve un resultado vacío. Pase el valor de `file` tal cual al [punto final de descarga](#download).

### lastTasks

Enumera las tareas de exportación recientes para una aplicación, de la más reciente a la más antigua.

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/lastTasks`

##### Parámetros del cuerpo de la solicitud

Cada parámetro es un filtro opcional; omítalos todos para listar cada tarea a la que el token tiene acceso:

| Nombre | Requerido | Tipo | Descripción |
|---|---|---|---|
| `application` | No | String | [Código de aplicación de Pushwoosh](/es/developer/api-reference/api-identifiers/#application-code). Omita para listar tareas en todas las aplicaciones a las que el token tiene acceso. |
| `types` | No | Array | Restringir a tipos de tarea específicos. Use <code>["TASK_TYPE_EXPORT<wbr/>_MESSAGES_V2"]</code> para ver solo las exportaciones de mensajes. |
| `campaign` | No | String | Filtrar por [código de campaña](/es/developer/api-reference/api-identifiers/#campaign-code). |
| `message_id` | No | String (uint64) | Filtrar por un único ID de mensaje numérico, entre comillas. |
| `message_code` | No | String | Filtrar por un único [código de mensaje](/es/developer/api-reference/api-identifiers/#message-code). |
| `limit` | No | Integer | Número máximo de tareas a devolver. |
| `timestamp_from` | No | String | Solo devolver tareas creadas después de esta marca de tiempo (RFC 3339). |

<Aside type="note">
Las tareas se conservan durante 30 días, independientemente de si su archivo ya ha sido eliminado después del período de retención de archivos de 7 días. `lastTasks` aún puede mostrar una tarea cuyo `result` ya no se resuelve en un archivo descargable.
</Aside>

##### Solicitud de ejemplo

```json
{
  "application": "XXXXX-XXXXX",
  "types": ["TASK_TYPE_EXPORT_MESSAGES_V2"],
  "limit": 10
}
```

<Tabs>
<TabItem label="200: OK">
```json
{
  "tasks": [
    {
      "id": "177458",
      "timestamp": "2026-08-13T12:00:00Z",
      "status": "STATUS_SUCCESS",
      "requested_by_user": "user@example.com",
      "export_messages_v2": {
        "application_code": "XXXXX-XXXXX"
      },
      "export_messages_v2_result": {
        "file": "Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv"
      }
    }
  ]
}
```
</TabItem>
</Tabs>

### delete

Elimina una tarea y su archivo antes de que expire el período de retención de 7 días.

`POST` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/delete`

##### Parámetros del cuerpo de la solicitud

Pase el identificador de tarea devuelto por `export`:

| Nombre | Requerido | Tipo | Descripción |
|---|---|---|---|
| `uid` | Sí | String (int64) | Identificador de tarea de la respuesta de `export`, p. ej., `"177458"`. |

##### Solicitud de ejemplo

```json
{
  "uid": "177458"
}
```

<Tabs>
<TabItem label="200: OK">
```json
{}
```
</TabItem>
</Tabs>

### Descarga

Descarga el archivo CSV generado por `result`, por su nombre.

`GET` `https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/<file>`

##### Cabeceras

Autentíquese de la misma manera que los otros métodos, o confíe en una sesión activa del Panel de Control:

| Nombre | Requerido | Descripción |
|---|---|---|
| `Authorization`| Sí | [Token de la API del servidor](/es/developer/api-reference/api-access-token/#server-api-token), en el mismo formato que los otros métodos `exportMessagesStatistics`: `Authorization: Api <Server Key>` (el esquema `Api` no distingue entre mayúsculas y minúsculas). Una solicitud sin cabecera `Authorization` y sin una sesión iniciada en el Panel de Control obtiene `401 Unauthorized`. |

Reemplace `<file>` con el valor exacto de `file` de la respuesta de `result`, por ejemplo:

```
https://api.pushwoosh.com/api/v2/statistics/exportMessagesStatistics/download/Export_Messages_v2_12345_20260813120000-a1b2c3d4.csv
```

El archivo es un CSV que contiene las columnas seleccionadas en `properties`. Permanece disponible durante 7 días después de que finaliza la exportación, luego el trabajo de limpieza lo elimina y la URL deja de resolverse.