Cancelando um Boleto

Cancelando um Boleto

O cancelamento de um boleto na API do Pagou permite invalidar um boleto ativo, alterando seu status para StatusCanceled e tornando-o não mais válido para pagamento.

Visão Geral Técnica

O endpoint DELETE /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 StatusCanceled. Apenas boletos no status StatusActive (ou, em casos raros, StatusEmpty) podem ser cancelados. Boletos em StatusPaid, StatusRefunded ou já em StatusCanceled 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 StatusActive ou, em casos raros, StatusEmpty. Boletos em outros status (ex.: StatusPaid) resultarão em erro 400.

Resposta

• Status: 204 No Content

• Corpo: (Vazio, conforme padrão para 204).

Exemplo de Resposta:

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 GET /v1/charges/{id} para confirmar o status StatusCanceled (veja Consultando um Boleto).

• Webhooks: O cancelamento não gera notificações via webhook.

Exemplos de Código

cURL

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"

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));

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()}")

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 [email protected].

Exemplo de Resposta de Erro:

{
  "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 GET /v1/charges/{id} para confirmar se o boleto está em StatusActive 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 GET /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.