Skip to content

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 conta

GET /charges ​

Lista cobranças da conta com filtros e paginação.

Query params:

ParâmetroTipoDescrição
searchstringBusca por nome/e-mail/documento do cliente
status_idintegerFiltrar por status (ex: 1=pendente, 2=pago, 3=expirado, 4=cancelado)
client_idintegerFiltrar por cliente
created_at_startdate Y-m-dData inicial de criação
created_at_enddate Y-m-dData final de criação
due_date_startdate Y-m-dVencimento inicial
due_date_enddate Y-m-dVencimento final
payment_date_startdate Y-m-dPagamento inicial
payment_date_enddate Y-m-dPagamento final
per_pageintegerItens por página (padrão: 15, máx: 100)
pageintegerPá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 }
    ]
  }
}
CampoTipoObrigatórioRegras
client_idintegerSimdeve existir em clients da conta
amountnumericSimvalor positivo
payment_methodstringSimPIX ou BOLEPIX
expiration_datedateSimigual ou posterior a hoje
descriptionstringNãomáx. 200 caracteres
webhookstringNãoURL válida
amount_ratenumericNãoJuros
type_ratestringNãoABSOLUTE ou PERCENTAGE
discountnumericNãoDesconto
days_discountintegerNãoDias antes do vencimento para desconto
late_feenumericNãoMulta por atraso
split.type_value_splitstringNãoPERCENTAGE ou ABSOLUTE
split.recipientsarrayNãoLista 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ódigoDescrição
422Validação falhou (cliente não encontrado, data inválida, etc.)
500Falha 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ódigoDescrição
404Cobranç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
}
CampoTipoObrigatórioRegras
amountnumericNãoNovo valor
expiration_datedateNãoIgual ou posterior a hoje
descriptionstringNãomáx. 200 caracteres
client_idintegerNãoDeve 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"
}
CampoTipoObrigatórioRegras
expiration_datedateSimIgual 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âmetroTipoObrigatórioValores
group_bystringSimdays ou months
date_startdateSimData inicial
date_enddateSimData 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) ​

A 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) ​

Esta 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.