# API de Audiencia

## bulkSetTags

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

Establece los valores de las etiquetas para la lista de dispositivos.

<Aside type="caution" title="Importante">
  Al usar el método `bulkSetTags`, asegúrese de que los valores de las etiquetas se establezcan para un mínimo de 50 dispositivos. Para establecer etiquetas para un solo dispositivo, use el método [`setTags`](/es/developer/api-reference/device-api/#settags).
</Aside>

#### Cuerpo de la solicitud

| Nombre                                           | Tipo    | Descripción                                                                 |
| ---------------------------------------------- | ------- | --------------------------------------------------------------------------- |
| application\*  | String  | [Código de aplicación de Pushwoosh](/es/developer/api-reference/api-identifiers/#application-code)                                                     |
| auth\*         | String  | [Token de acceso a la API](/es/developer/api-reference/api-identifiers/#api-access-token) desde el Panel de Control de Pushwoosh.                              |
| create\_missing\_tags                          | Boolean | Si es verdadero, las etiquetas faltantes se crean automáticamente.                            |
| devices\*      | Object  | Array de dispositivos.                                                           |
| devices.hwid                                   | String  | Se puede usar para identificar un dispositivo en lugar de user\_id o push\_token. [Más información](/es/developer/api-reference/api-identifiers/#hardware-id)         |
| devices.user\_id                               | String  | Se puede usar para identificar un usuario en lugar de hwid o push\_token. [Más información](/es/developer/api-reference/api-identifiers/#user-id)               |
| devices.push\_token                            | String  | Se puede usar para identificar un dispositivo en lugar de hwid o user\_id. [Más información](/es/developer/api-reference/api-identifiers/#push-token)                |
| devices.list\_operator                         | String  | Define cómo establecer valores para [etiquetas](/es/developer/api-reference/api-identifiers/#tag) de tipo lista: set, append o remove |
| devices.tags\* | Object  | Valores a establecer para las etiquetas especificadas.                                       |

<Tabs>
  <TabItem label="OK">
    ```json
    {
      "request_id": "request_id para usar en el método GET para obtener el estado del trabajo",
      "status": "Pending"
    }
    ```
  </TabItem>

  <TabItem label="Error">
    ```json
    {
      "message": "solicitud no válida"
    }
    ```
  </TabItem>
</Tabs>


```json title="Solicitud:"
{
  "application": "código de aplicación",   // requerido. Código de la aplicación Pushwoosh
  "auth": "token de autenticación de Pushwoosh",      // requerido. Token de acceso a la API desde el Panel de Control de Pushwoosh
  "create_missing_tags": false,        // opcional. Debería crear automáticamente las etiquetas faltantes
  "devices": [{                        // requerido. Array de dispositivos
    "hwid": "hwid del dispositivo",             // opcional. Se puede usar para identificar un dispositivo en lugar de
                                       //           "user_id" o "push_token".
    "user_id": "ID de usuario",              // opcional. Se puede usar para identificar un usuario en lugar de "hwid" o "push_token".
    "push_token": "token de push del dispositivo", // opcional. Se puede usar para identificar un dispositivo en lugar de "hwid" o "user_id".
    "list_operator": "set",            // requerido. Para etiquetas de lista. Define cómo establecer valores para
                                       //           etiquetas de tipo lista: set, append o remove
    "tags": {                          // requerido. Valores a establecer para las etiquetas especificadas.
      "tag_name": "tagvalue",          //           use el tipo de valor correcto
      "tag_name2": "tagvalue2"
    }
  }]
}

```

```json title="Respuesta:"
{
  "request_id": "request_id para usar en el método GET para obtener el estado del trabajo",
  "status": "Pending"
}
```

## Estado de bulkSetTags

`GET` `https://api.pushwoosh.com/api/v2/audience/bulkSetTags/{request_id}?detailed=false`

Devuelve el estado de la operación `/bulkSetTags`

#### Parámetros de ruta

| Nombre        | Tipo   | Descripción                                |
| ----------- | ------ | ------------------------------------------ |
| request\_id | String | ID de solicitud de la llamada `/bulkSetTags` anterior |

#### Parámetros de consulta

| Nombre     | Tipo    | Descripción                                             |
| -------- | ------- | ------------------------------------------------------- |
| detailed | Boolean | (true/false) si se debe devolver información detallada por dispositivo |

```json title="Respuesta:"
{
  "request_id": "id de la solicitud",
  "status": "Completed",          // también "Pending", "Failed"
  "progress": 100,                // progreso del trabajo 0-100
  "devices_success": 100,         // dispositivos correctos
  "devices_not_found": 0,         // dispositivos no encontrados en Pushwoosh
  "devices_failed": 0,            // con errores
  "devices": [{                   // reporte del dispositivo (solo con detailed = true)
    "hwid": "hwid del dispositivo",
    "status": "done",             // también "failed", "not found"
    "tags": {
      "tagName": "ok",
      "tagName2": "etiqueta no encontrada",
      "tagName3": "valor incorrecto. se espera :string"
    }
  }]
}

```

## bulkRegisterDevice

Registra múltiples dispositivos en Pushwoosh en una sola solicitud. También permite especificar varias etiquetas para cada dispositivo.

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

### Parámetros del cuerpo de la solicitud

| Parámetro | Tipo | Requerido | Descripción |
| :---- | ----- | ----- | ----- |
| application | string | Sí | [Código de aplicación de Pushwoosh](/es/developer/api-reference/api-identifiers/#application-code) |
| auth | string | Sí | [Token de acceso a la API](/es/developer/api-reference/api-identifiers/#api-access-token). |
| devices | array | Sí | Un array de objetos de dispositivo. Cada objeto representa un dispositivo y sus datos asociados. Vea los detalles en la tabla de **Parámetros del objeto Device** a continuación. |

#### Parámetros del objeto Device

| Parámetro       | Tipo     | Requerido | Descripción                                                                                     |
|-----------------|----------|----------|-------------------------------------------------------------------------------------------------|
| hwid          | string | Sí      | [El ID de hardware](/es/developer/api-reference/api-identifiers/#hardware-id) o identificador único para el dispositivo.                                           |
| push_token    | string | Sí      | [Token de push](/es/developer/api-reference/api-identifiers/#push-token) para el dispositivo.                                                                     |
| platform      | integer| Sí      | El identificador de la plataforma. [Más información](/es/developer/api-reference/messages-api/api-prerequisites/#platforms) |
| list_operator | string | No       | Determina la acción para las etiquetas de tipo lista: <br/> - **"append"**: Añade el valor especificado a la lista de etiquetas. <br/> - **"remove"**: Elimina el valor especificado de la lista de etiquetas. <br/> **Nota**: Si no se especifica el parámetro `list_operator`, todos los valores existentes en la lista de etiquetas serán reemplazados por los valores proporcionados. |
| tags          | object | No       | [Etiquetas](/es/developer/api-reference/api-identifiers/#tag) personalizadas asignadas al dispositivo. Las etiquetas son pares clave-valor utilizados para la segmentación.            |



#### Ejemplo de solicitud

```json
{
  "application": "código de aplicación",   // requerido. Código de la aplicación Pushwoosh
  "auth": "token de autenticación de Pushwoosh",      // requerido. Token de acceso a la API desde el Panel de Control de Pushwoosh
  "devices": [{                        // requerido. Array de dispositivos
    "hwid": "hwid del dispositivo",             // requerido. Identificador único para el dispositivo (puede ser un correo electrónico).
    "push_token": "token de push del dispositivo", // requerido. Token de notificación push para el dispositivo.
    "platform": 14,                    // requerido. Plataforma del dispositivo (p. ej., 14 para correo electrónico).
    "list_operator": "append",         // opcional. Para etiquetas de lista. Añade o elimina el/los valor(es) especificado(s) de la etiqueta de tipo lista.
    "tags": {                          // opcional. Valores a establecer para las etiquetas especificadas.
      "language": "en",                //           use el tipo de valor correcto.
      "CSV_Import": "summer_camp"
    }
  },
  {
    "hwid": "hwid del dispositivo 2",           // requerido. Identificador único para el segundo dispositivo.
    "push_token": "token de push del dispositivo 2", // requerido. Token de notificación push para el dispositivo.
    "platform": 14,                    // requerido. Plataforma del dispositivo.
    "list_operator": "remove",         // opcional. Añade o elimina valores de las etiquetas de tipo lista.
    "tags": {                          // opcional. Valores a eliminar de las etiquetas especificadas.
      "language": "en",
      "CSV_Import": "summer_camp2"
    }
  },
  {
    "hwid": "hwid del dispositivo 3",           // requerido. Identificador único para el tercer dispositivo.
    "push_token": "token de push del dispositivo 3", // requerido. Token de notificación push para el dispositivo.
    "platform": 14,                    // requerido. Plataforma del dispositivo.
    "tags": {                          // opcional. Valores a establecer para las etiquetas especificadas.
      "language": "en",
      "CSV_Import": "summer_camp3"
    }
  }]
}

```

### Respuesta

El método responde con un ID de operación, que se puede usar para rastrear el estado y los resultados del proceso de registro masivo.

```json
{
  "request_id": "request_id para usar en el método GET para obtener el estado del trabajo",
  "status": "Pending"
}

```

## Estado de bulkRegisterDevice

Puede verificar el estado de un proceso de registro masivo haciendo la siguiente solicitud **GET**:

`GET` `https://api.pushwoosh.com/api/v2/audience/bulkRegisterDevice/{request_id}?detailed=true`

| Parámetro | Tipo | Requerido | Descripción |
| ----- | ----- | ----- | ----- |
| request_id | string | Sí | El ID de solicitud devuelto por la solicitud POST. |
| detailed | boolean | No | Si se establece en `true`, la respuesta incluye resultados detallados para cada dispositivo registrado. |


#### Ejemplo de respuesta

```json
{
  "request_id": "9a2e1a14-XXXX-46c3-XXXX-c254b25d3782",
  "status": "Completed",
  "progress": 100,
  "devices_success": 4,
  "devices": [
    {
      "hwid": "user1@example.com",
      "status": "done"
    },
    {
      "hwid": "user2@example.com",
      "status": "done"
    },
    {
      "hwid": "user3@example.com",
      "status": "done"
    },
    {
      "hwid": "invalid_email@example.com",
      "status": "failed"
    }
  ]
}

```

## bulkUnregisterDevice

Da de baja a múltiples dispositivos de Pushwoosh en una sola solicitud.

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

### Parámetros del cuerpo de la solicitud

| Parámetro | Tipo | Requerido | Descripción |
| :---- | ----- | ----- | ----- |
| application | string | Sí | [Código de aplicación de Pushwoosh](/es/developer/api-reference/api-identifiers/#application-code) |
| auth | string | Sí | [Token de acceso a la API](/es/developer/api-reference/api-identifiers/#api-access-token) |
| devices | array | Sí | Un array de objetos de dispositivo. Cada objeto representa un dispositivo y sus datos asociados. Vea los detalles en la tabla de **Parámetros del objeto Device** a continuación. |

#### Parámetros del objeto Device

| Parámetro       | Tipo     | Requerido | Descripción                                                                                     |
|-----------------|----------|----------|-------------------------------------------------------------------------------------------------|
| hwid          | string | Sí      | El ID de hardware o identificador único para el dispositivo. [Más información](/es/developer/api-reference/api-identifiers/#hardware-id)                                          |



#### Ejemplo de solicitud

```json
{
  "application": "código de aplicación",   // requerido. Código de la aplicación Pushwoosh
  "auth": "token de autenticación de Pushwoosh",      // requerido. Token de acceso a la API desde el Panel de Control de Pushwoosh
  "devices": [{                        // requerido. Array de dispositivos
    "hwid": "hwid del dispositivo",             // requerido. Identificador único para el dispositivo (puede ser un correo electrónico).
  },
  {
    "hwid": "hwid del dispositivo 2",           // requerido. Identificador único para el segundo dispositivo.
  },
  {
    "hwid": "hwid del dispositivo 3",           // requerido. Identificador único para el tercer dispositivo.
  }]
}

```

### Respuesta

El método responde con un ID de operación, que se puede usar para rastrear el estado y los resultados del proceso masivo.

```json
{
  "request_id": "request_id para usar en el método GET para obtener el estado del trabajo",
  "status": "Pending"
}

```

## Estado de bulkUnregisterDevice

Puede verificar el estado de un proceso de baja masiva haciendo la siguiente solicitud **GET**:

`GET` `https://api.pushwoosh.com/api/v2/audience/bulkUnregisterDevice/{request_id}?detailed=true`

| Parámetro | Tipo | Requerido | Descripción |
| ----- | ----- | ----- | ----- |
| request_id | string | Sí | El ID de solicitud devuelto por la solicitud POST. |
| detailed | boolean | No | Si se establece en `true`, la respuesta incluye resultados detallados para cada dispositivo dado de baja. |


#### Ejemplo de respuesta

```json
{
  "request_id": "9a2e1a14-XXXX-46c3-XXXX-c254b25d3782",
  "status": "Completed",
  "progress": 100,
  "devices_success": 4,
  "devices": [
    {
      "hwid": "user1@example.com",
      "status": "done"
    },
    {
      "hwid": "user2@example.com",
      "status": "done"
    },
    {
      "hwid": "user3@example.com",
      "status": "done"
    },
    {
      "hwid": "invalid_email@example.com",
      "status": "failed"
    }
  ]
}

```