Cobranças (Charges)

Este documento detalha os endpoints de consultas avançadas, relatórios, exportações e ações adicionais (download de PDFs e envio de notificações) do módulo QuickPay.

---

1. Relatório de Cobranças (Reports)

Retorna dados estáticos e métricas financeiras sumarizadas por período (dias ou meses). É útil para construção de gráficos e dashboards no front-end.

Endpoint:GET quickpay/charges/reports

Parâmetros da Requisição (Query String)

Parâmetro	Tipo	Obrigatório	Descrição
group_by	string	Sim	Agrupamento dos dados. Valores permitidos: days ou months.
date_start	date	Sim	Data de início da análise (Formato: Y-m-d).
date_end	date	Sim	Data de término (deve ser maior ou igual a date_start).

Exemplo de Retorno (200 OK)

[
  {
    "reference_date": "2023-10-01",
    "status_id": 2,
    "total_qtd": 15,
    "total_amount_paid": "1500.00",
    "total_value": "1500.00",
    "status": {
      "id": 2,
      "title": "Pago",
      "description": "Cobrança foi paga pelo cliente."
    }
  }
]

---

2. Exportação de Cobranças (Export Document)

Exporta a listagem de cobranças em vários formatos (xlsx, csv, pdf). Pode processar de forma síncrona (download direto) ou agendar o processamento em fila.

Endpoint:GET quickpay/charges/export

Parâmetros da Requisição (Query String)

Parâmetro	Tipo	Obrigatório	Padrão	Descrição
format	string	Não	xlsx	Formato da exportação. Permitidos: xlsx, csv e pdf.
download	boolean	Não	false	true ou 1 executa o download imediato, ignorando a fila.
search	string	Não	-	Termo de busca genérica (nome do cliente, documento, etc).
client_id	int	Não	-	Filtrar por cliente.
status_id	string	Não	-	Um ID numérico ou vários IDs separados por vírgula (ex: 1,2).
created_at_start	date	Não	-	Filtro de data de criação (Início).
created_at_end	date	Não	-	Filtro de data de criação (Fim).
due_date_start	date	Não	-	Filtro de data de vencimento (Início).
due_date_end	date	Não	-	Filtro de data de vencimento (Fim).

Exemplo de Retorno Síncrono (download=true) (200 OK)

Retorna o conteúdo binário correspondente ao formato solicitado (Headers: Content-Type: application/pdf, application/vnd.openxmlformats..., ou text/csv).

Exemplo de Retorno Assíncrono (download=false) (202 Accepted)

Se a flag de download não for enviada ou for false, será disparado um Job que enviará o arquivo por email ao usuário vinculado, evitando timeouts na requisição.

{
  "success": true,
  "message": "Exportação agendada com sucesso!",
  "data": {
    "message": "Sua exportação foi iniciada. Você receberá um email em breve com o link para download."
  }
}

---

3. Download da Cobrança (PDF)

Gera ou baixa o arquivo PDF com os detalhes da cobrança (comprovante).

Endpoint:GET quickpay/charges/\{id\}/download

Parâmetros da Requisição (Path)

Parâmetro	Tipo	Obrigatório	Descrição
id	int / string	Sim	ID interno ou code único da cobrança.

Retorno (200 OK)

O endpoint renderiza e devolve via HTTP Stream o conteúdo binário nativo do PDF. O header configurará o Client para forçar o download. Headers:

• Content-Type: application/pdf
• Content-Disposition: attachment; filename="comprovante_\{id\}.pdf"

---

4. Disparo de Notificação (Notify)

Envia uma notificação manual/alerta por E-mail relatando a situação de uma determinada cobrança ou recado personalizado ao respectivo cliente.

Endpoint:POST quickpay/charges/\{id\}/notify

Parâmetros da Rota

Parâmetro	Tipo	Obrigatório	Descrição
id	int / string	Sim	ID interno ou code único da cobrança.

Corpo da Requisição (JSON Payload)

Parâmetro	Tipo	Regras	Descrição
message	string	Opcional (Max: 255 car)	Mensagem adcional incluída na notificação

Exemplo de Requisição (Body)

{
    "message": "Prezado cliente, informamos que o seu boleto de manutenção anual está vencido."
}

Exemplo de Retorno (200 OK)

{
    "message": "Notificação enviada com sucesso!"
}