Aparência
Cobranças
Emissão de Pix, boleto e BOLEPIX pela rota atual
/billing/charges, com os campos novos e o cancelamento no banco: Cobranças Pix e boleto.
Prefixo base: / (sem prefixo)
Todas as rotas requerem autenticação JWT + conta ativa.
Headers obrigatórios:
Authorization: Bearer {token}
Content-Type: application/json
account: {account_id} ← opcional se usuário tem apenas uma contaGET /charges
Lista cobranças da conta com filtros e paginação.
Query params:
| Parâmetro | Tipo | Descrição |
|---|---|---|
search | string | Busca por nome/e-mail/documento do cliente |
status_id | integer | Filtrar por status (ex: 1=pendente, 2=pago, 3=expirado, 4=cancelado) |
client_id | integer | Filtrar por cliente |
created_at_start | date Y-m-d | Data inicial de criação |
created_at_end | date Y-m-d | Data final de criação |
due_date_start | date Y-m-d | Vencimento inicial |
due_date_end | date Y-m-d | Vencimento final |
payment_date_start | date Y-m-d | Pagamento inicial |
payment_date_end | date Y-m-d | Pagamento final |
per_page | integer | Itens por página (padrão: 15, máx: 100) |
page | integer | Página atual |
Response 200:
json
{
"data": [
{
"id": 101,
"code": "abc123",
"value": "150.00",
"amount_paid": "150.00",
"due_date": "2025-07-15T00:00:00.000000Z",
"payment_date": "2025-07-10",
"payment_method_used": "BOLEPIX",
"description": "Mensalidade julho",
"path_pdf": "https://...",
"status": {
"id": 2,
"title": "paid",
"description": "Pago"
},
"client": {
"id": 5,
"name": "Maria Oliveira",
"email": "maria@exemplo.com",
"document": "98765432100"
},
"boleto": { ... },
"pix": { ... },
"created_at": "2025-07-01T10:00:00.000000Z"
}
],
"meta": {
"current_page": 1,
"per_page": 15,
"total": 48,
"last_page": 4
},
"summary": [
{
"status_id": 2,
"total_qtd": 30,
"total_amount_paid": "4500.00",
"total_value": "4500.00",
"status": { "id": 2, "title": "paid", "description": "Pago" }
}
],
"message": "Lista de Cobranças"
}POST /charges
Cria uma nova cobrança (Boleto, BolePix ou Pix).
Body:
json
{
"client_id": 5,
"amount": 150.00,
"payment_method": "BOLEPIX",
"expiration_date": "2025-07-31",
"description": "Mensalidade julho",
"webhook": "https://meusite.com/webhook",
"amount_rate": 2.0,
"type_rate": "PERCENTAGE",
"discount": 10.00,
"days_discount": 5,
"type_discount": "ABSOLUTE",
"late_fee": 5.00,
"split": {
"type_value_split": "PERCENTAGE",
"recipients": [
{ "establishment_id": 3, "value": 10 }
]
}
}| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
client_id | integer | Sim | deve existir em clients da conta |
amount | numeric | Sim | valor positivo |
payment_method | string | Sim | PIX ou BOLEPIX |
expiration_date | date | Sim | igual ou posterior a hoje |
description | string | Não | máx. 200 caracteres |
webhook | string | Não | URL válida |
amount_rate | numeric | Não | Juros |
type_rate | string | Não | ABSOLUTE ou PERCENTAGE |
discount | numeric | Não | Desconto |
days_discount | integer | Não | Dias antes do vencimento para desconto |
late_fee | numeric | Não | Multa por atraso |
split.type_value_split | string | Não | PERCENTAGE ou ABSOLUTE |
split.recipients | array | Não | Lista de destinatários de split |
Response 200:
json
{
"data": {
"id": 102,
"code": "xyz789",
"value": "150.00",
"due_date": "2025-07-31T00:00:00.000000Z",
"payment_method_used": "BOLEPIX",
"status": { "id": 1, "title": "pending" },
"client": { ... },
"boleto": {
"txid": "00190.00009 01234.567890 12345.678903 1 92850000015000",
"barcode": "00190000090123456789012345678903192850000015000",
"digitable_line": "00190.00009 01234.567890...",
"value": "150.00",
"expired": "2025-07-31"
},
"pix": {
"txid": "abc123def",
"qrcode": "00020126330014...",
"image": "data:image/png;base64,..."
},
"path_pdf": "https://storage/cobranças/102.pdf"
},
"message": "Cobrança criada com sucesso!"
}Erros:
| Código | Descrição |
|---|---|
| 422 | Validação falhou (cliente não encontrado, data inválida, etc.) |
| 500 | Falha na comunicação com banco parceiro |
Regras de negócio:
- Para
BOLEPIX: gera boleto + Pix dinâmico juntos via API do banco parceiro. - Para
PIX: gera apenas Pix dinâmico. - Após criar, gera PDF da cobrança e salva no storage.
- Envia e-mail de notificação ao cliente se ele tiver e-mail cadastrado.
- Suporta split de valores entre estabelecimentos.
GET /charges/{id}
Retorna os detalhes de uma cobrança pelo id numérico.
Response 200:
json
{
"data": {
"id": 102,
"code": "xyz789",
"value": "150.00",
"amount_paid": null,
"payment_date": null,
"due_date": "2025-07-31T00:00:00.000000Z",
"payment_method_used": "BOLEPIX",
"description": "Mensalidade julho",
"path_pdf": "https://...",
"status": { "id": 1, "title": "pending", "description": "Pendente" },
"client": { "id": 5, "name": "Maria", "email": "maria@ex.com" },
"boleto": { ... },
"pix": { ... },
"splits": [ ... ]
},
"message": "Detalhes da Cobrança"
}Erros:
| Código | Descrição |
|---|---|
| 404 | Cobrança não encontrada |
PUT /charges/{id}
Atualiza valor e/ou data de vencimento de uma cobrança pendente.
A cobrança é identificada só pelo id da URL. Um code enviado no corpo não é usado para localizá-la.
Body:
json
{
"amount": 200.00,
"expiration_date": "2025-08-15",
"description": "Mensalidade agosto",
"client_id": 5
}| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
amount | numeric | Não | Novo valor |
expiration_date | date | Não | Igual ou posterior a hoje |
description | string | Não | máx. 200 caracteres |
client_id | integer | Não | Deve existir |
Response 200:
json
{
"data": { ... },
"message": "Cobrança atualizada com sucesso!"
}Regras de negócio:
- Se houver mudança de valor ou data, o boleto e/ou Pix são atualizados via API do banco.
- O PDF é regerado após atualização.
DELETE /charges/{id}
Remove (soft delete) a cobrança e marca como DELETED.
Response 200:
json
{
"message": "Cobrança apagado com sucesso!"
}POST /charges/{id}/cancel
Esta rota não existe com esse caminho. O cancelamento que mantém a cobrança visível é POST /billing/charges/{id}/cancel: veja Cobranças Pix e boleto.
POST /charges/{id}/reissue
Reemite a cobrança com nova data de vencimento, criando uma nova cobrança baseada nos dados da original.
Body:
json
{
"expiration_date": "2025-09-30"
}| Campo | Tipo | Obrigatório | Regras |
|---|---|---|---|
expiration_date | date | Sim | Igual ou posterior a hoje |
Response 200:
json
{
"data": {
"id": 115,
"code": "novo123",
"value": "150.00",
"due_date": "2025-09-30T00:00:00.000000Z",
"status": { "id": 1, "title": "pending" },
"boleto": { ... },
"pix": { ... }
},
"message": "Cobrança reemitida com sucesso!"
}Regras de negócio:
- Cria uma nova cobrança com os mesmos dados (cliente, valor, método de pagamento, descrição).
- Gera novo boleto/Pix no banco parceiro.
GET /billing/charges/{id}/download-pdf
Baixa o PDF da cobrança pelo id numérico. O code não é aceito (404). (O antigo GET /quickpay/charges/{id}/download foi removido em 03/10/2026.)
Response: Arquivo PDF (application/pdf)
GET /billing/charges/reports
Retorna dados agrupados para gráficos (por dia ou mês), por status e método de pagamento. A data de referência é a de pagamento para cobranças pagas e a de vencimento para as demais. Substitui GET /quickpay/charges/reports e GET /quickpay/chargess/reports, removidos em 03/10/2026.
Query params:
| Parâmetro | Tipo | Obrigatório | Valores |
|---|---|---|---|
group_by | string | Sim | days ou months |
date_start | date | Sim | Data inicial |
date_end | date | Sim | Data final (≥ date_start) |
Response 200:
json
[
{
"reference_date": "2025-07-01",
"status_id": 2,
"payment_method": "PIX",
"total_qtd": 12,
"total_amount_paid": "1800.00",
"total_value": "1800.00",
"total_method_paid": "1800.00",
"total_method_unpaid": "0.00",
"status": { "id": 2, "title": "paid", "description": "Pago" }
}
]GET /quickpay/charges/export (removida)
/quickpay/charges/exportA exportação de cobranças por essa rota foi removida em 03/10/2026: nenhum portal a usava (o portal gera o CSV a partir dos dados já carregados). A rota responde 404.
GET /billing/reports (nunca existiu)
/billing/reportsEsta seção descrevia um relatório financeiro em GET /billing/reports. A rota nunca foi registrada. O controller e o service dela (Reports\BillingReportController, Reports\BillingReportService) eram código morto e foram apagados em 03/10/2026, junto com Reports\CustomerReportController/CustomerReportService. Para relatório de cobranças, use GET /billing/charges/reports.