# Cancelar

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

Cancela uma mensagem criada anteriormente, identificada pelo seu `message_code`. O cancelamento está disponível apenas enquanto a mensagem estiver em um destes estados:

- **pending:** criada, mas ainda não recolhida para envio.
- **waiting:** agendada para um horário de envio futuro.
- **processing:** atualmente sendo preparada para entrega.

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

- Se a mensagem estiver em `processing`, o cancelamento interrompe apenas as entregas que ainda não foram enviadas. Qualquer pessoa que já tenha recebido a mensagem ainda pode tê-la.

- Se a mensagem já foi cancelada ou terminou de ser enviada, a API retorna `400`. Esta chamada não é idempotente. Verifique o estado da mensagem antes de tentar novamente.
</Aside>

Para verificar se uma mensagem ainda está em um estado cancelável, consulte [Verificando o estado da mensagem](#verificando-o-estado-da-mensagem).


## Requisição

Autentique-se com seu [token de API do Servidor](/pt/developer/api-reference/api-access-token/#server-api-token) no cabeçalho `Authorization: Token <API_TOKEN>`.

| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
| `message_code` | string | Sim | [Código da mensagem](/pt/developer/api-reference/api-identifiers/#message-code) da mensagem a ser cancelada, conforme retornado por [`Notify`](/pt/developer/api-reference/messaging-api-v2/notify/) em `result.message_code`. |

### Exemplo de requisição

```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"
  }'
```

## Resposta

Em caso de sucesso, retorna HTTP 200 com um corpo JSON vazio.

```json
{}
```

## Erros

Os erros usam o envelope de erro padrão do gRPC-Gateway: `{ "code": ..., "message": ..., "details": [...] }`.

| Status HTTP | Condição |
|---|---|
| `400` | O `message_code` está ausente. |
| `400` | A mensagem não está em um estado cancelável (não está mais `pending`, `waiting` ou `processing`). |
| `403` | A mensagem pertence a outra conta. |
| `404` | Nenhuma mensagem existe para o `message_code` fornecido. |
| `500` | Ocorreu um erro interno ao carregar a mensagem ou publicar o cancelamento. Tente a requisição novamente. |


**Exemplo**

Cancelar uma mensagem que não existe mais retorna HTTP `404`:

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

## Verificando o estado da mensagem

Antes de cancelar, você pode verificar se uma mensagem ainda está em um estado cancelável. Além de ler a coluna **Status** na tabela de mensagens no Painel de Controle ([**Campanhas → Mensagens únicas**](/pt/product/statistics-and-analytics/message-history/)), você pode consultar o estado programaticamente com [`messages:list`](/pt/developer/api-reference/statistics-api/message-statistics-api/#messageslist):

- Passe o `message_code` no array `filters.messages_codes` (juntamente com o `filters.application` obrigatório).
- Leia o campo `status` da entrada correspondente em `items[]`.

<Aside type="note">
`messages:list` faz parte da API de Estatísticas e usa um cabeçalho de autenticação diferente deste endpoint: `Authorization: Api <Server Key>`.
</Aside>

## Relacionados

<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="Estatísticas de mensagens" href="/developer/api-reference/statistics-api/message-statistics-api/#messageslist" />
  <LinkCard title="Visão geral da API de Mensagens v2" href="/developer/api-reference/messaging-api-v2/" />
  <LinkCard title="Migração da v1" href="/developer/api-reference/messaging-api-v2/migration-from-v1/" />
</CardGrid>