Issue a batch of boletos
Issues from 1 to 25 TRADITIONAL boletos, one per item, on one collection account (midazAccountId) and one ledger (ledgerId) of the X-Organization-Id organization, in a single request. The answer is 202 Accepted with the batch and the status of each item: the batch is recorded and its items are sent for issuance, and no item carries a barcode in this answer. Issuance goes on asynchronously, each item on its own; follow it at GET /v1/boletos/batches/ or through the status change notifications configured at /v1/admin/webhooks. A request refused before anything is recorded keeps its own status and code, in this order: 401 or 403 for authentication and authorization; 400 PBP-0012 for a missing or malformed Idempotency-Key; 413 PBP-0010 for a body above 256 KiB (262144 bytes); 400 PBP-0001 for a body that fails schema validation, including items absent or null, an item without type, and guarantor, ledgerId or midazAccountId sent inside an item; 400 PBP-0025 when X-Organization-Id is missing or not a canonical UUID; 400 PBP-0026 when ledgerId is missing or not a canonical UUID; 400 PBP-0001 when midazAccountId is blank; 422 PBP-0122 when the batch holds fewer than 1 or more than 25 items, with maxItems and receivedItems; 404 PBP-0005 when the account does not exist or is not under the organization and the ledger; 400 PBP-0116 when the account has no registered holder, or the holder’s registration is incomplete, and 422 PBP-0117 when the registered holder cannot be used as a final beneficiary; 422 PBP-0123 when one or more items break a rule, the whole batch refused with every problem listed in itemErrors, each with its position and field; and 422 PBP-0017 when an item carries ourNumber and this instance has no account discovery to reserve it in. A retry carrying the same Idempotency-Key and the same body issues no boleto: it returns the stored answer of the first call while the service keeps the idempotency record of that call, and the batch’s current state once the record has expired. The same key with a different body is refused with 422 PBP-0013.
Authorizations
JWT bearer token issued by the identity provider.
Headers
Midaz organization the account and the ledger entry live under. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025.
Client-supplied idempotency key, a UUID. Required: a request without it, with a value that is not a UUID, or with the nil UUID (00000000-0000-0000-0000-000000000000) is refused with 400 PBP-0012.
Body
Boletos of the batch, from 1 to 25, in the order the client wants to see them. The position of each item is its index in this list, from 0: the position of the response and the index of body.items[] in a refusal. A list outside 1 to 25 items, the empty list included, refuses the whole batch with 422 PBP-0122, which carries the limit and the number of items received; the batch is never split.
Midaz account every item of the batch settles into. Its holder is the final beneficiary of every item. It must belong to the organization and the ledger, or the request is answered 404. Checked once per batch.
Midaz ledger the account lives in and the entry is posted to. Required: absent, blank or not a canonical UUID is refused with 400 PBP-0026.
Response
Accepted: the batch is recorded and its items are sent for issuance. Each item carries its position, its boleto and its status.
Batch identifier.
"0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b"
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.
When the batch was created, RFC 3339 in UTC.
"2026-10-14T19:34:00Z"
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.
Every item, in ascending position. Never paginated: a batch holds at most 25 items.
Ledger of the batch and of each item.
"7c1e5b9a-3d2f-4a6b-8e0c-1f2a3b4c5d6e"
Collection account of the batch and of each item.
"3f9a2c1e-5b7d-4e8f-9a0b-1c2d3e4f5a6b"
Organization the batch was recorded with: always the organization of the X-Organization-Id header.
"0f9d6c2a-1b3e-4f5a-8c7d-6e5f4a3b2c1d"
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.
CREATED, COMPLETED, PARTIAL_FAILURE, FAILED