# Cancelar

`POST` `https://api.pushwoosh.com/messaging/v2/cancel`

Cancela un mensaje creado previamente, identificado por su `message_code`. La cancelación solo está disponible mientras el mensaje se encuentre en uno de estos estados:

- **pending:** creado pero aún no recogido para su envío.
- **waiting:** programado para una hora de envío futura.
- **processing:** actualmente en preparación para su entrega.

<Aside type="caution" title="Importante">

- Si el mensaje está en estado de `processing`, la cancelación solo detiene las entregas que aún no se han realizado. Cualquiera que ya haya recibido el mensaje aún puede tenerlo.

- Si el mensaje ya fue cancelado o ha terminado de enviarse, la API devuelve un `400`. Esta llamada no es idempotente. Comprueba el estado del mensaje antes de reintentar.
</Aside>

Para comprobar si un mensaje todavía está en un estado cancelable, consulta [Comprobando el estado del mensaje](#checking-message-status).


## Solicitud

Autentícate con tu [token de API del servidor](/es/developer/api-reference/api-access-token/#server-api-token) en el encabezado `Authorization: Token <API_TOKEN>`.

| Campo | Tipo | Requerido | Descripción |
|---|---|---|---|
| `message_code` | string | Sí | [Código de mensaje](/es/developer/api-reference/api-identifiers/#message-code) del mensaje a cancelar, tal como lo devuelve [`Notify`](/es/developer/api-reference/messaging-api-v2/notify/) en `result.message_code`. |

### Solicitud de ejemplo

```bash
curl -X POST https://api.pushwoosh.com/messaging/v2/cancel \
  -H "Authorization: Token YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "message_code": "XXXX-XXXXXXXX-XXXXXXXX"
  }'
```

## Respuesta

En caso de éxito, devuelve un HTTP 200 con un cuerpo JSON vacío.

```json
{}
```

## Errores

Los errores utilizan el sobre de error estándar de gRPC-Gateway: `{ "code": ..., "message": ..., "details": [...] }`.

| Estado HTTP | Condición |
|---|---|
| `400` | Falta el `message_code`. |
| `400` | El mensaje no está en un estado cancelable (ya no está `pending`, `waiting` o `processing`). |
| `403` | El mensaje pertenece a otra cuenta. |
| `404` | No existe ningún mensaje para el `message_code` proporcionado. |
| `500` | Ocurrió un error interno al cargar el mensaje o publicar la cancelación. Reintenta la solicitud. |


**Ejemplo**

Cancelar un mensaje que ya no existe devuelve un HTTP `404`:

```json
{
  "code": 5,
  "message": "message not found",
  "details": []
}
```

## Comprobando el estado del mensaje

Antes de cancelar, puedes verificar si un mensaje todavía está en un estado cancelable. Además de leer la columna **Estado** en la tabla de mensajes en el Panel de Control ([**Campañas → Mensajes únicos**](/es/product/statistics-and-analytics/message-history/)), puedes consultar el estado programáticamente con [`messages:list`](/es/developer/api-reference/statistics-api/message-statistics-api/#messageslist):

- Pasa el `message_code` en el array `filters.messages_codes` (junto con el `filters.application` requerido).
- Lee el campo `status` de la entrada correspondiente en `items[]`.

<Aside type="note">
`messages:list` es parte de la API de Estadísticas y utiliza un encabezado de autenticación diferente al de este endpoint: `Authorization: Api <Server Key>`.
</Aside>

## Relacionado

<CardGrid>
  <LinkCard title="Notify" href="/developer/api-reference/messaging-api-v2/notify/" />
  <LinkCard title="Update" href="/developer/api-reference/messaging-api-v2/update/" />
  <LinkCard title="Estadísticas de mensajes" href="/developer/api-reference/statistics-api/message-statistics-api/#messageslist" />
  <LinkCard title="Resumen de la API de Mensajería v2" href="/developer/api-reference/messaging-api-v2/" />
  <LinkCard title="Migración desde v1" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>