Get a boleto batch

Reads one boleto batch of the X-Organization-Id organization: its outcome, its counts and every item, in ascending position. The outcome, the counts, closed, finished and each item’s overdue are derived from the items on every read, at the instant of the read. A batch that does not exist and a batch of another organization are both answered 404 PBP-0005, with the same body. A request refused earlier keeps its own status: 401 or 403 for authentication and authorization, 400 PBP-0001 when batch_id is not a UUID, and 400 PBP-0025 when X-Organization-Id is missing or not a canonical UUID.

GET /v1/boletos/batches/{batch_id}

Get a boleto batch

cURL

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

200

{
  "batchId": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",
  "closed": true,
  "counts": {
    "canceled": 1,
    "failed": 1,
    "inactivated": 0,
    "overdue": 0,
    "processing": 1,
    "registered": 2,
    "requested": 5,
    "settled": 0
  },
  "createdAt": "2026-10-14T19:34:00Z",
  "finished": true,
  "items": [
    {
      "amount": "150.00",
      "boletoId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "cancelable": true,
      "dueDate": "2030-01-15",
      "overdue": true,
      "payer": {
        "document": "<string>",
        "name": "<string>",
        "address": {
          "city": "<string>",
          "complement": "<string>",
          "neighborhood": "<string>",
          "number": "<string>",
          "state": "<string>",
          "street": "<string>",
          "zipCode": "<string>"
        }
      },
      "position": 0,
      "status": "CREATED",
      "discount": {
        "amount": "<string>",
        "limitDate": "<string>",
        "type": "<string>"
      },
      "errorCode": "PBP-0108",
      "errorMessage": "no title was issued for this emission",
      "fine": {
        "amount": "<string>",
        "type": "<string>"
      },
      "instructions": "<string>",
      "interest": {
        "amount": "<string>",
        "type": "<string>"
      },
      "ourNumber": "00000000152",
      "ourNumberDigit": "3",
      "ourNumberHolderBoletoId": "<string>",
      "providerId": "<string>",
      "requestedOurNumber": "00000000152"
    }
  ],
  "ledgerId": "7c1e5b9a-3d2f-4a6b-8e0c-1f2a3b4c5d6e",
  "midazAccountId": "3f9a2c1e-5b7d-4e8f-9a0b-1c2d3e4f5a6b",
  "organizationId": "0f9d6c2a-1b3e-4f5a-8c7d-6e5f4a3b2c1d",
  "status": "CREATED"
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Encabezados

X-Organization-Id · string

Organization the batch belongs to. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025. A batch of another organization is answered 404, exactly as one that does not exist.

Parámetros de ruta

batch_id · string<uuid> · requerido

Batch identifier (UUID), the batchId the creation answered. A value that is not a UUID is refused with 400 PBP-0001.

Ejemplo:

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

Respuesta

200

application/json

The batch with its outcome, its counts and every item, derived at the instant of the read.

batchId · string<uuid> · requerido

Batch identifier.

Ejemplo:

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

closed · boolean · requerido

Whether every item is SETTLED, CANCELED, INACTIVATED or FAILED: nothing else will happen to the batch, payment included. Always present. It moves back to false when a cancellation is refused and the item returns to CREATED. True implies finished.

counts · object · requerido

Show child attributes

createdAt · string<date-time> · requerido

When the batch was created, RFC 3339 in UTC.

Ejemplo:

"2026-10-14T19:34:00Z"

finished · boolean · requerido

Whether no item is PENDING: the issuance of the batch is over. Always present. It never moves back to false; an overdue item keeps it false.

items · object[] | null · requerido

Every item, in ascending position. Never paginated: a batch holds at most 25 items.

Show child attributes

ledgerId · string<uuid> · requerido

Ledger of the batch and of each item.

Ejemplo:

"7c1e5b9a-3d2f-4a6b-8e0c-1f2a3b4c5d6e"

midazAccountId · string · requerido

Collection account of the batch and of each item.

Ejemplo:

"3f9a2c1e-5b7d-4e8f-9a0b-1c2d3e4f5a6b"

organizationId · string<uuid> · requerido

Organization the batch was recorded with: always the organization of the X-Organization-Id header.

Ejemplo:

"0f9d6c2a-1b3e-4f5a-8c7d-6e5f4a3b2c1d"

status · enum<string> · requerido

Issuance outcome of the batch, derived from its items on every read. CREATED: some item is still PENDING. COMPLETED: no item is PENDING and none is FAILED. PARTIAL_FAILURE: no item is PENDING and some, not all, are FAILED; those carry errorCode and errorMessage. FAILED: every item is FAILED. Only issuance moves it: payment, cancellation and write-off do not, and it never moves back to CREATED.

Opciones disponibles: CREATED, COMPLETED, PARTIAL_FAILURE, FAILED