Issue a single boleto
Creates a new TRADITIONAL boleto via the banking provider. HYBRID (BolePix) and QR_CODE are out of V1 and are refused with 422 PBP-0006. A nosso numero already held by an active boleto of the same provider account is refused with 422 PBP-0108 before the provider is called. When that holder can be read, the PBP-0108 detail names the boleto that holds the number, and the problem carries its id as ourNumberHolderBoletoId. When it is an earlier emission still without the provider’s answer, the detail says so and does not ask for another number, because that emission can still become a live boleto; when it is a boleto the provider already answered, the detail asks for it to be consulted before another number is informed, because it may be an earlier emission of the same charge whose answer was lost. When a title the local index cannot see holds the number — for example, one issued through another deployment or another tenant sharing the provider account — the provider accepts the emission and refuses it later, and the boleto moves to FAILED, unless the title holding the number belongs to this same emission, in which case the boleto is bound to that title. The boleto stays PENDING instead when the provider’s search cannot tell whose title holds the number — it lists a live title with that number that it attributes to no emission, more than one title of this same emission, or one of this emission without the provider’s identifier or that disagrees with the boleto — or when the search could not be made or read whole; it also stays PENDING, transiently, while the search does not answer or is postponed to a later reconciliation pass.
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. Declared optional on the schema so that refusal keeps its own code instead of the schema's PBP-0001.
Client-supplied idempotency key. Required in practice even though the schema marks it optional: a request that omits this header is refused with 400 PBP-0012.
Body
Amount as a decimal string, at most two decimal places.
32"100.00"
Due date, YYYY-MM-DD.
"2030-01-15"
Midaz account the boleto settles into.
Boleto type. Only TRADITIONAL is supported in V1. HYBRID (BolePix) and QR_CODE are refused with 422 PBP-0006.
"TRADITIONAL"
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.
Bank-side identification of the boleto (nosso numero), chosen by the payee. Optional: when absent, the provider assigns the number. Surrounding spaces are removed. A hyphen is accepted only when followed by exactly one digit, which is discarded because the check digit is always computed by the bank: 152-3 is sent as 152, while 152- and 152-abc are refused. Any other character that is not a digit is refused. Leading zeros do not make a different number: 152 and 00000000152 are the same number for the current provider, and two active boletos of the same provider account cannot hold it at the same time, whatever their amount or due date. The accepted width is set by the connected provider (11 significant digits for the current one). Format and width refusals answer 400 PBP-0001; a provider that does not accept a number chosen by the payee refuses the field with 422 PBP-0006. A number already held by an active boleto of the same provider account is refused with 422 PBP-0108 before the provider is called. When the holder can be read, the PBP-0108 detail names the boleto that holds the number, and the problem carries its id as ourNumberHolderBoletoId; when it is an earlier emission that has no answer from the provider yet, the detail says so instead of asking for another number; otherwise it asks for that boleto to be consulted before another number is informed, because it may be an earlier emission of the same charge. After a 422 PBP-0014, or a 5xx, answered to an emission with ourNumber, the number can stay held until the periodic reconciliation resolves that emission, which it does not do before a grace period set by the deployment (30 minutes by default); meanwhile that emission can still become a live boleto, and issuing the same charge again with another number can leave two boletos for it.
"00000000152"
Response
Created
Midaz ledger the boleto was written with. Always present.
Midaz organization the boleto was written with. Always present.
Bank-side identification of the boleto (nosso numero), as assigned by the provider and printed on the instrument. Read from the barcode and returned in the instrument's form, with leading zeros: the width is set by the connected provider (11 digits for the current one). When the payee supplied ourNumber on issuance, this field still reports the instrument and not the value supplied: if the two differ, the value here is the one printed on the boleto, and the divergence is recorded by the service. Optional: absent for boletos issued before this field existed, and absent while the provider has not produced a valid barcode. Absence means not yet known; the periodic reconciliation fills it in once the provider produces the instrument, with no action needed from the client; it is never sent as an empty string.
"00000000029"
Check digit of ourNumber, computed by the bank and never accepted in a request. Optional: absent whenever the provider did not return it, in which case ourNumber is presented alone, with no trailing hyphen. It is absent in particular when the payee supplied ourNumber: the current provider returns the digit only for numbers it assigned itself. When present, the canonical presentation is {ourNumber}-{ourNumberDigit}.
"3"