Issue installment boletos

Creates a series of 2 to 36 independent boletos, one per installment, with totalAmount split evenly, the remainder going to the last installment, or with the amounts given in installmentAmounts. Installment k falls due on firstDueDate plus (k-1) times intervalDays days, with intervalDays from 1 to 365 and no business-day adjustment. The answer is immediate and nothing is issued in it: the series and its installments are recorded PENDING, and each installment is registered with the banking provider afterwards, one at a time. This answer always carries status CREATED and closed false; follow the series at GET /v1/boletos/installments/{series_id} and each installment at GET /v1/boletos/{id}. The organization comes from the X-Organization-Id header and the ledger from ledgerId, with the same refusals as POST /v1/boletos, and every installment is written with that pair. The account in midazAccountId must belong to that organization and ledger, and it is checked once per series. Nothing is recorded when a request is refused, and the refusals come in this order: 401 PBP-0003 and 403 PBP-0004 for authentication and authorization; the Idempotency-Key, 400 PBP-0012 when it is missing or malformed, 409 PBP-0007 while the original request is still running, and 422 PBP-0013 when the same key arrives with another body or under another organization; 400 PBP-0001 for a body that fails schema validation, including one that sends guarantor, which this operation does not accept, for installments or intervalDays of zero or less, and for an ourNumbers item that is not a number, named as ourNumbers[<i>] counted from 0; 400 PBP-0025 for the organization, then 400 PBP-0026 for the ledger; 400 PBP-0001 for a date or an amount that cannot be read; 422 PBP-0006 for a type a series does not carry, QR_CODE or HYBRID; 422 PBP-0102 for a payer document whose check digit fails or a first due date before today; 422 PBP-0006 for a refused fine, interest or discount; 422 PBP-0102 for intervalDays above 365, installments outside 2 to 36, an installmentAmounts list of another length, or an amount below 0.01 or with more than two decimal places; the numbers, when ourNumbers is present and not null: 422 PBP-0102 for an ourNumbers list that does not hold one number per installment, an empty one included, 422 PBP-0006 when the connected provider does not accept a number chosen by the payee, or 422 PBP-0017 when this instance has no provider to judge them by, 400 PBP-0001 for an ourNumbers item wider than the provider accepts, named as ourNumbers[<i>], and 422 PBP-0102 when two installments carry the same number, with the installments, counted from 1, in duplicateInstallmentNumbers; the account, 404 PBP-0005 when it does not exist or belongs to another organization or ledger, 422 PBP-0106 when account validation is not configured on this instance, and 503 PBP-0301 when the ledger credential is unavailable; the final beneficiary, established once per series, 503 PBP-0118 when the account holder's registration data cannot be read or reading it is not configured, 400 PBP-0116 when it is incomplete, 422 PBP-0117 when the holder cannot be a final beneficiary and 422 PBP-0119 when the payer is the holder; 422 PBP-0102 when installmentAmounts does not add up to totalAmount; only for a series with numbers, the provider account the numbers are reserved in, 422 PBP-0017 when this instance has no account discovery, 422 PBP-0014 when the provider refuses the lookup and 503 PBP-0015 when it does not answer; last, 422 PBP-0108 when a number is already held by an active boleto of this tenant on the same provider account, before the provider is called and with nothing of the series recorded, the problem carrying the installment as installmentNumber and, when the holder can be read, its id as ourNumberHolderBoletoId. A series without numbers never depends on the account discovery. A refusal releases the Idempotency-Key, and so do 503 PBP-0301, 503 PBP-0118 and 503 PBP-0015: a retry under the same key runs the request again.

POST /v1/boletos/installments

Issue installment boletos

cURL

curl --request POST \
  --url https://api.example.com/v1/boletos/installments \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "firstDueDate": "2030-01-15",
  "installments": 2,
  "intervalDays": 30,
  "midazAccountId": "<string>",
  "payer": {
    "document": "<string>",
    "name": "<string>",
    "address": {
      "city": "<string>",
      "complement": "<string>",
      "neighborhood": "<string>",
      "number": "<string>",
      "state": "<string>",
      "street": "<string>",
      "zipCode": "<string>"
    }
  },
  "type": "TRADITIONAL",
  "installmentAmounts": [
    "<string>"
  ],
  "ledgerId": "<string>",
  "ourNumbers": [
    "<string>"
  ],
  "totalAmount": "100.00"
}
'

201

{
  "boletos": [
    {
      "amount": "<string>",
      "dueDate": "<string>",
      "id": "<string>",
      "installmentLabel": "<string>",
      "installmentNumber": 123,
      "status": "PENDING",
      "errorMessage": "<string>",
      "ourNumber": "00000000029",
      "ourNumberDigit": "3"
    }
  ],
  "closed": true,
  "installmentsCount": 123,
  "ledgerId": "<string>",
  "organizationId": "<string>",
  "seriesId": "<string>",
  "status": "CREATED",
  "totalAmount": "<string>"
}

Autorizações

Authorization · string · header · obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

X-Organization-Id · string

Midaz organization the account and every installment live under. Required: a request without it, or with a value that is not a canonical UUID, is refused with 400 PBP-0025.

Idempotency-Key · string · obrigatório

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.

Corpo

application/json

firstDueDate · string<date> · obrigatório

Due date of the first installment, YYYY-MM-DD.

Exemplo:

"2030-01-15"

installments · integer<int64> · obrigatório

Number of installments.

Exemplo:

2

intervalDays · integer<int64> · obrigatório

Days between consecutive installments.

Exemplo:

30

midazAccountId · string · obrigatório

Midaz account the series settles into.

payer · object · obrigatório

Show child attributes

type · string · obrigatório

Boleto type applied to every installment.

Exemplo:

"TRADITIONAL"

discount · object

Show child attributes

fine · object

Show child attributes

installmentAmounts · string[] | null

Per-installment amounts, at most 36. When supplied, its length must match installments.

Maximum array length: 36

Maximum string length: 32

interest · object

Show child attributes

ledgerId · string

Midaz ledger the account lives in and every installment is written with. Required: absent, blank or not a canonical UUID is refused with 400 PBP-0026.

ourNumbers · string[] | null

Bank-side identification (nosso numero) chosen by the payee for each installment: one number per installment, in installment order, at most 36. All or none: when absent or null, the provider assigns every number, and an empty list is refused with 422 PBP-0102, as is a list of another length. Each item follows the rule of ourNumber on POST /v1/boletos: surrounding spaces are removed, a hyphen is accepted only when followed by exactly one digit, which is discarded, and any other character that is not a digit is refused; the accepted width is set by the connected provider (11 significant digits for the current one). A format or width refusal answers 400 PBP-0001 naming the item as ourNumbers[], counted from 0. Two installments with the same number, leading zeros ignored, are refused with 422 PBP-0102, and the problem carries the installments, counted from 1, as duplicateInstallmentNumbers. A number already held by an active boleto of this tenant on the same provider account refuses the whole series with 422 PBP-0108 before the provider is called, and the problem carries the installment as installmentNumber and, when the holder can be read, its id as ourNumberHolderBoletoId. Only a series with numbers depends on the provider account discovery: 422 PBP-0017 when this instance has none, 422 PBP-0014 when the provider refuses it and 503 PBP-0015 when the provider does not answer.

Maximum array length: 36

totalAmount · string

Series total as a decimal string. Optional: either this or installmentAmounts must be supplied.

Maximum string length: 32

Exemplo:

"100.00"

Resposta

201

application/json

Created

boletos · object[] | null · obrigatório

Show child attributes

closed · boolean · obrigatório

Whether no installment of the series can still be paid: true when every installment is SETTLED, CANCELED, INACTIVATED or FAILED. Always present. It can return to false when the provider reverts the cancellation of an installment.

installmentsCount · integer<int64> · obrigatório

ledgerId · string · obrigatório

Midaz ledger the installments were written with. Always present.

organizationId · string · obrigatório

Midaz organization the installments were written with. Always present, and always the organization of the X-Organization-Id header.

seriesId · string · obrigatório

status · enum<string> · obrigatório

Emission outcome of the series, derived from its installments on every read. CREATED: some installment has no emission outcome yet. COMPLETED: every installment has an outcome and none is FAILED. PARTIAL_FAILURE: every installment has an outcome and some, not all, are FAILED; those carry errorMessage. FAILED: every installment is FAILED. It does not depend on payment, cancellation or write-off, and it can move from COMPLETED to PARTIAL_FAILURE or FAILED when the provider later refuses an accepted installment: a client waiting for the final outcome reads closed.

Opções disponíveis: CREATED, COMPLETED, PARTIAL_FAILURE, FAILED

totalAmount · string · obrigatório