> ## Documentation Index > Fetch the complete documentation index at: https://docs.lerian.studio/llms.txt > Use this file to discover all available pages before exploring further. # 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/{batch_id} 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. ## OpenAPI ````yaml /pt/openapi/v3-current/payments.yaml post /v1/boletos/batches openapi: 3.1.0 info: description: >- API for the Lerian Payments interface via BTG. It covers boleto issuance, cancellation, and queries; bill payments (bankslip, utilities, and DARF) and queries; aggregated boleto and payment dashboards; provider connection and outbound webhook configuration; and the provider webhook receiver for settlement events. ERROR BODIES. A failed request arrives as an RFC 9457 problem document on application/problem+json. Branch on the code member. A license refusal carries an LCS code, listed in the License Manager error list. title: Payments — via BTG API version: 1.0.0 servers: - url: https://api.example.com description: >- Replace the example host with the URL provided during environment onboarding. security: [] tags: - description: >- Tenant-level setup: connecting the banking provider and configuring where status notifications are delivered. name: Admin - description: Issuing, querying and cancelling boletos, and retrieving the rendered PDF. name: Boletos - description: >- Aggregated counts, amounts and breakdowns over a period, for boletos and for payments. name: Dashboards - description: >- Paying bankslips, utility bills and DARF tax slips, and querying those payments. name: Payments - description: >- The webhook the payment provider posts settlement events to. Authenticated with a credential agreed with the provider, not with the platform identity used by the rest of this API. name: Settlement paths: /v1/boletos/batches: post: tags: - Boletos summary: Issue a batch of boletos description: >- 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/{batch_id} 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. operationId: createBoletoBatch parameters: - description: >- 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. in: header name: X-Organization-Id schema: description: >- 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. type: string - description: >- 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. in: header name: Idempotency-Key required: true schema: description: >- 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. type: string requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateBoletoBatchRequest' required: true responses: '202': content: application/json: schema: $ref: '#/components/schemas/BoletoBatchResponse' description: >- Accepted: the batch is recorded and its items are sent for issuance. Each item carries its position, its boleto and its status. '400': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Bad Request '401': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Authentication failed: the request carries no valid credential, or the credential does not identify a tenant. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0003`. Obtain a valid bearer token and send the request again. '403': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- The authenticated principal is not allowed to perform this request. The error body is an RFC 9457 problem document (`application/problem+json`) with error code `PBP-0004`: the principal lacks permission for this operation, and the permission has to be granted before the request can succeed. '404': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Not Found '409': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Conflict. While an earlier request under the same `Idempotency-Key` is still being processed, a request under that key is answered PBP-0007 and is not run. Send it again under the SAME key after a short wait: the key answers this code for at most five minutes after the earlier request arrived. Afterwards the same key answers with the earlier request's stored answer, with 500 PBP-0002 when that answer cannot be replayed, or, when no answer was kept, by running the request. Do not send it under a new key to get past this answer: the earlier request may still take effect. '413': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Request Entity Too Large '422': content: application/problem+json: schema: anyOf: - $ref: '#/components/schemas/BatchSizeProblem' - $ref: '#/components/schemas/BatchInvalidItemsProblem' - $ref: '#/components/schemas/Detail' description: Unprocessable Entity '500': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: Internal Server Error '503': content: application/problem+json: schema: $ref: '#/components/schemas/Detail' description: >- Service Unavailable. PBP-0008 means a dependency the request needs, authentication or the tenant's storage, is temporarily unavailable. The request was not processed; wait and send the same request again with the same Idempotency-Key. security: - BearerAuth: [] components: schemas: CreateBoletoBatchRequest: additionalProperties: false properties: items: description: >- 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. items: $ref: '#/components/schemas/CreateBoletoBatchItemRequest' type: array ledgerId: description: >- 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. type: string midazAccountId: description: >- 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. type: string required: - midazAccountId - items type: object BoletoBatchResponse: additionalProperties: false properties: batchId: description: Batch identifier. examples: - 0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b format: uuid type: string closed: description: >- 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. type: boolean counts: $ref: '#/components/schemas/BoletoBatchCounts' createdAt: description: When the batch was created, RFC 3339 in UTC. examples: - '2026-10-14T19:34:00Z' format: date-time type: string finished: description: >- 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. type: boolean items: description: >- Every item, in ascending position. Never paginated: a batch holds at most 25 items. items: $ref: '#/components/schemas/BoletoBatchItemResponse' type: - array - 'null' ledgerId: description: Ledger of the batch and of each item. examples: - 7c1e5b9a-3d2f-4a6b-8e0c-1f2a3b4c5d6e format: uuid type: string midazAccountId: description: Collection account of the batch and of each item. examples: - 3f9a2c1e-5b7d-4e8f-9a0b-1c2d3e4f5a6b type: string organizationId: description: >- Organization the batch was recorded with: always the organization of the X-Organization-Id header. examples: - 0f9d6c2a-1b3e-4f5a-8c7d-6e5f4a3b2c1d format: uuid type: string status: $ref: '#/components/schemas/BoletoBatchOutcome' required: - items - batchId - organizationId - ledgerId - midazAccountId - status - closed - finished - counts - createdAt type: object Detail: additionalProperties: true properties: code: description: >- Stable, machine-readable domain error code scoped to the emitting service (format: -NNNN). type: string detail: description: >- A human-readable explanation specific to this occurrence of the problem. examples: - Property foo is required but is missing. type: string errors: description: Optional list of individual error details items: $ref: '#/components/schemas/ErrorDetail' type: - array - 'null' instance: description: >- A URI reference that identifies the specific occurrence of the problem. examples: - https://example.com/error-log/abc123 format: uri type: string status: description: HTTP status code examples: - 400 format: int64 type: integer title: description: >- A short, human-readable summary of the problem type. This value should not change between occurrences of the error. examples: - Bad Request type: string type: default: about:blank description: A URI reference to human-readable documentation for the error. examples: - https://example.com/errors/example format: uri type: string upstream: $ref: '#/components/schemas/Upstream' description: >- RFC 9457 extension member: the error a proxied third-party provider reported. Absent unless the emitting service explicitly surfaced one. type: object BatchSizeProblem: allOf: - $ref: '#/components/schemas/Detail' - properties: code: enum: - PBP-0122 type: string maxItems: description: The most items a batch holds. enum: - 25 format: int64 type: integer receivedItems: description: The number of items sent. examples: - 26 format: int64 minimum: 0 type: integer required: - code - maxItems - receivedItems type: object description: '422 PBP-0122: the number of items is outside 1 to 25.' BatchInvalidItemsProblem: allOf: - $ref: '#/components/schemas/Detail' - properties: code: enum: - PBP-0123 type: string itemErrors: description: >- The problems of the items, by ascending position and, within an item, in the order of its members. items: $ref: '#/components/schemas/BatchItemError' minItems: 1 type: array required: - code - itemErrors type: object description: >- 422 PBP-0123: one or more items are invalid. The whole batch is refused, and nothing is recorded or sent for issuance. Every problem of every item comes at once, in two forms: errors[], the service's form for generic clients, with location body.items[]. and message; and itemErrors[], an extension member with the same problems, each with position, field and the item's code, to mark the member and translate the problem without reading the message. A refusal that holds for the whole batch (account, ledger, holder registration) prevails and comes under its own code, without the list. CreateBoletoBatchItemRequest: additionalProperties: false properties: amount: description: >- Amount as a decimal string, at most two decimal places, greater than zero. examples: - '150.00' maxLength: 32 type: string discount: $ref: '#/components/schemas/DiscountRequest' dueDate: description: Due date, YYYY-MM-DD. examples: - '2030-01-15' format: date type: string fine: $ref: '#/components/schemas/FineRequest' instructions: description: >- Instructions printed on the boleto, free text. Optional; the same member and rule as on POST /v1/boletos. examples: - Mensalidade de janeiro type: string interest: $ref: '#/components/schemas/InterestRequest' ourNumber: description: >- Bank-side identification of the boleto (nosso numero), chosen by the payee. Optional item by item: when absent, the number is assigned at issuance. Same form as on POST /v1/boletos: surrounding spaces are removed, a hyphen is accepted only when followed by exactly one digit, which is discarded, and leading zeros do not make a different number. Two items of the batch with the same number are an item problem PBP-0125 on both, and the batch is refused. A number already held by an active boleto of the same collection account does not refuse the batch: that item alone ends FAILED with errorCode PBP-0108, and the other items go on. examples: - '00000000152' type: string payer: $ref: '#/components/schemas/PayerRequest' type: description: >- Boleto type. Only TRADITIONAL is issued in a batch: HYBRID, QR_CODE or any other value is an item problem PBP-0006, reported in 422 PBP-0123 with every other problem of the batch. examples: - TRADITIONAL type: string required: - type - payer - amount - dueDate type: object BoletoBatchCounts: additionalProperties: false properties: canceled: description: Items CANCELED. examples: - 1 format: int64 minimum: 0 type: integer failed: description: Items FAILED. examples: - 1 format: int64 minimum: 0 type: integer inactivated: description: 'Items INACTIVATED: written off.' examples: - 0 format: int64 minimum: 0 type: integer overdue: description: >- Items still processing past the service's deadline (overdue: true). Never more than processing. examples: - 0 format: int64 minimum: 0 type: integer processing: description: Items PENDING, still being issued. examples: - 1 format: int64 minimum: 0 type: integer registered: description: 'Items CREATED: registered and available for payment.' examples: - 2 format: int64 minimum: 0 type: integer requested: description: 'Number of items requested: the size of the batch.' examples: - 5 format: int64 maximum: 25 minimum: 1 type: integer settled: description: 'Items SETTLED: paid.' examples: - 0 format: int64 minimum: 0 type: integer required: - requested - processing - registered - settled - canceled - inactivated - failed - overdue type: object BoletoBatchItemResponse: additionalProperties: false properties: amount: description: Requested amount, as a decimal string with two decimal places. examples: - '150.00' type: string boletoId: description: >- Identifier of the boleto this item produced: the id GET /v1/boletos/{id}, the PDF and the boleto cancellation take. format: uuid type: string cancelable: description: >- Same meaning as cancelable on GET /v1/boletos/{id}: true only for a CREATED item that carries a providerId. Always present. type: boolean discount: $ref: '#/components/schemas/DiscountResponse' dueDate: description: Requested due date. examples: - '2030-01-15' format: date type: string errorCode: description: >- Product code of the failure. Present only with status FAILED. The list is open; today PBP-0108 when the requested ourNumber is already in use, and PBP-0014 when the item was refused. examples: - PBP-0108 pattern: ^PBP-[0-9]{4}$ type: string errorMessage: description: >- Readable reason of the failure, present only with status FAILED. Written by this service; after provider reported ERROR it may carry, in parentheses, the error code the issuing bank sent. Translate it by errorCode. examples: - no title was issued for this emission maxLength: 500 type: string fine: $ref: '#/components/schemas/FineResponse' instructions: description: >- Instructions requested for the item. Absent when the item carried none. type: string interest: $ref: '#/components/schemas/InterestResponse' ourNumber: description: >- Bank-side identification of the item's boleto (nosso numero), read from the barcode with leading zeros, as GET /v1/boletos/{id} answers it. Absent while the provider has not produced the boleto. examples: - '00000000152' type: string ourNumberDigit: description: >- Check digit of ourNumber, computed by the bank, as GET /v1/boletos/{id} answers it. Absent whenever the provider did not return it. examples: - '3' type: string ourNumberHolderBoletoId: description: >- Boleto that held the requested ourNumber when the item collided with it on creation (errorCode PBP-0108). It may be an earlier issuance of the same charge, so read that boleto before requesting another number. Absent in every other case. type: string overdue: description: >- Whether the item is PENDING past the service's deadline. Derived on every read. It is not a failure: the item is still being processed. Always false outside PENDING. type: boolean payer: $ref: '#/components/schemas/PayerResponse' position: description: >- Position of the item in the request, from 0: its index in the request's items and in body.items[] of a refusal. Add 1 to show it as item n. examples: - 0 format: int64 maximum: 24 minimum: 0 type: integer providerId: description: >- Identifier the payment provider assigned to the item's boleto. Present only once the item is bound to a live boleto at the provider; absent while it is queued or being sent, and on FAILED. type: string requestedOurNumber: description: >- ourNumber requested for the item, in canonical form: no hyphen and no check digit. Absent when the item requested none, and on an item that failed with PBP-0108 on creation. Distinct from ourNumber, which reports the boleto. examples: - '00000000152' type: string status: description: >- Status of the item's boleto, the same GET /v1/boletos/{id} answers. PENDING covers an item queued, sent or still being processed; CREATED is a registered item with barcode and digitable line. An item becomes FAILED only once it is certain that no boleto was registered for it. enum: - PENDING - CREATED - SETTLED - CANCELED - INACTIVATED - FAILED examples: - CREATED type: string required: - position - boletoId - status - overdue - cancelable - amount - dueDate - payer type: object BoletoBatchOutcome: description: >- 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. enum: - CREATED - COMPLETED - PARTIAL_FAILURE - FAILED type: string ErrorDetail: additionalProperties: false properties: location: description: >- Where the error occurred, e.g. 'body.items[3].tags' or 'path.thing-id' type: string message: description: Error message text type: string value: description: The value at the given location type: object Upstream: additionalProperties: false properties: code: description: The upstream provider's own error code, verbatim. examples: - E4001 type: string message: description: >- The upstream provider's own error message, verbatim (bounded, never its raw response body). examples: - account not found at provider type: string type: object BatchItemError: additionalProperties: false properties: code: description: >- Code of the item's problem. An open list; today: PBP-0001 (form, size, presence, document, amount, due date, address), PBP-0006 (type not supported, HYBRID included, with the reason in message; charges), PBP-0119 (payer is the final beneficiary) and PBP-0125 (ourNumber repeated in the batch). It is the code the single boleto or the installment series gives the same condition, except the last, which is the batch's own. examples: - PBP-0125 pattern: ^PBP-[0-9]{4}$ type: string field: description: >- Path of the member inside the item, in dot notation (payer.address.zipCode, ourNumber, discount.limitDate). examples: - payer.address.zipCode type: string message: description: >- Human-readable message, in English like every message of the service. A client translates by code, never by this text. examples: - type HYBRID is not supported for batch issuance type: string position: description: Position of the item in the request, from 0. examples: - 1 format: int64 maximum: 24 minimum: 0 type: integer required: - position - field - code - message type: object DiscountRequest: additionalProperties: false properties: amount: description: >- Discount amount as a decimal string, greater than zero. For FIXED it is in BRL with at most 2 decimal places; for PERCENTAGE it is in percent (2.5 means 2.5%) with at most 6 decimal places. On a HYBRID boleto a PERCENTAGE amount accepts at most 2 decimal places, counted as written (2.500 carries three); more is refused with 422 PBP-0006 naming discount.amount. maxLength: 32 type: string limitDate: description: >- Last date the discount applies, YYYY-MM-DD. It must be on or after the day of issuance (Brazilian calendar) and before the due date: before dueDate on a single boleto, before firstDueDate on installments. A date outside that window is refused with 422 PBP-0006. examples: - '2029-12-31' format: date type: string type: description: >- Discount type, granted when the boleto is paid on or before limitDate. One of FIXED (amount in BRL, at most 2 decimal places) or PERCENTAGE (percent of the boleto's face value, at most 6 decimal places, 2 on a HYBRID boleto). Required when a discount is sent: an absent, empty or unlisted value is refused with 422 PBP-0006. A discount also requires amount and limitDate. type: string required: - amount - limitDate type: object FineRequest: additionalProperties: false properties: amount: description: >- Fine amount as a decimal string, greater than zero. For FIXED it is in BRL with at most 2 decimal places; for PERCENTAGE it is in percent (2.5 means 2.5%) with at most 6 decimal places. On a HYBRID boleto a PERCENTAGE amount accepts at most 2 decimal places, counted as written (2.500 carries three); more is refused with 422 PBP-0006 naming fine.amount. maxLength: 32 type: string type: description: >- Fine type, charged once when the boleto is paid after its due date. One of FIXED (amount in BRL, at most 2 decimal places) or PERCENTAGE (percent of the boleto's face value, at most 6 decimal places, 2 on a HYBRID boleto). Required when a fine is sent: an absent, empty or unlisted value is refused with 422 PBP-0006. type: string required: - amount type: object InterestRequest: additionalProperties: false properties: amount: description: >- Interest amount as a decimal string, greater than zero. For DAILY_FIXED it is in BRL per calendar day with at most 2 decimal places; for DAILY_PERCENTAGE and MONTHLY_PERCENTAGE it is in percent (1 means 1%) with at most 6 decimal places. On a HYBRID boleto a DAILY_PERCENTAGE or MONTHLY_PERCENTAGE amount accepts at most 2 decimal places, counted as written (1.500 carries three); more is refused with 422 PBP-0006 naming interest.amount. maxLength: 32 type: string type: description: >- Interest type, accrued for each calendar day the boleto is paid late. One of DAILY_FIXED (amount in BRL per calendar day late, at most 2 decimal places), DAILY_PERCENTAGE (percent of the boleto's face value per calendar day late, at most 6 decimal places, 2 on a HYBRID boleto) or MONTHLY_PERCENTAGE (percent of the boleto's face value per month, accrued per calendar day over a 30-day month, at most 6 decimal places, 2 on a HYBRID boleto). Required when interest is sent: an absent, empty or unlisted value is refused with 422 PBP-0006. type: string required: - amount type: object PayerRequest: additionalProperties: false properties: address: $ref: '#/components/schemas/AddressRequest' document: description: Payer CPF or CNPJ, digits only. type: string name: description: Payer full name. type: string required: - document - name type: object DiscountResponse: additionalProperties: false properties: amount: type: string limitDate: type: string type: type: string required: - type - amount - limitDate type: object FineResponse: additionalProperties: false properties: amount: type: string type: type: string required: - type - amount type: object InterestResponse: additionalProperties: false properties: amount: type: string type: type: string required: - type - amount type: object PayerResponse: additionalProperties: false properties: address: $ref: '#/components/schemas/AddressResponse' document: type: string name: type: string required: - name - document type: object AddressRequest: additionalProperties: false properties: city: type: string complement: type: string neighborhood: type: string number: type: string state: type: string street: type: string zipCode: type: string type: object AddressResponse: additionalProperties: false properties: city: type: string complement: type: string neighborhood: type: string number: type: string state: type: string street: type: string zipCode: type: string type: object securitySchemes: BearerAuth: bearerFormat: JWT description: JWT bearer token issued by the identity provider. scheme: bearer type: http ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.