# Exportação assíncrona de estatísticas de mensagens

`exportMessagesStatistics` exporta o histórico e as estatísticas de mensagens para um arquivo CSV no servidor. Use-o para extrações grandes ou de contas completas que o [`messages:list`](/pt/developer/api-reference/statistics-api/message-statistics-api/#messageslist) não consegue lidar.

## Quando usar a exportação em vez de messages:list

Use `messages:list` para pesquisas ao vivo e paginadas de um período delimitado. Use `exportMessagesStatistics` quando o resultado exceder o limite de paginação profunda de `messages:list` (`page × per_page > 100000`), ou quando o objetivo for um único arquivo para download em vez de JSON paginado. A exportação não tem limite de `date_range` ou contagem de linhas, porque transmite o resultado para um arquivo em disco em vez de mantê-lo em uma única resposta.

## Como funciona o fluxo de exportação

1. Chame [`export`](#export) com os mesmos filtros que `messages:list`. A resposta retorna um identificador de tarefa `uid` imediatamente, antes que o arquivo seja gerado.
2. Consulte [`status`](#status) com esse `uid` até que ele relate `STATUS_SUCCESS` (ou `STATUS_FAILED`).
3. Chame [`result`](#result) com o mesmo `uid` para obter o nome do arquivo gerado.
4. [Baixe](#download) o arquivo pelo nome.

Use [`lastTasks`](#lasttasks) para procurar tarefas de exportação recentes para um aplicativo e [`delete`](#delete) para cancelar uma tarefa ou remover seu arquivo antecipadamente.

## Métodos

O ciclo de vida da exportação tem cinco métodos, mais um endpoint de download simples:

| Método | Descrição |
|--------|--------------|
| [`exportMessagesStatistics/export`](#export) | Enfileira uma exportação e retorna um `uid` de tarefa. |
| [`exportMessagesStatistics/status`](#status) | Verifica o progresso da tarefa. |
| [`exportMessagesStatistics/result`](#result) | Retorna o nome do arquivo gerado assim que a tarefa é concluída. |
| [`exportMessagesStatistics/lastTasks`](#lasttasks) | Lista tarefas de exportação recentes para um aplicativo. |
| [`exportMessagesStatistics/delete`](#delete) | Cancela uma tarefa ou remove seu arquivo antes que o período de retenção expire. |
| [Download](#download) | Baixa o arquivo CSV gerado pelo nome. |

### export

Enfileira uma exportação do histórico de mensagens e retorna um identificador de tarefa imediatamente.

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

##### Cabeçalhos

A solicitação precisa de um token de API do Servidor:

| Nome             | Obrigatório | Descrição                                                                                          |
|------------------|----------|---------------------------------------------------------------------------------------------------------|
| `Authorization`  | Sim      | [Token de API do Servidor](/pt/developer/api-reference/api-access-token/#server-api-token). Deve ser fornecido no seguinte formato: `Authorization: Api <Server Key>`.     |

##### Parâmetros do corpo da solicitação

O corpo da solicitação aceita os seguintes campos:

| Nome                                  | Obrigatório | Tipo    | Descrição                                                                                                                     |
|----------------------------------------|----------|---------|--------------------------------------------------------------------------------------------------------------------------------|
| `type`                                | Sim      | String  | Deve ser <code>"TASK_TYPE_EXPORT<wbr/>_MESSAGES_V2"</code>.                                                                                     |
| <code>export_messages<wbr/>_v2</code>                  | Sim      | Object  | Parâmetros de exportação, descritos abaixo.                                                                                            |
| <code>export_messages<wbr/>_v2.application<wbr/>_code</code> | Ver nota | String  | [Código do aplicativo Pushwoosh](/pt/developer/api-reference/api-identifiers/#application-code). Obrigatório se `app_group_code` não estiver definido. |
| <code>export_messages<wbr/>_v2.app<wbr/>_group_code</code>   | Ver nota | String  | Código do grupo de aplicativos, exporta para todos os aplicativos do grupo. Obrigatório se `application_code` não estiver definido.                     |
| <code>export_messages<wbr/>_v2.search</code>           | Não       | String  | Pesquisa de texto livre no título e conteúdo da mensagem.                                                                               |
| <code>export_messages<wbr/>_v2.filters</code>          | Não       | Object  | Filtros de mensagem, descritos abaixo. Omita para exportar todo o histórico da conta.                                                    |
| <code>export_messages<wbr/>_v2.properties</code>       | Não       | Array   | Colunas a serem incluídas no CSV, descritas abaixo.                                                                                 |

`export_messages_v2.filters` aceita:

| Nome <div style="width:150px"></div> | Tipo    | Descrição                                                                                                                             |
|---------------------------------------|---------|-------------------------------------------------------------------------------------------------------------------------------------------|
| `statuses`                            | Array   | Status da mensagem a serem incluídos. <details><summary>Valores possíveis</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](/pt/developer/api-reference/messages-api/api-prerequisites/#platforms) (numéricos, ex. `1` para iOS), não as strings de nome de plataforma usadas por `messages:list`. |
| `sent_date`                           | Object  | Período de relatório filtrado pela data de envio: `{"date_from": "YYYY-MM-DD", "date_to": "YYYY-MM-DD"}`.                                          |
| `created_date`                        | Object  | Período de relatório filtrado pela data de criação da mensagem, mesmo formato que `sent_date`.                                                          |
| `created_via`                         | Array   | Origem da mensagem. <details><summary>Valores possíveis</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](/pt/developer/api-reference/api-identifiers/#segment--filter-code) para os quais a mensagem foi enviada.                                 |
| `campaigns`                           | Array   | [Códigos de campanha](/pt/developer/api-reference/api-identifiers/#campaign-code). Ao contrário de `messages:list`, este aceita uma lista, não um único código. |
| `message_id`                          | String (uint64) | Um único ID de mensagem numérico, entre aspas. Ao contrário de `messages:list`, a exportação aceita um ID, não um array.                                |
| `message_code`                        | String  | Um único [código de mensagem](/pt/developer/api-reference/api-identifiers/#message-code).                                                        |

`export_messages_v2.properties` seleciona quais colunas o CSV contém.

<details>
<summary>Valores possíveis</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 não é apenas um filtro">
Uma propriedade não listada em `properties` não aparece no arquivo, incluindo as colunas base (ID, data de envio, conteúdo, status). Deixar `properties` vazio produz um CSV sem colunas. Liste todas as colunas que a exportação deve conter, não apenas as métricas que você deseja adicionar a um conjunto padrão.
</Aside>

##### Exemplo de solicitação

```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: Incorrect API access token">
```json
{
  "error": "account not found"
}
```
</TabItem>
</Tabs>

### status

Retorna o progresso de uma tarefa de exportação.

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

##### Parâmetros do corpo da solicitação

Passe o identificador da tarefa retornado por `export`:

| Nome  | Obrigatório | Tipo    | Descrição                                     |
|-------|----------|---------|--------------------------------------------------|
| `uid` | Sim      | String (int64) | Identificador da tarefa da resposta de `export`, ex. `"177458"`. |

##### Exemplo de solicitação

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

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

`status` é um de `"STATUS_PENDING"`, `"STATUS_SUCCESS"`, ou `"STATUS_FAILED"`. `progress` é uma fração entre `0` e `1`; consulte `status` até que atinja `"STATUS_SUCCESS"` antes de chamar `result`.

### result

Retorna o nome do arquivo gerado assim que a tarefa for concluída.

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

##### Parâmetros do corpo da solicitação

Passe o mesmo identificador de tarefa retornado por `export`:

| Nome  | Obrigatório | Tipo    | Descrição                                     |
|-------|----------|---------|--------------------------------------------------|
| `uid` | Sim      | String (int64) | Identificador da tarefa da resposta de `export`, ex. `"177458"`. |

##### Exemplo de solicitação

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

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

Chamar `result` antes que `status` relate `"STATUS_SUCCESS"` retorna um resultado vazio. Passe o valor de `file` como está para o [endpoint de download](#download).

### lastTasks

Lista as tarefas de exportação recentes para um aplicativo, da mais recente para a mais antiga.

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

##### Parâmetros do corpo da solicitação

Cada parâmetro é um filtro opcional; omita todos eles para listar todas as tarefas às quais o token tem acesso:

| Nome             | Obrigatório | Tipo    | Descrição                                                                         |
|------------------|----------|---------|---------------------------------------------------------------------------------------|
| `application`    | Não       | String  | [Código do aplicativo Pushwoosh](/pt/developer/api-reference/api-identifiers/#application-code). Omita para listar tarefas de todos os aplicativos aos quais o token tem acesso. |
| `types`          | Não       | Array   | Restringir a tipos de tarefa específicos. Use <code>["TASK_TYPE_EXPORT<wbr/>_MESSAGES_V2"]</code> para ver apenas as exportações de mensagens. |
| `campaign`       | Não       | String  | Filtrar por [código de campanha](/pt/developer/api-reference/api-identifiers/#campaign-code).  |
| `message_id`     | Não       | String (uint64) | Filtrar por um único ID de mensagem numérico, entre aspas.                                  |
| `message_code`   | Não       | String  | Filtrar por um único [código de mensagem](/pt/developer/api-reference/api-identifiers/#message-code). |
| `limit`          | Não       | Integer | Número máximo de tarefas a serem retornadas.                                                    |
| `timestamp_from` | Não       | String  | Retornar apenas tarefas criadas após este timestamp (RFC 3339).                          |

<Aside type="note">
As tarefas são mantidas por 30 dias, independentemente de seu arquivo já ter sido excluído após o período de retenção de 7 dias. `lastTasks` ainda pode mostrar uma tarefa cujo `result` não resolve mais para um arquivo para download.
</Aside>

##### Exemplo de solicitação

```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

Exclui uma tarefa e seu arquivo antes que o período de retenção de 7 dias expire.

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

##### Parâmetros do corpo da solicitação

Passe o identificador da tarefa retornado por `export`:

| Nome  | Obrigatório | Tipo    | Descrição                                     |
|-------|----------|---------|--------------------------------------------------|
| `uid` | Sim      | String (int64) | Identificador da tarefa da resposta de `export`, ex. `"177458"`. |

##### Exemplo de solicitação

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

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

### Download

Baixa o arquivo CSV gerado por `result`, pelo nome.

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

##### Cabeçalhos

Autentique da mesma forma que os outros métodos, ou confie em uma sessão ativa do Painel de Controle:

| Nome             | Obrigatório | Descrição                                                                                          |
|------------------|----------|-----------------------------------------------------------------------------------------------------|
| `Authorization`| Sim      | [Token de API do Servidor](/pt/developer/api-reference/api-access-token/#server-api-token), no mesmo formato que os outros métodos `exportMessagesStatistics`: `Authorization: Api <Server Key>` (o esquema `Api` não diferencia maiúsculas de minúsculas). Uma solicitação sem o cabeçalho `Authorization` e sem uma sessão de Painel de Controle logada recebe `401 Unauthorized`.     |

Substitua `<file>` pelo valor exato de `file` da resposta de `result`, por exemplo:

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

O arquivo é um CSV contendo as colunas selecionadas em `properties`. Ele permanece disponível por 7 dias após o término da exportação, depois o trabalho de limpeza o remove e a URL para de resolver.