QuickPay - Boletos

Gestão de emissão e gerenciamento de boletos no módulo QuickPay.

Listagem de Boletos

`[GET] quickpay/boletos`

Retorna uma lista paginada de boletos 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 100)
status	integer	Não	Filtro por status do boleto
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)
payment_date_start	date	Não	Data inicial de pagamento (Y-m-d)
payment_date_end	date	Não	Data final de pagamento (Y-m-d)
updated_at_start	date	Não	Data inicial de atualização (Y-m-d)
updated_at_end	date	Não	Data final de atualização (Y-m-d)
search	string	Não	Busca por nome, e-mail, documento ou TXID (case-insensitive)

Response (200 OK)

json

{
  "data": [
    {
      "id": 85,
      "status": 1,
      "status_label": "Pago",
      "webhook": "https://callback.com",
      "txid": "bol_def456",
      "pix_id": 10,
      "name": "Maria Santos",
      "email": "maria@email.com",
      "document": "12345678901",
      "rate": 2.5,
      "type_rate": "PERCENTAGE",
      "value": "250.00",
      "expired": "2024-12-30",
      "barcode": "...",
      "digitableLine": "...",
      "account_id": 1,
      "type_discount": "ABSOLUTE",
      "discount": 10.0,
      "days_discount": 5,
      "late_fee": 2.0,
      "processing_fee": 2.99,
      "yourNumber": "000001",
      "ourNumber": "12345678",
      "paid_amount": 0.0,
      "payment_date": null,
      "created_at": "2024-01-01T10:00:00.000000Z",
      "updated_at": "2024-01-01T10:00:00.000000Z",
      "charge_id": 150,
      "pix": [
        {
          "id": 10,
          "status": 1,
          "webhook": "...",
          "txid": "...",
          "qrcode": "...",
          "value": "250.00"
        }
      ],
      "json": {
        "nossoNumero": "12345678",
        "seuNumero": "000001",
        "deleted_history": [
          {
            "requested_at": "2024-02-28 14:00:00",
            "response": "400 - Requisição Inválida: ..."
          }
        ]
      }
    }
  ],
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "...",
    "per_page": 100,
    "to": 1,
    "total": 1
  }
}

Criar Boleto

`[POST] quickpay/boletos`

Gera um novo boleto bancário, opcionalmente viciado com um QR Code Pix.

Request Body

Nome	Tipo	Obrigatório	Descrição
amount	numeric	Sim	Valor nominal do boleto
expiration_date	date	Sim	Data de vencimento (Y-m-d)
name	string	Sim	Nome do pagador
email	string	Sim	E-mail do pagador
document	string	Sim	CPF ou CNPJ do pagador
webhook	url	Não	URL para notificações de alteração de status
hasPix	boolean	Não	Se deve gerar QR Code Pix associado (padrão false)
hasPDF	boolean	Não	Se deve gerar PDF imediato (apenas Sicredi)
late_fee	numeric	Não	Valor ou percentual da multa após vencimento
late_fee_type	string	Não	`ABSOLUTE` ou `PERCENTAGE` para a multa
amount_rate	numeric	Não	Valor ou percentual dos juros mensais
type_rate	string	Não	`ABSOLUTE` ou `PERCENTAGE` para os juros
discount	numeric	Não	Valor ou percentual do desconto
days_discount	integer	Não	Dias antes do vencimento para o desconto
type_discount	string	Não	`ABSOLUTE` ou `PERCENTAGE` para o desconto
phone	string	Não	Telefone do pagador
address	object	Não	Objeto contendo `street`, `number`, `city`, `state`, `zipcode`
split	object	Não	Objeto para divisão de valores (ver estrutura abaixo)

Estrutura do Objeto Split

json

{
  "type_value_split": "PERCENTAGE", // ou ABSOLUTE
  "recipients": [
    {
      "beneficiary_name": "Socio 1",
      "beneficiary_document": "12345678901",
      "bank_code": "001",
      "branch": "0001",
      "account": "123456",
      "account_type": "POUPANCA",
      "value": 10.0
    }
  ]
}

Response (200 OK)

json

{
  "success": true,
  "data": {
    "txid": "bol_def456",
    "status": 0,
    "status_label": "Pendente",
    "value": 250.0,
    "name": "João da Silva",
    "email": "joao@email.com",
    "document": "12345678901",
    "barcode": "...",
    "digitableLine": "...",
    "expired": "2024-12-30",
    "pix": {
      "txid": "...",
      "value": 250.0,
      "qrcode": "...",
      "image": "data:image/png;base64,..."
    },
    "pdf_path": "/storage/boletos/bol_def456.pdf"
  },
  "message": "Boleto Gerado com sucesso"
}

Consultar Boleto

`[GET] quickpay/boletos/{txid}`

Retorna os detalhes de um boleto específico via TXID.

Cancelar Boletos

`[POST] quickpay/boletos/cancel`

Realiza o cancelamento de um ou mais boletos. Este processo solicita a baixa bancária (no banco emissor) e atualiza o status no sistema.

Request Body

Nome	Tipo	Obrigatório	Descrição
txid	string	Não*	TXID de um único boleto para cancelar
txids	array	Não*	Lista de TXIDs para cancelamento em lote

* É obrigatório informar pelo menos um dos campos txid ou txids.

Exemplo Bulk

json

{
  "txids": ["bol_123", "bol_456"]
}

Response (200 OK)

json

{
  "success": true,
  "data": {
    "bol_123": { "success": true, "message": "Boleto cancelado com sucesso" },
    "bol_456": { "success": false, "message": "Boleto não encontrado" }
  },
  "message": "Processamento de cancelamento concluído"
}

Gerar/Consultar PDF

`[POST] quickpay/boletos/{txid}/pdf`

Retorna as URLs para acesso ao PDF do boleto.

Response (200 OK)

json

{
  "success": true,
  "data": {
    "pdf_url": "/storage/boletos/boleto_txid.pdf",
    "pdf_path": "/storage/boletos/boleto_txid.pdf",
    "pdf_url_full": "https://api.site.com/storage/boletos/boleto_txid.pdf"
  },
  "message": "PDF gerado com sucesso"
}

Deletar/Baixar Boleto

`[DELETE] quickpay/boletos/{txid}`

Realiza a baixa (cancelamento) do boleto via TXID na URL. É equivalente ao cancelamento unitário.

Pagamento de Boletos Externos (Saída)

`[POST] quickpay/boletos/payment-barcode`

Realiza o pagamento de um boleto externo utilizando o código de barras.

Consultar Info Barcode

`[POST] quickpay/boletos/info-barcode`

Extrai informações de um boleto (beneficiário, valor, vencimento) a partir do código de barras ou linha digitável.

Request Body

json

{
  "barcode": "00190500954014481606906809350314337370000000250"
}

Response (201 Created)

json

{
  "success": true,
  "data": {
    "boleto": {
      "beneficiary": "EMPRESA XPTO",
      "document": "...",
      "value": 250.00,
      "due_date": "2024-12-30"
    },
    "barcode": "00190500954014481606906809350314337370000000250"
  }
}

Tabela de Status

As APIs de boletos retornam os campos status (inteiro) e status_label (string). Veja os valores possíveis:

Código	Label	Descrição
0	Pendente	Aguardando pagamento
1	Pago	Pagamento confirmado
-5	Cancelado	Baixa bancária confirmada (Status final)
3	Expirado	Data de vencimento ultrapassada
4	Falhou	Erro no processamento do registro
5	Pago com Pix	Liquidado via QR Code Pix do Bolepix
-1	Deletado	Baixa bancária falhou ou removido internamente
-2	Deletado	Removido logicamente (Backup status)

QuickPay - Boletos ​

Listagem de Boletos ​

[GET] quickpay/boletos ​

Criar Boleto ​

[POST] quickpay/boletos ​

Consultar Boleto ​

[GET] quickpay/boletos/{txid} ​

Cancelar Boletos ​

[POST] quickpay/boletos/cancel ​

Gerar/Consultar PDF ​

[POST] quickpay/boletos/{txid}/pdf ​

Deletar/Baixar Boleto ​

[DELETE] quickpay/boletos/{txid} ​

Pagamento de Boletos Externos (Saída) ​

[POST] quickpay/boletos/payment-barcode ​

Consultar Info Barcode ​

[POST] quickpay/boletos/info-barcode ​

Tabela de Status ​

QuickPay - Boletos

Listagem de Boletos

`[GET] quickpay/boletos`

Criar Boleto

`[POST] quickpay/boletos`

Consultar Boleto

`[GET] quickpay/boletos/{txid}`

Cancelar Boletos

`[POST] quickpay/boletos/cancel`

Gerar/Consultar PDF

`[POST] quickpay/boletos/{txid}/pdf`

Deletar/Baixar Boleto

`[DELETE] quickpay/boletos/{txid}`

Pagamento de Boletos Externos (Saída)

`[POST] quickpay/boletos/payment-barcode`

Consultar Info Barcode

`[POST] quickpay/boletos/info-barcode`

Tabela de Status