# API de eliminación de datos

La API de eliminación de datos es la forma de autoservicio para eliminar los datos personales de un sujeto de Pushwoosh (derecho de eliminación de GDPR). La eliminación es irreversible: úsela para reflejar la página de [Solicitudes de datos](/es/product/account-management-and-security/data-requests/) del Panel de Control y la acción [Borrar datos personales](/es/product/audience-data-and-segmentation/user-explorer/#erase-personal-data) en la tarjeta de un suscriptor desde sus propios sistemas.

## URL Base

```
https://rpc-api.svc-nue.pushwoosh.com
```

Todos los endpoints se sirven a través de HTTPS. Las solicitudes y respuestas usan `application/json`, excepto [Upload](#upload), que usa `multipart/form-data`.

## Autenticación

Cada solicitud debe incluir un encabezado `Authorization` con su [token de la API del servidor](/es/developer/api-reference/api-access-token/#server-api-token):

```
Authorization: Api YOUR_API_TOKEN
```

El token debe tener acceso de modificación a cada aplicación nombrada en `application_codes`. Es el mismo acceso que un token necesita para escribir datos de dispositivo en esas aplicaciones.

<span id="conventions" />

## Convenciones

* **Nomenclatura de campos:** los cuerpos de las solicitudes aceptan `lowerCamelCase` (por ejemplo, `applicationCodes`, `identifierType`). Las respuestas se serializan usando los nombres de campo de proto, en `snake_case` (`task_id`, `identifier_hash`, etc.). Los ejemplos y las referencias de objetos a continuación usan ese formato.
* **Identificadores:** un sujeto se direcciona mediante `identifier_type` (`SUBJECT_IDENTIFIER_USER_ID`, `SUBJECT_IDENTIFIER_HWID`, o `SUBJECT_IDENTIFIER_EMAIL`) más una lista de `identifiers` de ese único tipo. Un identificador de correo electrónico se compara sin distinguir mayúsculas y minúsculas.
* **Primero un dry run, luego cítelo:** [Create](#create) con `dry_run: true` solo cuenta lo que se eliminaría y no escribe nada. Citar el `task_id` de ese dry run como `confirmation_dry_run_task_id` en la llamada real es opcional, pero si cita uno, debe coincidir exactamente con las aplicaciones e identificadores de ese dry run, y debe llamarse dentro de los 15 minutos posteriores a su finalización. De lo contrario, la llamada se rechaza.
* **Los informes nunca llevan el identificador en texto claro.** Tanto [GetTaskReport](#gettaskreport) como [GetJournalReport](#getjournalreport) informan cada identificador como su hash sha256 (`identifier_hash`), y el cuerpo del informe se codifica en CSV como base64 dentro de la respuesta JSON.

### Respuestas de error

| Estado HTTP | Significado |
| :---- | :---- |
| `400 Bad Request` | Argumento no válido, como un `identifier_type`, `identifiers`, o `application_codes` vacío, más de 10,000 identificadores, más de 50 aplicaciones, identificadores × aplicaciones por encima de 50,000, una cadena de identificador vacía, o (solo Upload) un archivo CSV faltante o ilegible. También se devuelve como `FailedPrecondition` en la transmisión cuando un `confirmation_dry_run_task_id` citado no coincide con el dry run finalizado que nombra, es demasiado antiguo (más de 15 minutos), o no es un dry run finalizado en absoluto. |
| `401 Unauthorized` | Encabezado `Authorization` faltante o no válido. |
| `403 Forbidden` | El token no tiene derecho de modificación/datos de dispositivo en una de las aplicaciones solicitadas, o quien llama no puede leer la tarea/informe solicitado. |
| `404 Not Found` | No se encontró la tarea, o no pertenece a la cuenta de quien llama. |
| `413 Payload Too Large` | (solo Upload) el archivo subido supera los 5 MB. |
| `429 Too Many Requests` | La cuenta ya inició 20 tareas de eliminación de datos (dry runs incluidos) en las últimas 24 horas. |

## Endpoints

| Método | Ruta | Descripción |
| :---- | :---- | :---- |
| `POST` | `/api/data_erasure/tasks` | Crear una tarea de eliminación (o dry-run) |
| `POST` | `/api/data_erasure/upload` | Crear una tarea de eliminación a partir de un CSV subido de identificadores |
| `GET` | `/api/data_erasure/tasks` | Listar las tareas de eliminación de la cuenta |
| `GET` | `/api/data_erasure/tasks/{task_id}` | Obtener una tarea de eliminación |
| `GET` | `/api/data_erasure/tasks/{task_id}/rows` | Listar los resultados por identificador de una tarea |
| `GET` | `/api/data_erasure/tasks/{task_id}/report` | Descargar el informe de una tarea como CSV |
| `GET` | `/api/data_erasure/report` | Descargar todas las tareas de un período como un único CSV |

## Create

Comienza a eliminar los datos personales de los sujetos listados en las aplicaciones listadas. Con `dry_run: true`, la tarea solo cuenta lo que se eliminaría.

`POST` `/api/data_erasure/tasks`

### Cuerpo de la solicitud

| Parámetro | Tipo | Requerido | Descripción |
| :---- | :---- | :---- | :---- |
| `identifierType` | string | Sí | `SUBJECT_IDENTIFIER_USER_ID`, `SUBJECT_IDENTIFIER_HWID`, o `SUBJECT_IDENTIFIER_EMAIL`. |
| `identifiers` | array de strings | Sí | Identificadores de sujeto de ese único tipo, hasta 10,000 por tarea, sin valores vacíos. |
| `applicationCodes` | array de strings | Sí | [Códigos de aplicación](/es/developer/api-reference/api-identifiers/#application-code) desde los que eliminar, hasta 50. No hay forma de eliminar de todas las aplicaciones de la cuenta en una sola llamada, así que nombre cada una explícitamente. `identifiers.length × applicationCodes.length` no debe superar 50,000, porque el informe contiene una fila por identificador por aplicación. |
| `dryRun` | boolean | No | Cuenta lo que se eliminaría y no escribe nada. El valor predeterminado es `false`. |
| `confirmationDryRunTaskId` | integer | No | `task_id` de un dry run finalizado que midió esta eliminación exacta. Consulte [Convenciones](#conventions). |

##### Ejemplo de solicitud

```json
{
  "identifierType": "SUBJECT_IDENTIFIER_EMAIL",
  "identifiers": ["subject@example.com"],
  "applicationCodes": ["XXXXX-XXXXX"],
  "dryRun": true
}
```

### Respuesta

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `task_id` | integer | Id de la tarea creada. Úselo con todos los demás endpoints de esta página. |

<Aside type="danger">
La eliminación no se puede deshacer. Eliminar a un sujeto elimina sus datos en todas las aplicaciones nombradas, pero no cancela los mensajes ya programados o en cola para ese sujeto, por ejemplo un envío retrasado o el siguiente paso de un Journey en ejecución.
</Aside>

## Upload

Crea el mismo tipo de tarea que [Create](#create), pero los identificadores provienen de un CSV subido en lugar de un array JSON. Use esto para una lista masiva de sujetos.

`POST` `/api/data_erasure/upload`

### Solicitud (multipart/form-data)

| Campo | Requerido | Descripción |
| :---- | :---- | :---- |
| `file` | Sí | Archivo CSV, hasta 5 MB, un identificador por fila, en la única columna. La primera fila puede nombrar la columna (`user_id`, `userid`, `user id`, `hwid`, `email`, `identifier`, o `subject`, sin distinguir mayúsculas y minúsculas) en lugar de contener un identificador. Esa fila se omite entonces como encabezado, sin contarse. Las filas en blanco se omiten y se cuentan por separado. Los identificadores duplicados (sin distinguir mayúsculas y minúsculas, para email) se colapsan en uno y se cuentan por separado. |
| `identifier_type` | Sí | `user_id`, `hwid`, o `email`, en minúsculas, un formato diferente al de los valores de enum JSON `identifierType` usados en el resto de esta página. Un solo tipo se aplica a todo el archivo. |
| `application_codes` | Sí | Códigos de aplicación separados por comas. |
| `dry_run` | No | `true`/`false`. |
| `confirmation_dry_run_task_id` | No | Igual que `Create`. |

### Respuesta

```json
{
  "task_id": 123,
  "identifier_count": 480,
  "duplicate_count": 3,
  "skipped_rows": 1
}
```

## ListTasks

Lista las eliminaciones de la cuenta, las más recientes primero: el diario de auditoría de quién eliminó qué y cuándo. Los dry runs se excluyen a menos que se configure `includeDryRuns`.

`GET` `/api/data_erasure/tasks`

### Parámetros de consulta

| Parámetro | Tipo | Descripción |
| :---- | :---- | :---- |
| `limit` / `offset` | integer | Paginación. |
| `includeDryRuns` | boolean | Incluir tareas dry-run (solo de medición). |
| `from` / `to` | string (RFC 3339) | Mantener las tareas iniciadas en `[from, to)`. |
| `applicationCode` | string | Mantener las tareas que cubren esta aplicación. |
| `initiatorUserId` | integer | Mantener las tareas iniciadas por este usuario del Panel de Control. `0` (predeterminado) mantiene todos los iniciadores. |
| `initiatorTokenId` | integer | Mantener las tareas iniciadas por este token de API. `0` (predeterminado) mantiene todos los iniciadores. |
| `initiatorEmail` | string | Mantener las tareas iniciadas por este usuario del Panel de Control, comparado por email, sin distinguir mayúsculas y minúsculas. |

### Respuesta

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `tasks` | array de [objetos de tarea de eliminación de datos](#data-erasure-task-object) | Tareas coincidentes. |

## GetTask

Devuelve una tarea de eliminación con su estado y contadores. Úselo para seguir una tarea iniciada por [Create](#create) o [Upload](#upload).

`GET` `/api/data_erasure/tasks/{task_id}`

### Respuesta

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `task` | [objeto de tarea de eliminación de datos](#data-erasure-task-object) | La tarea solicitada. |

## ListTaskRows

Devuelve el resultado por identificador de una tarea: qué se eliminó, no se encontró, se omitió o falló. Los identificadores se informan como su hash sha256.

`GET` `/api/data_erasure/tasks/{task_id}/rows`

### Parámetros de consulta

| Parámetro | Tipo | Descripción |
| :---- | :---- | :---- |
| `limit` / `offset` | integer | Paginación. |

### Respuesta

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `rows` | array de [objetos de fila de tarea de eliminación de datos](#data-erasure-task-row-object) | Esta página de resultados. |

## GetTaskReport

Devuelve el informe completo de una tarea como un archivo CSV: una fila por identificador por aplicación, con su resultado. [ListTaskRows](#listtaskrows) muestra las mismas filas página por página en su lugar.

`GET` `/api/data_erasure/tasks/{task_id}/report`

### Respuesta

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `filename` | string | Nombre de archivo sugerido, por ejemplo `data-erasure-task-42.csv`. |
| `content_type` | string | `text/csv`. |
| `content` | string (base64) | El archivo CSV. Columnas: `task_id`, `created`, `identifier_type`, `identifier_hash`, `application_code`, `result`, `detail`. |

## GetJournalReport

Devuelve todas las eliminaciones de un período como un único archivo CSV: una fila por identificador por aplicación, con la tarea y su iniciador en cada fila. Esto es lo que una cuenta entrega a un auditor.

`GET` `/api/data_erasure/report`

### Parámetros de consulta

| Parámetro | Tipo | Requerido | Descripción |
| :---- | :---- | :---- | :---- |
| `from` | string (RFC 3339) | Sí | Inicio del período. |
| `to` | string (RFC 3339) | No | Fin del período. El valor predeterminado es ahora. |
| `includeDryRuns` | boolean | No | Incluir tareas dry-run. |

<Aside type="caution">
Un período con más de 2,000 tareas de eliminación se rechaza en lugar de recortarse. Reduzca el período y llame de nuevo.
</Aside>

### Respuesta

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `filename` | string | Nombre de archivo sugerido, por ejemplo `data-erasure-2026-01-01-2026-04-01.csv`. |
| `content_type` | string | `text/csv`. |
| `content` | string (base64) | El archivo CSV. Columnas: `task_id`, `task_created`, `initiator_user_id`, `initiator_email`, `initiator_token_id`, `dry_run`, `identifier_type`, `identifier_hash`, `application_code`, `result`, `detail`, `row_created`. |

<span id="data-erasure-task-object" />

## Objeto de tarea de eliminación de datos

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `task_id` | integer | Id de la tarea. |
| `identifier_type` | string | `SUBJECT_IDENTIFIER_USER_ID`, `SUBJECT_IDENTIFIER_HWID`, o `SUBJECT_IDENTIFIER_EMAIL`. |
| `application_codes` | array de strings | Aplicaciones que cubre la tarea. |
| `dry_run` | boolean | Si esta tarea solo midió un volumen. |
| `status` | string | `ERASURE_TASK_STATUS_PENDING`, `_IN_PROGRESS`, `_DONE`, o `_FAILED`. |
| `total_count` | integer | Identificadores × aplicaciones que cubre esta tarea. |
| `deleted_count` | integer | Cuántos se eliminaron (o, para un dry run, se eliminarían). |
| `not_found_count` | integer | Cuántos no coincidieron con nada. |
| `failed_count` | integer | Cuántos fallaron. Consulte [ListTaskRows](#listtaskrows) o el informe para saber por qué. |
| `fail_reason` | string | Se establece cuando `status` es `ERASURE_TASK_STATUS_FAILED`. |
| `initiator_user_id` | integer | Usuario del Panel de Control que inició la tarea. `0` cuando lo hizo un token de API. |
| `initiator_token_id` | integer | Token de API que inició la tarea. `0` cuando lo hizo un usuario del Panel de Control. |
| `initiator_email` | string | Dirección del usuario del Panel de Control que inició la tarea. Vacío para un token de API. |
| `created` | string (RFC 3339) | Cuándo se creó la tarea. |
| `started_at` | string (RFC 3339) | Cuándo comenzó el trabajo de eliminación. |
| `finished_at` | string (RFC 3339) | Cuándo la tarea alcanzó un estado final. |

<span id="data-erasure-task-row-object" />

## Objeto de fila de tarea de eliminación de datos

| Campo | Tipo | Descripción |
| :---- | :---- | :---- |
| `identifier_hash` | string | sha256 del identificador. El informe nunca almacena ni devuelve el identificador en sí. |
| `application_code` | string | Aplicación a la que se aplica el resultado de esta fila. |
| `result` | string | `ERASURE_ROW_RESULT_DELETED`, `_NOT_FOUND`, `_SKIPPED`, o `_FAILED`. |
| `detail` | string | Detalle técnico, se establece principalmente en caso de fallo. |
| `created` | string (RFC 3339) | Cuándo se escribió esta fila. |

## Relacionado

<CardGrid>
  <LinkCard title="Solicitudes de datos (guía de producto)" href="/product/account-management-and-security/data-requests/" />
  <LinkCard title="Borrar datos personales desde User Explorer" href="/product/audience-data-and-segmentation/user-explorer/#erase-personal-data" />
</CardGrid>