# API de Segmentação (Filtros)

## createFilter

`POST` `https://api.pushwoosh.com/json/1.3/createFilter`

Cria um novo filtro.

**Corpo da solicitação**

| Nome | Obrigatório | Tipo | Descrição |
| ---------------------------------------------------- | -------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| auth\* | Sim | string | [Token de acesso à API](/pt/developer/api-reference/api-identifiers/#api-access-token) do Painel de Controle da Pushwoosh. |
| name\* | Sim | string | [Nome do filtro](/pt/developer/api-reference/api-identifiers/#segment--filter-name). |
| filter\_expression\* | Sim | string | <p>Expressão construída de acordo com as regras da <a href="/developer/api-reference/segmentation-filters-api/segmentation-language/">linguagem de Segmentação</a>. <br /><strong>Exemplo:</strong> <code>T("City", eq, "Madrid")</code> para segmentar usuários cuja cidade é Madrid.</p> |
| application | Não | string | [Código da aplicação Pushwoosh](/pt/developer/api-reference/api-identifiers/#application-code). Este parâmetro é utilizável apenas com a Configuração de Alta Velocidade; caso contrário, omita-o. |
| expiration\_date | Não | string | Expiração do filtro. O filtro será excluído automaticamente na data especificada, a menos que seja usado em um Preset ou em um Feed RSS. |

**200**
```json
{
  "status_code": 200, 
  "status_message": "OK", 
  "response": {
    "name": "filter name"
  }
}
```



**Exemplo**
```json
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "name": "City = Madrid",
    "filter_expression": "T(\"City\", eq, \"Madrid\")",
    "application": "B18XX-XXXXX",
    "expiration_date": "2025-01-01"
  }
}

// criando Filtros para Fusos Horários
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // token de acesso à API do Painel de Controle da Pushwoosh
    "name": "Timezone Filter",
    "filter_expression": "T(\"Timezone\", BETWEEN, [\"UTC-12:00\", \"UTC+14:00\"])"
  }
}
```


## listFilters

`POST` `https://api.pushwoosh.com/json/1.3/listFilters`

Retorna uma lista de segmentos (filtros) disponíveis com suas condições.

**Corpo da Solicitação**

| Nome | Obrigatório | Tipo | Descrição |
| --------------------------------------------- | -------- | ------ | ---------------------------------------------- |
| auth\* | Sim | string | [Token de acesso à API](/pt/developer/api-reference/api-identifiers/#api-access-token) do Painel de Controle da Pushwoosh. |
| application\* | Sim | string | [Código da aplicação Pushwoosh](/pt/developer/api-reference/api-identifiers/#application-code) |


**200**
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": {
    "filters": [{
      "code": "52551-F2F42",
      "name": "City = Madrid",
      "filter_expression": "T(\"City\", eq, \"madrid\")",
      "expiration_date": "2025-01-01",
      "application": "B18XX-XXXXX"
    }]
  }
}

```


**Exemplo**
```json
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H",
    "application": "B18XX-XXXXX"
  }
}
```

## deleteFilter

`POST` `https://api.pushwoosh.com/json/1.3/deleteFilter`

Exclui um filtro existente.

**Corpo da Solicitação**

| Nome | Tipo | Descrição |
| -------------------------------------- | ------ | ---------------------------------------------- |
| auth\* | string | [Token de acesso à API](/pt/developer/api-reference/api-identifiers/#api-access-token) do Painel de Controle da Pushwoosh. |
| name\* | string | [Nome do filtro](/pt/developer/api-reference/api-identifiers/#segment--filter-name). |

<Tabs>
<TabItem label="200">
```json
{
  "status_code": 200,
  "status_message": "OK",
  "response": null
}
```
</TabItem>
</Tabs>



```json title="Exemplo"
{
  "request": {
    "auth": "yxoPUlwqm…………pIyEX4H", // token de acesso à API do Painel de Controle da Pushwoosh
    "name": "filter name"
  }
}
```

## exportSegment

`POST` `https://api.pushwoosh.com/api/v2/audience/exportSegment`

Uma solicitação agendada. Exporta a lista de assinantes que se enquadram nas condições de Filtro especificadas.

**Corpo da solicitação**
| Nome <div style="width:100px"></div> | Obrigatório <div style="width:100px"></div> | Tipo | Descrição |
|----------------------------|------------|---------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| auth\* | Sim | string | [Token de acesso à API](/pt/developer/api-reference/api-identifiers/#api-access-token) do Painel de Controle da Pushwoosh. |
| filterExpression\* | Sim | string | Condições do filtro |
| exportData | Não | array | Dados a serem exportados. Valores possíveis: `"hwids"`, `"push_tokens"`, `"users"`, `"tags"`, `"location"`. Incluir `"location"` adiciona as colunas `Latitude` e `Longitude` ao CSV exportado. Se `exportData` for omitido, `Latitude` e `Longitude` são incluídos na exportação por padrão. |
| filterCode | Não | string | [Código de filtro](/pt/developer/api-reference/api-identifiers/#segment--filter-code) pré-fabricado, pode ser usado em vez de `filterExpression`. Pode ser obtido na API `/listFilters` ou na barra de endereço do seu navegador ao visualizar o filtro no Painel de Controle. |
| applicationCode | Obrigatório se você estiver usando `filterExpression` ou `filterCode`. | string | [Código da aplicação Pushwoosh](/pt/developer/api-reference/api-identifiers/#application-code) |
| generateExport | Não | boolean | Por padrão, definido como `true`, e uma resposta contém um link para baixar o arquivo. Se for falso, apenas a contagem de dispositivos será enviada na resposta. |
| format | Não | string | Define o formato do arquivo exportado: "csv" ou "json\_each\_line". Se omitido, o arquivo CSV é gerado. |
| tagsList | Não | array | Especifica as [tags](/pt/developer/api-reference/api-identifiers/#tag) a serem exportadas. Para obter apenas as tags específicas, o array "exportData" deve conter o valor "tags". |
| includeWithoutTokens | Não | boolean | Defina como `true` para incluir usuários sem tokens de push no arquivo exportado. O padrão é `false`. |


<Tabs>
<TabItem label="200: Sucesso">
```json
{
  "task_id": "177458"
}
```
</TabItem>
</Tabs>



```json title="Exemplo"
{
  "auth": "yxoPUlwqm…………pIyEX4H",                           // obrigatório. Token de acesso à API do Painel de Controle da Pushwoosh
  "filterExpression": "AT(\"12345-67890\", \"Name\", any)", // condições do filtro, consulte o guia da Linguagem de Segmentação para a sintaxe 
  "filterCode": "12345-67890",                              // código de filtro pré-fabricado, pode ser usado em vez de filterExpression
  "applicationCode": "00000-AAAAA",                         // Obrigatório se você estiver usando `filterExpression` ou `filterCode`. Código da aplicação Pushwoosh. Pode ser obtido na solicitação da API /listFilters ou na barra de endereço do seu navegador ao visualizar o filtro no Painel de Controle.
  "generateExport": true,                                   // se for falso, apenas a contagem de dispositivos será enviada na resposta; por padrão, uma resposta contém um link para baixar o arquivo CSV
  "format": "json_each_line",                               // formato do arquivo para apresentar os dados: "csv" – o arquivo .csv é baixado; "json" – um arquivo JSON com todos os dispositivos exportados; ou "json_each_line" – uma linha JSON para cada dispositivo. Se não for especificado, CSV é o formato padrão. 
  "exportData": ["hwids", "tags"],                          // opcional. Dados a serem exportados. Valores possíveis: "hwids", "push_tokens", "users", "tags", "location", "fcm_keys", "web keys"
  "tagsList": ["Name", "Level"],                            // opcional. Especifica as tags a serem exportadas. Para obter apenas as tags específicas, o valor "tags" deve ser enviado dentro do array "exportData" ou o "exportData" deve estar vazio. 
  "includeWithoutTokens": true                              // opcional. Defina como true para incluir usuários sem tokens de push no arquivo exportado. O padrão é false.
}
```

<Aside type="note">
Por favor, encontre a referência da Linguagem de Segmentação para escrever expressões de filtro [aqui](/pt/developer/api-reference/segmentation-filters-api/segmentation-language/).
</Aside>

Por exemplo, para exportar todos os assinantes de um aplicativo específico, use as seguintes condições de Filtro:

```json
{
  "auth": "yxoPUlwqm…………pIyEX4H",            // token de acesso à API do Painel de Controle da Pushwoosh
  "filterExpression": "A(\"AAAAA-BBBBB\")",  // Expressão de filtro referenciando o segmento do aplicativo
  "applicationCode": "AAAAA-BBBBB"           // Código de aplicativo Pushwoosh obrigatório
}
```

<Aside type="caution">
Na resposta, você receberá o **`task_id`** para obter o arquivo resultante. Em seguida, chame [/exportSegment/result](./#exportsegment-results) com esse `task_id` no corpo da solicitação para recuperar o arquivo resultante.
</Aside>

## exportSegment results

`POST` `https://api.pushwoosh.com/api/v2/audience/exportSegment/result`

**Recupera o link para o CSV com os resultados de /exportSegment.**

**Corpo da Solicitação**

| Nome | Tipo | Descrição |
| ------------------------------------------ | ------ | -------------------------------------------------------- |
| auth\* | String | [Token de acesso à API](/pt/developer/api-reference/api-identifiers/#api-access-token) do Painel de Controle da Pushwoosh. |
| task\_id\* | String | Identificador recebido na sua resposta `/exportSegment`. |

<Tabs>
<TabItem label="200: OK">
```json
{
  "devicesCount": "24735",
  "filename": "https://static.pushwoosh.com/segment-export/export_segment_XXXXX_XXXXX_xxxxxxxxxxxxxxxxx.csv.zip",
  "status": "completed"
}
```
</TabItem>
</Tabs>

Passe o "**task\_id**" recebido na sua resposta `/exportSegment` no corpo da solicitação `/exportSegment/result`.

Na resposta `/exportSegment/result`, você receberá o parâmetro "filename". Siga o link fornecido no valor desse parâmetro para baixar automaticamente um arquivo ZIP. Descompacte o arquivo para recuperar o arquivo CSV ou JSON (dependendo do "format" especificado em sua solicitação) contendo os dados dos dispositivos.

A partir de 3 de abril de 2025, a autorização será necessária para baixar o arquivo:

- Se estiver baixando por um **navegador**, basta fazer login no **Painel de Controle da Pushwoosh** para obter acesso.
- Se estiver baixando por um **software de servidor**, inclua o seguinte cabeçalho em sua solicitação:
`Authorization: Token SEU_TOKEN_DE_API`

Se você especificar o "exportData" em sua solicitação `/exportSegment`, o arquivo baixado conterá apenas os dados solicitados. Por padrão, o arquivo contém os seguintes dados do usuário:

| **Campo** | Descrição | Exemplo de valor |
| ------------------ | ----------------------------------------------------------------------------------------------- | ------------------------------------ |
| Hwid | [ID de Hardware de um dispositivo](/pt/developer/api-reference/api-identifiers/#hardware-id) | 01D1BA5C-AAAA-0000-BBBB-9B81CD5823C8 |
| User ID | [ID de Usuário](/pt/developer/api-reference/api-identifiers/#user-id) associando um dispositivo a um usuário específico. Se nenhum ID de Usuário for atribuído, o HWID é usado. | user8192 |
| Push Token | Identificador único atribuído a um dispositivo por gateways de mensagens na nuvem. [Saiba mais](/pt/developer/api-reference/api-identifiers/#push-token) | eeeb2fd7....0fc3547 |
| Type | Tipo de plataforma (inteiro). | 1 |
| Type (humanized) | Tipo de plataforma (string). | iOS |
| Age | Valor da tag padrão Idade. | 29 |
| ApplicationVersion | Valor da tag padrão Versão da Aplicação. | 1.12.0.0 |
| City | Valor da tag padrão Cidade. | us, boston |
| TagName | Valor de uma tag criada em sua conta. | TagValue |