List boletos

Lists boletos with optional status, kind, type, batch and date filters, paginated. Kind BATCH lists the items of batches, and batchId the items of one batch.

GET /v1/boletos

List boletos

cURL

curl --request GET \
  --url https://api.example.com/v1/boletos \
  --header 'Authorization: Bearer <token>'

200

{
  "items": [
    {
      "amount": "<string>",
      "cancelable": true,
      "createdAt": "<string>",
      "dueDate": "<string>",
      "id": "<string>",
      "kind": "<string>",
      "ledgerId": "<string>",
      "midazAccountId": "<string>",
      "organizationId": "<string>",
      "payer": {
        "document": "<string>",
        "name": "<string>",
        "address": {
          "city": "<string>",
          "complement": "<string>",
          "neighborhood": "<string>",
          "number": "<string>",
          "state": "<string>",
          "street": "<string>",
          "zipCode": "<string>"
        }
      },
      "status": "<string>",
      "type": "<string>",
      "updatedAt": "<string>",
      "barcode": "<string>",
      "batchId": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",
      "batchPosition": 3,
      "canceledAt": "<string>",
      "cancellationReason": "<string>",
      "digitableLine": "<string>",
      "discount": {
        "amount": "<string>",
        "limitDate": "<string>",
        "type": "<string>"
      },
      "errorMessage": "<string>",
      "excessPayments": [
        {
          "amount": "10.00",
          "detectedAt": "2023-11-07T05:31:56Z",
          "paidAt": "2023-11-07T05:31:56Z",
          "paidVia": "BOLETO",
          "providerReference": "<string>"
        }
      ],
      "failedAt": "<string>",
      "fine": {
        "amount": "<string>",
        "type": "<string>"
      },
      "guarantor": {
        "document": "<string>",
        "name": "<string>",
        "address": {
          "city": "<string>",
          "complement": "<string>",
          "neighborhood": "<string>",
          "number": "<string>",
          "state": "<string>",
          "street": "<string>",
          "zipCode": "<string>"
        }
      },
      "inactivatedAt": "<string>",
      "installmentLabel": "<string>",
      "instructions": "<string>",
      "interest": {
        "amount": "<string>",
        "type": "<string>"
      },
      "midazOperationId": "<string>",
      "ourNumber": "00000000029",
      "ourNumberDigit": "3",
      "paidVia": "BOLETO",
      "pixLocation": "pix.example.com/qr/v2/cobv/5d9a8e91c88c43db942d01a0ad92ffc3",
      "pixTxId": "35dabf21d3b941e8a937409b8749f281",
      "providerId": "<string>",
      "qrCode": "<string>",
      "seriesId": "<string>",
      "settledAmount": "<string>",
      "settledAt": "<string>"
    }
  ],
  "limit": 123,
  "page": 123,
  "total": 123
}

Autorizações

Authorization · string · header · obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

X-Organization-Id · string

Midaz organization whose boletos are listed. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. Only boletos of this organization are listed and counted.

Parâmetros de consulta

status · enum<string>

Status filter.

Opções disponíveis: PENDING, CREATED, SETTLED, CANCELED, INACTIVATED, FAILED

Exemplo:

"CREATED"

kind · enum<string>

Boleto kind filter. BATCH lists the items of batches.

Opções disponíveis: SINGLE, INSTALLMENT, BATCH

Exemplo:

"SINGLE"

type · enum<string>

Boleto type filter.

Opções disponíveis: TRADITIONAL, QR_CODE, HYBRID

Exemplo:

"TRADITIONAL"

batchId · string<uuid>

Batch filter: only the boletos created as items of this batch. A value that is not a UUID is refused with 400 PBP-0001. A batch that does not exist, or that belongs to another organization, yields an empty list (total 0), not 404: this is a filter. Combined with a kind other than BATCH, the list is empty.

Exemplo:

"0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b"

from · string

Created-from bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and starts at its first instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T00:00:00-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B).

Pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2}))?$

Exemplo:

"2026-01-01"

to · string

Created-to bound, inclusive. A calendar date (YYYY-MM-DD) is a UTC day and covers it to its last instant; an RFC 3339 date-time with offset (e.g. 2026-09-30T23:59:59.999999-03:00) is used as the exact instant. A positive offset must be percent-encoded (%2B).

Pattern: ^[0-9]{4}-[0-9]{2}-[0-9]{2}(T[0-9]{2}:[0-9]{2}:[0-9]{2}([.][0-9]{1,9})?(Z|[+-][0-9]{2}:[0-9]{2}))?$

Exemplo:

"2026-12-31"

dueDateFrom · string<date>

Due-date lower bound, inclusive.

Exemplo:

"2026-02-01"

dueDateTo · string<date>

Due-date upper bound, inclusive.

Exemplo:

"2026-11-30"

page · integer<int64> · padrão: 1

Page number, one-based.

Intervalo obrigatório: x >= 1

Exemplo:

1

limit · integer<int64> · padrão: 20

Items per page.

Intervalo obrigatório: 1 <= x <= 100

Exemplo:

20

Resposta

200

application/json

OK

items · object[] | null · obrigatório

Show child attributes

limit · integer<int64> · obrigatório

page · integer<int64> · obrigatório

total · integer<int64> · obrigatório