Criando um Boleto
A criação de boletos na API do Pagou permite gerar boletos para pagamento, com detalhes do cliente, cedente, e URLs para visualização em PDF ou HTML. Esta seção detalha o endpoint POST /v1/charges, o payload, a geração de URLs para visualização, autenticação, validação, exemplos de código, tratamento de erros, e boas práticas para criar boletos de forma robusta e segura.
Visão Geral Técnica
O endpoint POST /v1/charges cria um boleto, retornando um ID único e informações básicas na resposta síncrona. Detalhes como código de barras, linha digitável, e informações bancárias são enviados posteriormente pelo webhook charge.created (veja Webhooks para Interações com Boletos) após o registro do boleto. Após a criação, o boleto pode ser visualizado em PDF (https://fatura.pagou.com.br/boleto/pdf/{id}) ou HTML (https://fatura.pagou.com.br/boleto/{id}), mas essas URLs podem não estar disponíveis imediatamente até o registro ser concluído.
Especificações:
Método:
POSTURL:
Produção:
https://api.pagou.com.br/v1/chargesSandbox:
https://sandbox.api.pagou.com.br/v1/charges
Autenticação: Cabeçalho
X-API-KEYcom chave do painel.Content-Type:
application/jsonResposta:
Status 201Created com corpo JSON contendo o ID do boleto e detalhes.Erros:
400 Bad Request,401 Unauthorized,500 Internal Server Error.
Headers
Content-Type
application/json
Formato JSON para o corpo da requisição.
X-API-KEY
<token>
Chave de autenticação do painel.
User-Agent
NomeDaSuaAplicacao/1.0
Identificador da aplicação.
Corpo da Requisição
O payload deve conter informações do boleto, cliente, multas, juros, descontos e configurações de notificação.
{
"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"
}Campos do Payload:
Campo
Tipo
Obrigatório
Descrição
due_date
string
Sim
Data de vencimento (formato YYYY-MM-DD).
grace_period
number
Sim
Dias de tolerância após o vencimento (ex.: 15 dias).
amount
number
Sim
Valor do boleto em reais (ex.: 100.50 para R$ 100,50).
description
string
Sim
Descrição do boleto (máx. 255 caracteres).
metadata
array
Não
Pares chave-valor para dados adicionais (ex.: ID do pedido).
metadata[].key
string
Sim (se usado)
Chave do metadado (ex.: order_id).
metadata[].value
string
Sim (se usado)
Valor do metadado (ex.: ORD-2024-001).
payer
object
Sim
Dados do pagador.
payer.name
string
Sim
Nome completo do pagador (máx. 100 caracteres).
payer.document
string
Sim
CPF (11 dígitos) ou CNPJ (14 dígitos).
payer.zip
string
Sim
CEP (8 dígitos, sem hífen).
payer.street
string
Sim
Rua ou avenida (máx. 200 caracteres).
payer.city
string
Sim
Cidade (máx. 100 caracteres).
payer.state
string
Sim
UF (2 letras, ex.: SP).
payer.number
string
Sim
Número do endereço (máx. 20 caracteres).
payer.neighborhood
string
Sim
Bairro (máx. 100 caracteres).
fine
number
Não
Multa por atraso em percentual (ex.: 2.5 para 2,5%).
interest
number
Não
Juros por dia de atraso em percentual (ex.: 1.0 para 1%).
discount
object
Não
Desconto para pagamento antecipado.
discount.type
string
Sim (se usado)
Tipo de desconto (fixed ou percentage).
discount.amount
number
Sim (se usado)
Valor do desconto (em reais para fixed, ou percentual para percentage).
discount.limit_date
string
Sim (se usado)
Data limite para o desconto (formato YYYY-MM-DD).
notification_url
string
Não
URL HTTPS para webhooks (ex.: https://your-webhook.com/notifications).
customer_code
string
Não
Código interno do cliente (máx. 50 caracteres).
Validações:
due_date: Deve ser uma data futura (mín. 1 dia).grace_period: Deve ser maior do que 0 e menor igual a 30.amount: Valor mínimo de 5.00 (R$ 5,00).payer.document: Deve ser um CPF (11 dígitos) ou CNPJ (14 dígitos) válido.payer.zip: Deve ser um CEP válido (8 dígitos).discount.limit_date: Deve ser anterior ou igual a due_date.notification_url: Deve ser uma URL HTTPS válida.
Resposta
Status: 201 Created
Header: Location: /charges/{id}
Corpo: Contendo o ID do Boleto criado mais os dados.
Response
{
"id": "d1bfda17-3a56-433b-8825-7981f7374cee",
"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"
}{
"error": "Invalid request"
}Visualização do Boleto
Após a criação, o boleto pode ser visualizado em dois formatos:
PDF: Acesse
https://fatura.pagou.com.br/boleto/pdf/{id}(ex.: https://fatura.pagou.com.br/boleto/pdf/1b6f2a39-2403-4217-a2ce-7d20e6376cf5).HTML: Acesse
https://fatura.pagou.com.br/boleto/{id}(ex.: https://fatura.pagou.com.br/boleto/1b6f2a39-2403-4217-a2ce-7d20e6376cf5).
Nota: Substitua {id} pelo UUID retornado (id). As URLs podem não estar disponíveis imediatamente, pois dependem do registro do boleto. Aguarde o webhook charge.created para confirmar a disponibilidade do boleto.
Exemplos de Código
curl -X POST https://sandbox.api.pagou.com.br/v1/charges \
-H "X-API-KEY: sua_chave_api" \
-H "Content-Type: application/json" \
-H "User-Agent: MinhaLoja/1.0" \
-d '{
"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"
}'const fetch = require('node-fetch');
const { validate } = require('jsonschema');
// Esquema de validação do payload
const schema = {
type: 'object',
required: ['due_date', 'amount', 'description', 'payer'],
properties: {
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 }
}
};
// Payload
const payload = {
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'
};
// Validar payload
const validation = validate(payload, schema);
if (!validation.valid) {
console.error('Erro de validação:', validation.errors);
process.exit(1);
}
// Enviar requisição
fetch('https://sandbox.api.pagou.com.br/v1/charges', {
method: 'POST',
headers: {
'X-API-KEY': 'sua_chave_api',
'Content-Type': 'application/json',
'User-Agent': 'MinhaLoja/1.0'
},
body: JSON.stringify(payload)
})
.then(response => {
if (!response.ok) {
throw new Error(`Erro ${response.status}: ${response.statusText}`);
}
console.log(`Status: ${response.status}`);
console.log(`Location: ${response.headers.get('Location')}`);
})
.catch(error => console.error('Erro na requisição:', error));import requests
from jsonschema import validate, ValidationError
# Esquema de validação do payload
schema = {
"type": "object",
"required": ["due_date", "amount", "description", "payer"],
"properties": {
"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}
}
}
# Payload
payload = {
"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"
}
# Validar payload
try:
validate(instance=payload, schema=schema)
except ValidationError as e:
print(f"Erro de validação: {e}")
exit(1)
# Enviar requisição
url = "https://sandbox.api.pagou.com.br/v1/charges"
headers = {
"X-API-KEY": "sua_chave_api",
"Content-Type": "application/json",
"User-Agent": "MinhaLoja/1.0"
}
try:
response = requests.post(url, json=payload, headers=headers)
response.raise_for_status()
print(f"Status: {response.status_code}")
print(f"Location: {response.headers.get('Location')}")
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
Payload inválido (ex.: CPF inválido, amount < 1.00).
Validar dados antes de enviar (use schema fornecido).
401
Unauthorized
X-API-KEY inválido ou ausente.
Verificar chave em Configurações > API.
429
Too Many Requests
Limite de requisições excedido.
Implementar rate limiting e retentativas exponenciais.
Boas Práticas Técnicas
Validação de Dados: Use esquemas JSON (como nos exemplos) para validar o payload antes de enviar, evitando erros 400.
Segurança: Armazene X-API-KEY em variáveis de ambiente e use HTTPS para todas as requisições.
Webhooks: Configure o
notification_urlpara receber o eventoChargePaidquando o boleto for pago.Testes no Sandbox: Use https://sandbox.api.pagou.com.br/v1/charge para simular criação de boletos sem custos reais.
Monitoramento: Registre todas as requisições e respostas (incluindo Location) em logs para auditoria e depuração.
Mapa de Status dos Boletos
Cada boleto possui um status que reflete seu estado no ciclo de vida. Os status possíveis, conforme definido na API do Pagou, são:
Status
Valor Numérico
Descrição
StatusEmpty
1
Estado inicial transitório, indicando que o boleto foi criado, mas ainda não está ativo (ex.: aguardando validação interna).
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 (ex.: por solicitação ou expiração).
StatusPaid
4
Boleto pago pelo cliente, com liquidação confirmada.
StatusRefunded
5
Boleto pago, mas reembolsado ao cliente (ex.: após devolução do produto).
Transições de Status:
StatusEmpty→StatusActive: Após validação interna bem-sucedida (geralmente imediata).StatusActive→StatusPaid: Quando o pagamento é confirmado (notificado via webhookChargePaid).StatusActive→StatusCanceled: Após solicitação de cancelamento via solicitação ou expiração.StatusPaid→StatusRefunded: Após processamento de reembolso.StatusEmpty,StatusCanceled,StatusRefunded: Estados finais, sem transições adicionais.
Last updated