Billing - Cobranças (Charges)

Gestão de cobranças no módulo Billing. Este módulo permite a criação de cobranças avulsas ou parceladas, suportando Pix, Boleto e Cartão de Crédito.

As rotas de Billing estão disponíveis sob o prefixo billing/.

---

Listagem de Cobranças

[GET] billing/charges

Retorna uma lista paginada de cobranças da conta autenticada.

Query Params

Nome	Tipo	Obrigatório	Descrição
page	integer	Não	Página atual (padrão 1)
per_page	integer	Não	Itens por página (padrão 15)
status_id	mixed	Não	ID ou lista de IDs de status (ex: 1 ou 1,2,3)
created_at_start	date	Não	Data inicial de criação (Y-m-d)
created_at_end	date	Não	Data final de criação (Y-m-d)
due_date_start	date	Não	Data inicial de vencimento (Y-m-d)
due_date_end	date	Não	Data final de vencimento (Y-m-d)
search	string	Não	Busca por nome, e-mail ou documento do cliente
order_by	string	Não	Campo para ordenação
order_dir	string	Não	Direção (asc ou desc)
has_distribution	boolean	Não	Filtrar cobranças com split

Response (200 OK)

{
  "current_page": 1,
  "data": [
    {
      "id": 1001,
      "code": "ch_7a9b...",
      "value": "150.00",
      "amount_paid": "0.00",
      "status_id": 1,
      "status": { "id": 1, "title": "pending", "label": "Pendente" },
      "payment_method": "BOLEPIX",
      "due_date": "2024-12-30",
      "client": {
        "id": 50,
        "name": "Cliente Exemplo",
        "email": "cliente@email.com",
        "document": "12345678901"
      }
    }
  ],
  "total": 125
}

---

Criar Cobrança

[POST] billing/charges

Cria uma nova cobrança. Pode gerar Pix, Boleto ou ambos (Bolepix), ou processar Cartão de Crédito.

Request Body

Nome	Tipo	Obrigatório	Descrição
value	numeric	Sim*	Valor da cobrança (ou amount)
due_date	date	Sim	Data de vencimento (Y-m-d)
payment_method	string	Sim	PIX, BOLETO, BOLEPIX ou CREDIT_CARD
name	string	Sim**	Nome do cliente
email	string	Sim**	E-mail do cliente
document	string	Sim**	CPF/CNPJ do cliente (Obrigatório para Boleto/Cartão)
phone	string	Não	Telefone do cliente
address	object	Não	Objeto com endereço (obrigatório para Cartão)
description	string	Não	Descrição da cobrança
charge_group_id	integer	Não	ID do grupo de cobrança associado
webhook	url	Não	URL para notificações de status
split	array	Não	Estrutura de divisão de valores

* Utilize value ou amount.** Se client_id for fornecido, os dados do cliente são carregados automaticamente.

Exemplo (Pix/Boleto)

{
  "value": 100.00,
  "due_date": "2024-12-30",
  "payment_method": "BOLEPIX",
  "name": "Jose Silva",
  "document": "000.000.000-00",
  "email": "jose@email.com"
}

Response (201 Created)

{
  "data": {
    "id": 1002,
    "value": 100.0,
    "status": "pending",
    "payment_method": "BOLEPIX",
    "pix": {
      "txid": "...",
      "qrcode": "..."
    },
    "boleto": {
      "barcode": "...",
      "digitableLine": "..."
    }
  }
}

---

Detalhes da Cobrança

[GET] billing/charges/{id}

Retorna os detalhes completos de uma cobrança, incluindo dados do Pix e Boleto associados. O {id} pode ser o ID numérico ou o código (code) da cobrança.

---

Atualizar Cobrança

[PUT] billing/charges/{id}

Permite atualizar dados de uma cobrança que ainda esteja com status pending. Se o valor for alterado, o Pix associado será atualizado ou gerado novamente.

Campos Editáveis: value, description, due_date, webhook, payment_method, etc.

---

Deletar Cobrança

[DELETE] billing/charges/{id}

Marca a cobrança com o status DELETED.

---

Download do PDF

[GET] billing/charges/{id}/download-pdf

Gera e inicia o download do PDF da fatura/boleto da cobrança.

---

Simular Pagamento (Ambiente de Teste)

[POST] billing/simulate-payment/{id}/charges

Disponível apenas para contas de teste (IDs 1, 2, 3), esta rota simula a liquidação de uma cobrança, atualizando o status para paid, criando a transação financeira e disparando webhooks.

---

Notificar Cliente

[POST] billing/charges/notify

[POST] billing/charges/{id}/notify

Envia notificações de uma ou várias cobranças em aberto para os clientes através de múltiplos canais (E-mail, WhatsApp, SMS). O processamento é assíncrono (Job).

Request Body

Nome	Tipo	Obrigatório	Descrição
channels	array	Sim	Lista de canais: email, whatsapp, sms
ids	array	Não*	Lista de IDs ou Códigos das cobranças para notificação em massa.
id	mixed	Não*	Um único ID ou Código da cobrança.
message	string	Não	Mensagem personalizada. Suporta os placeholders: :link (Link de Pagamento), :name (Nome do Cliente), :value (Valor Formatado) e :due_date (Data de Vencimento).

* Opcional se o {id} for passado na URL.

Exemplo (Massa)

{
  "ids": [105, "ch_abc123", 110],
  "channels": ["whatsapp"],
  "message": "Olá, sua fatura vence logo. Pague aqui: :link"
}

Mensagens Padrão (Fallback)

• WhatsApp: Olá [Nome], sua cobrança no valor de R$ [Valor] está disponível. Acesse o link para pagar: [Link]
• SMS: Sua cobranca de R$ [Valor] vence em [Data]. Pague aqui: [Link]

---

Tabela de Status (Charges)

ID	Título	Legenda	Descrição
1	pending	Em Aberto	Aguardando pagamento
2	paid	Pago	Pagamento confirmado
3	canceled	Expirado	Prazo de pagamento encerrado
4	processing	Em Processamento	Pagamento em análise
5	failed	Falhou	Erro no processamento do pagamento
6	overpaid	Pago em Excesso	Valor pago foi maior que o cobrado
7	underpaid	Pago a Menos	Valor pago foi menor que o cobrado
8	DELETED	Deletado	Cobrança removida logicamente

---

Relatório de Cobranças

[GET] reports/invoices

Gera estatísticas e relatórios de cobranças agrupados por dia ou mês dentro de um período específico. As estatísticas são consolidadas por status.

Query Params

Nome	Tipo	Obrigatório	Descrição
group_by	string	Sim	Agrupamento dos dados: days ou months
date_start	date	Sim	Data inicial do período (Y-m-d)
date_end	date	Sim	Data final do período (Y-m-d)

Lógica de Data de Referência:

• Se a cobrança estiver paga, utiliza-se a payment_date.
• Caso contrário, utiliza-se a updated_at.

Response (200 OK)

{
 "success": true,
 "message": "Relatório de cobranças gerado com sucesso.",
 "data": [
   {
     "reference_date": "2024-03-01",
     "status_id": 1,
     "total_qtd": 15,
     "total_amount_paid": "0.00",
     "total_value": "1500.00",
     "status": {
       "id": 1,
       "title": "pending",
       "description": "Aguardando pagamento"
     }
   },
   {
     "reference_date": "2024-03-01",
     "status_id": 2,
     "total_qtd": 8,
     "total_amount_paid": "800.00",
     "total_value": "800.00",
     "status": {
       "id": 2,
       "title": "paid",
       "description": "Pagamento confirmado"
     }
   }
 ]
}

---

Comandos Artisan

Importar Cobrança do Banco

php artisan charge:import {nosso_numero} {account_id}

Este comando busca uma cobrança diretamente na API da instituição bancária vinculada à conta e a sincroniza com o sistema interno. É útil para recuperar pagamentos feitos fora do fluxo normal ou para reconciliação manual.

Funcionalidades:

• Consulta o banco (Sicoob ou Sicredi) via API.
• Cria ou atualiza o cliente no sistema.
• Cria ou atualiza o Boleto e a Charge.
• Sicoob: Extrai automaticamente o valor pago (paid_amount) e a data de pagamento (payment_date) a partir do histórico de liquidação bancária.