# Cancelando um Boleto

## Cancelando um Boleto

O cancelamento de um boleto na API do Pagou permite invalidar um boleto ativo, alterando seu status para <mark style="color:red;background-color:red;">`StatusCanceled`</mark> e tornando-o não mais válido para pagamento.

### Visão Geral Técnica

O endpoint <mark style="color:red;">`DELETE`</mark>` ``/v1/charges/{chargeID}` solicita o cancelamento de um boleto identificado por seu ID único. A operação é síncrona, retornando `204 No Content` em caso de sucesso, indicando que o boleto foi cancelado e seu status atualizado para <mark style="color:red;">`StatusCanceled`</mark>. Apenas boletos no status <mark style="color:red;">`StatusActive`</mark> (ou, em casos raros, <mark style="color:red;">`StatusEmpty`</mark>) podem ser cancelados. Boletos em <mark style="color:red;">`StatusPaid`</mark>, <mark style="color:red;">`StatusRefunded`</mark> ou já em <mark style="color:red;background-color:red;">`StatusCanceled`</mark> não podem ser cancelados novamente.

**Especificações**:

* **Método**: DELETE
* **URL**:
  * Produção: <https://api.pagou.com.br/v1/charges/{id}>
  * Sandbox: <https://sandbox.api.pagou.com.br/v1/charges/{id}>
* **Autenticação**: Cabeçalho X-API-KEY com chave do painel.
* **Content-Type**: application/json
* **Resposta**: Status 204 No Content (sem corpo).
* **Erros**: 400 Bad Request, 401 Unauthorized, 500 Internal Server Error.

### Pré-requisitos

* **Conta no Pagou**: Acesse <https://pagou.com.br> e crie uma conta.
* **Chave de API**: Obtenha a chave em *Configurações > API* (diferentes para sandbox e produção).
* **ID do boleto**: Use o UUID retornado no header Location ao criar o boleto (ex.: 550e8400-e29b-41d4-a716-446655440000).
* **Ferramentas**: Use cURL, Postman ou bibliotecas HTTP (ex.: requests em Python, fetch em JavaScript).

### Endpoint

* **Método**: DELETE
* **URL**: <https://api.pagou.com.br/v1/charges/{id}> (produção) ou <https://sandbox.api.pagou.com.br/v1/charges/{id}> (sandbox)

### Cabeçalhos

| Cabeçalho    | Valor                  | Descrição                                                    |
| ------------ | ---------------------- | ------------------------------------------------------------ |
| X-API-KEY    | sua\_chave\_api        | Chave de autenticação (encontrada em *Configurações > API*). |
| Content-Type | application/json       | Formato JSON para a requisição.                              |
| User-Agent   | NomeDaSuaAplicacao/1.0 | Identificador da aplicação (ex.: MinhaLoja/1.0, opcional).   |

### Parâmetros da URL

| Parâmetro | Tipo   | Obrigatório | Descrição                                                                       |
| --------- | ------ | ----------- | ------------------------------------------------------------------------------- |
| `id`      | string | Sim         | ID único do boleto no formato UUID (ex.: 550e8400-e29b-41d4-a716-446655440000). |

**Validações**:

* id: Deve ser um UUID válido (ex.: 550e8400-e29b-41d4-a716-446655440000).
* O boleto deve estar em <mark style="color:red;">StatusActive</mark> ou, em casos raros, <mark style="color:red;">`StatusEmpty`</mark>. Boletos em outros status (ex.: <mark style="color:red;">StatusPaid</mark>) resultarão em erro 400.

### Resposta

* **Status**: 204 No Content
* **Corpo**: (Vazio, conforme padrão para 204).

**Exemplo de Resposta**:

```bash
HTTP/1.1 204 No Content
Content-Length: 0
```

### Mapa de Status e Cancelamento

O cancelamento altera o status do boleto para StatusCanceled. Abaixo está o contexto dos status, conforme definido na API do Pagou:

| Status           | Valor Numérico | Descrição                                                                                |
| ---------------- | -------------- | ---------------------------------------------------------------------------------------- |
| `StatusEmpty`    | 1              | Estado inicial transitório, indicando que o boleto foi criado, mas ainda não está ativo. |
| `StatusActive`   | 2              | Boleto ativo, pronto para pagamento, com código de barras e PDF disponíveis.             |
| `StatusCanceled` | 3              | Boleto cancelado, não mais válido para pagamento.                                        |
| `StatusPaid`     | 4              | Boleto pago pelo cliente, com liquidação confirmada.                                     |
| `StatusRefunded` | 5              | Boleto pago, mas reembolsado ao cliente.                                                 |

**Impacto do Cancelamento**:

* **Condição**: Apenas boletos em StatusActive (ou, raramente, StatusEmpty) podem ser cancelados.
* **Resultado**: O boleto transita para StatusCanceled, tornando-o inválido para pagamento.
* **Verificação**: Após o cancelamento, use <mark style="color:purple;">`GET`</mark>` ``/v1/charges/{id}` para confirmar o status <mark style="color:red;">StatusCanceled</mark> (veja Consultando um Boleto).
* **Webhooks**: O cancelamento não gera notificações via webhook.

### Exemplos de Código

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X DELETE https://sandbox.api.pagou.com.br/v1/charges/550e8400-e29b-41d4-a716-446655440000 \
  -H "X-API-KEY: sua_chave_api" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MinhaLoja/1.0"
```

{% endtab %}

{% tab title="JavaScript" %}

```javascript
const fetch = require('node-fetch');

// Configuração
const chargeId = '550e8400-e29b-41d4-a716-446655440000';
const url = `https://sandbox.api.pagou.com.br/v1/charges/${chargeId}`;
const headers = {
    'X-API-KEY': 'sua_chave_api',
    'Content-Type': 'application/json',
    'User-Agent': 'MinhaLoja/1.0'
};

fetch(url, {
    method: 'DELETE',
    headers: headers
})
    .then(response => {
        if (!response.ok) {
            return response.json().then(err => { throw new Error(`Erro ${response.status}: ${err.error.message}`); });
        }
        console.log(`Status: ${response.status} - Boleto ${chargeId} cancelado com sucesso`);
    })
    .catch(error => console.error('Erro na requisição:', error));
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import re

# Configuração
charge_id = "550e8400-e29b-41d4-a716-446655440000"
url = "https://sandbox.api.pagou.com.br/v1/charges/{charge_id}"
headers = {
    "X-API-KEY": "sua_chave_api",
    "Content-Type": "application/json",
    "User-Agent": "MinhaLoja/1.0"
}

try:
    response = requests.delete(url, headers=headers)
    response.raise_for_status()
    print(f"Status: {response.status_code} - Boleto {charge_id} cancelado com sucesso")
except requests.RequestException as e:
    print(f"Erro na requisição: {e}")
    if e.response:
        print(f"Detalhes: {e.response.json()}")
```

{% endtab %}
{% endtabs %}

### Tratamento de Erros

| Código HTTP | Descrição             | Possível Causa                                                              | Solução                                                    |
| ----------- | --------------------- | --------------------------------------------------------------------------- | ---------------------------------------------------------- |
| 400         | Bad Request           | id não é um UUID válido ou boleto não está em `StatusActive`/`StatusEmpty`. | Verificar formato do id e status via GET /v1/charges/{id}. |
| 401         | Unauthorized          | `X-API-KEY` inválido ou ausente.                                            | Verificar chave.                                           |
| 500         | Internal Server Error | Erro interno da API.                                                        | Tentar novamente e contatar <suporte@pagou.com.br>.        |

**Exemplo de Resposta de Erro**:

```json
{
  "error": "Charge is not in a cancellable state"
}
```

### Boas Práticas Técnicas

* **Validação de Dados**: Valide o id como UUID (formato 8-4-4-4-12) antes de enviar a requisição. Use <mark style="color:purple;">`GET`</mark>` ``/v1/charges/{id}` para confirmar se o boleto está em <mark style="color:red;">`StatusActive`</mark> antes de cancelar.
* **Segurança**: Armazene `X-API-KEY` em variáveis de ambiente e use HTTPS para todas as requisições.
* **Verificação Pós-Cancelamento**: Após o cancelamento, consulte o boleto com <mark style="color:purple;">`GET`</mark>` ``/v1/charges/{id}` para confirmar o status StatusCanceled.
* **Testes no Sandbox**: Use `https://sandbox.api.pagou.com.br/v1/charges/{id}` para simular cancelamentos sem impacto em produção.
* **Monitoramento**: Registre todas as requisições e respostas (incluindo id e status HTTP) em logs para auditoria e depuração.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.pagou.com.br/integracao-com-a-api/meio-de-pagamento-boleto/cancelando-um-boleto.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.