Consultando um Boleto

Consultando um Boleto

A consulta de um boleto na API do Pagou permite recuperar detalhes de um boleto existente, como status, valor, código de barras e data de pagamento, usando seu ID único.

Visão Geral Técnica

O endpoint GET /v1/charges/{id} retorna os detalhes completos de um boleto, incluindo informações do pagador, multas, juros, descontos e status. A operação é síncrona e ideal para verificar o estado de um boleto sem depender de webhooks, embora o uso de webhooks (ex.: evento ChargePaid) seja recomendado para atualizações automáticas.

GET /v1/charges/{id}

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	Identifica sua aplicação (ex.: MinhaLoja/1.0).

Parâmetros da URL

Parâmetro	Tipo	Obrigatório	Descrição
id	string	Sim	ID único do boleto (ex.: 8325a4b3-579c-45df-b475-0ce57df2478d).

Validações:

• id: Deve ser um ID válido retornado pelo endpoint de criação (POST /v1/charges).

Resposta

• Status: 200 OK

• Corpo: JSON com os detalhes do boleto.

Exemplo de Resposta:

{
  "id": "8325a4b3-579c-45df-b475-0ce57df2478d",
  "status": 2,
  "due_date": "2024-12-31",
  "grace_period": 15,
  "amount": 100.50,
  "description": "Payment for services rendered",
  "metadata": [
    {
      "key": "order_id",
      "value": "ORD-2024-001"
    },
    {
      "key": "reference",
      "value": "REF-12345"
    }
  ],
  "payer": {
    "name": "João Silva",
    "document": "12345678901",
    "zip": "01234567",
    "street": "Rua das Flores",
    "city": "São Paulo",
    "state": "SP",
    "number": "123",
    "neighborhood": "Centro"
  },
  "fine": 2.5,
  "interest": 1.0,
  "discount": {
    "type": "fixed",
    "amount": 10.00,
    "limit_date": "2024-12-25"
  },
  "notification_url": "https://your-webhook.com/notifications",
  "customer_code": "CUST-001",
  "created_at": "2025-07-23T09:30:00-03:00",
  "paid_at": null
}

Campos da Resposta:

Campo	Tipo	Descrição
id	string	ID único do boleto (ex.: 8325a4b3-579c-45df-b475-0ce57df2478d).
status	number	Status do boleto (1, 2, 3, 4, 5).
due_date	string	Data de vencimento (formato YYYY-MM-DD).
grace_period	number	Dias de tolerância após o vencimento (ex.: 15).
amount	number	Valor do boleto em reais (ex.: 100.50 para R$ 100,50).
description	string	Descrição do boleto (máx. 255 caracteres).
metadata	array	Pares chave-valor para dados adicionais (ex.: ID do pedido).
metadata[].key	string	Chave do metadado (ex.: order_id).
metadata[].value	string	Valor do metadado (ex.: ORD-2024-001).
payer	object	Dados do pagador.
payer.name	string	Nome completo do pagador (máx. 100 caracteres).
payer.document	string	CPF (11 dígitos) ou CNPJ (14 dígitos).
payer.zip	string	CEP (8 dígitos, sem hífen).
payer.street	string	Rua ou avenida (máx. 200 caracteres).
payer.city	string	Cidade (máx. 100 caracteres).
payer.state	string	UF (2 letras, ex.: SP).
payer.number	string	Número do endereço (máx. 20 caracteres).
payer.neighborhood	string	Bairro (máx. 100 caracteres).
fine	number	Multa por atraso em percentual (ex.: 2.5 para 2,5%).
interest	number	Juros por dia de atraso em percentual (ex.: 1.0 para 1%).
discount	object	Desconto para pagamento antecipado.
discount.type	string	Tipo de desconto (fixed ou percentage).
discount.amount	number	Valor do desconto (em reais para fixed, ou percentual para percentage).
discount.limit_date	string	Data limite para o desconto (formato YYYY-MM-DD).
notification_url	string	URL HTTPS para webhooks (ex.: https://your-webhook.com/notifications).
customer_code	string	Código interno do cliente (máx. 50 caracteres).
created_at	string	Data de criação do boleto (ISO 8601).
paid_at	string	Data de pagamento do boleto (ISO 8601, ou null se não pago).

Exemplos de Código

cURL

curl -X GET https://sandbox.api.pagou.com.br/v1/charges/8325a4b3-579c-45df-b475-0ce57df2478d \
  -H "X-API-KEY: sua_chave_api" \
  -H "Content-Type: application/json" \
  -H "User-Agent: MinhaLoja/1.0"

Javascript

const fetch = require('node-fetch');
const { validate } = require('jsonschema');

// Esquema de validação da resposta
const schema = {
    type: 'object',
    required: ['id', 'status', 'due_date', 'amount', 'description', 'payer'],
    properties: {
        id: { type: 'string' },
        status: { type: 'number', enum: [1, 2, 3, 4, 5] },
        due_date: { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}$' },
        grace_period: { type: 'integer', minimum: 0 },
        amount: { type: 'number', minimum: 1.00 },
        description: { type: 'string', maxLength: 255 },
        metadata: {
            type: 'array',
            items: {
                type: 'object',
                required: ['key', 'value'],
                properties: {
                    key: { type: 'string' },
                    value: { type: 'string' }
                }
            }
        },
        payer: {
            type: 'object',
            required: ['name', 'document', 'zip', 'street', 'city', 'state', 'number', 'neighborhood'],
            properties: {
                name: { type: 'string', maxLength: 100 },
                document: { type: 'string', pattern: '^\\d{11}|\\d{14}$' },
                zip: { type: 'string', pattern: '^\\d{8}$' },
                street: { type: 'string', maxLength: 200 },
                city: { type: 'string', maxLength: 100 },
                state: { type: 'string', pattern: '^[A-Z]{2}$' },
                number: { type: 'string', maxLength: 20 },
                neighborhood: { type: 'string', maxLength: 100 }
            }
        },
        fine: { type: 'number', minimum: 0, maximum: 100 },
        interest: { type: 'number', minimum: 0, maximum: 100 },
        discount: {
            type: 'object',
            required: ['type', 'amount', 'limit_date'],
            properties: {
                type: { type: 'string', enum: ['fixed', 'percentage'] },
                amount: { type: 'number', minimum: 0 },
                limit_date: { type: 'string', pattern: '^\\d{4}-\\d{2}-\\d{2}$' }
            }
        },
        notification_url: { type: 'string', format: 'uri' },
        customer_code: { type: 'string', maxLength: 50 },
        barcode: { type: 'string' },
        pdf_url: { type: 'string', format: 'uri' },
        created_at: { type: 'string', format: 'date-time' },
        paid_at: { type: ['string', 'null'], format: 'date-time' }
    }
};

// Consultar boleto
const boletoId = '8325a4b3-579c-45df-b475-0ce57df2478d';
fetch(`https://sandbox.api.pagou.com.br/v1/charges/${boletoId}`, {
    method: 'GET',
    headers: {
        'X-API-KEY': 'sua_chave_api',
        'Content-Type': 'application/json',
        'User-Agent': 'MinhaLoja/1.0'
    }
})
    .then(response => {
        if (!response.ok) {
            throw new Error(`Erro ${response.status}: ${response.statusText}`);
        }
        return response.json();
    })
    .then(data => {
        // Validar resposta
        const validation = validate(data, schema);
        if (!validation.valid) {
            throw new Error(`Erro de validação: ${validation.errors}`);
        }
        
        console.log(`Boleto ID: ${data.id}`);
        console.log(`Status: ${data.status}`);
    })
    .catch(error => console.error('Erro na requisição:', error));

Python

import requests
from jsonschema import validate, ValidationError

# Esquema de validação da resposta
schema = {
    "type": "object",
    "required": ["id", "status", "due_date", "amount", "description", "payer"],
    "properties": {
        "id": {"type": "string"},
        "status": {"type": "number", "enum": [1, 2, 3, 4, 5]},
        "due_date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"},
        "grace_period": {"type": "integer", "minimum": 1},
        "amount": {"type": "number", "minimum": 1.00},
        "description": {"type": "string", "maxLength": 255},
        "metadata": {
            "type": "array",
            "items": {
                "type": "object",
                "required": ["key", "value"],
                "properties": {
                    "key": {"type": "string"},
                    "value": {"type": "string"}
                }
            }
        },
        "payer": {
            "type": "object",
            "required": ["name", "document", "zip", "street", "city", "state", "number", "neighborhood"],
            "properties": {
                "name": {"type": "string", "maxLength": 100},
                "document": {"type": "string", "pattern": "^\\d{11}|\\d{14}$"},
                "zip": {"type": "string", "pattern": "^\\d{8}$"},
                "street": {"type": "string", "maxLength": 200},
                "city": {"type": "string", "maxLength": 100},
                "state": {"type": "string", "pattern": "^[A-Z]{2}$"},
                "number": {"type": "string", "maxLength": 20},
                "neighborhood": {"type": "string", "maxLength": 100}
            }
        },
        "fine": {"type": "number", "minimum": 0, "maximum": 100},
        "interest": {"type": "number", "minimum": 0, "maximum": 100},
        "discount": {
            "type": "object",
            "required": ["type", "amount", "limit_date"],
            "properties": {
                "type": {"type": "string", "enum": ["fixed", "percentage"]},
                "amount": {"type": "number", "minimum": 0},
                "limit_date": {"type": "string", "pattern": "^\\d{4}-\\d{2}-\\d{2}$"}
            }
        },
        "notification_url": {"type": "string", "format": "uri"},
        "customer_code": {"type": "string", "maxLength": 50},
        "barcode": {"type": "string"},
        "pdf_url": {"type": "string", "format": "uri"},
        "created_at": {"type": "string", "format": "date-time"},
        "paid_at": {"type": ["string", "null"], "format": "date-time"}
    }
}

# Consultar boleto
boleto_id = "8325a4b3-579c-45df-b475-0ce57df2478d"
url = f"https://sandbox.api.pagou.com.br/v1/charges/{boleto_id}"
headers = {
    "X-API-KEY": "sua_chave_api",
    "Content-Type": "application/json",
    "User-Agent": "MinhaLoja/1.0"
}

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()
    data = response.json()
    
    # Validar resposta
    try:
        validate(instance=data, schema=schema)
    except ValidationError as e:
        print(f"Erro de validação na resposta: {e}")
        exit(1)
    
    print(f"Boleto ID: {data['id']}")
    print(f"Status: {data['status']}")
except requests.RequestException as e:
    print(f"Erro na requisição: {e}")

Tratamento de Erros

Código HTTP	Descrição	Possível Causa	Solução
400	Bad Request	ID do boleto malformado.	Verificar formato do id.
401	Unauthorized	X-API-KEY inválido ou ausente.	Verificar chave..
404	Not Found	Boleto não existe.	Confirmar ID do boleto.
429	Too Many Requests	Limite de requisições excedido.	Implementar rate limiting e retentativas.
500	Internal Server Error	Erro interno da API.	Tentar novamente e contatar suporte.

Exemplo de Resposta de Erro:

{
  "error": "Boleto not found"
}

Boas Práticas Técnicas

• Segurança: Armazene X-API-KEY em variáveis de ambiente e use HTTPS para todas as requisições.

• Webhooks como Alternativa: Para atualizações em tempo real, configure o evento ChargePaid em vez de consultas frequentes. Veja Webhooks para Interações com Boleto.

• Testes no Sandbox: Use https://sandbox.api.pagou.com.br/v1/charges/{id} para simular consultas sem custos reais.

• Monitoramento: Registre todas as requisições e respostas em logs, incluindo id, status e paid_at, para auditoria e depuração.

• Cache: Considere armazenar respostas em cache (ex.: Redis, com TTL de 5 minutos) para reduzir chamadas à API em sistemas de alto tráfego.

Get a Charge

get

This endpoint return a charge.

Authorizations

Path parameters

chargeIDanyRequired

Charge ID

Header parameters

User-AgentanyOptional

Client Identifier

Responses

200

OK

application/json

Responsestring

400

Bad Request

application/json

401

Unauthorized

application/json

404

Not Found

application/json

500

Internal Server Error

application/json

get

HTTPcURLJavaScriptPython

GET /v1/charges/{chargeID} HTTP/1.1
Host: sandbox-api.pagou.com.br
X-API-KEY: YOUR_API_KEY
Accept: */*

text