Adopt the provider title of an installment

Operational action for an installment the emission conference did not adopt: PENDING, without a provider id, and already attempted. That covers an installment whose title the provider proved to exist, one withheld by a lapsed discount before its resend, and one attempted without either, for instance one whose resends the provider keeps refusing.

• The service reads the title at the provider by the providerId given and compares its clientRequestId, derived from the installment, its amount and its due date with the installment’s.
• All three match: the provider id is recorded on the installment and the acceptance sweep takes it to CREATED. The answer is 200 with the boleto, the body of GET /v1/boletos/{id}.
• Any of them differs, the provider has no title with that id, or the installment is not in that state: 422 PBP-0121, and nothing is written. The detail says which.
• Repeating the call with the same providerId on the installment it already adopted answers 200.

POST /v1/admin/boletos/{id}/adopt

Adopt the provider title of an installment

cURL

curl --request POST \
  --url https://api.example.com/v1/admin/boletos/{id}/adopt \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: <idempotency-key>' \
  --data '
{
  "providerId": "8c2f0b5e-1d3a-4c7e-9f6b-2a4d5e6f7a8b"
}
'

200

{
  "amount": "<string>",
  "cancelable": true,
  "createdAt": "<string>",
  "dueDate": "<string>",
  "id": "<string>",
  "kind": "<string>",
  "ledgerId": "<string>",
  "midazAccountId": "<string>",
  "organizationId": "<string>",
  "payer": {
    "document": "<string>",
    "name": "<string>",
    "address": {
      "city": "<string>",
      "complement": "<string>",
      "neighborhood": "<string>",
      "number": "<string>",
      "state": "<string>",
      "street": "<string>",
      "zipCode": "<string>"
    }
  },
  "status": "<string>",
  "type": "<string>",
  "updatedAt": "<string>",
  "barcode": "<string>",
  "batchId": "0192a3b4-c5d6-7e8f-9a0b-1c2d3e4f5a6b",
  "batchPosition": 3,
  "canceledAt": "<string>",
  "cancellationReason": "<string>",
  "digitableLine": "<string>",
  "discount": {
    "amount": "<string>",
    "limitDate": "<string>",
    "type": "<string>"
  },
  "errorMessage": "<string>",
  "excessPayments": [
    {
      "amount": "10.00",
      "detectedAt": "2023-11-07T05:31:56Z",
      "paidAt": "2023-11-07T05:31:56Z",
      "paidVia": "BOLETO",
      "providerReference": "<string>"
    }
  ],
  "failedAt": "<string>",
  "fine": {
    "amount": "<string>",
    "type": "<string>"
  },
  "guarantor": {
    "document": "<string>",
    "name": "<string>",
    "address": {
      "city": "<string>",
      "complement": "<string>",
      "neighborhood": "<string>",
      "number": "<string>",
      "state": "<string>",
      "street": "<string>",
      "zipCode": "<string>"
    }
  },
  "inactivatedAt": "<string>",
  "installmentLabel": "<string>",
  "instructions": "<string>",
  "interest": {
    "amount": "<string>",
    "type": "<string>"
  },
  "midazOperationId": "<string>",
  "ourNumber": "00000000029",
  "ourNumberDigit": "3",
  "paidVia": "BOLETO",
  "pixLocation": "pix.example.com/qr/v2/cobv/5d9a8e91c88c43db942d01a0ad92ffc3",
  "pixTxId": "35dabf21d3b941e8a937409b8749f281",
  "providerId": "<string>",
  "qrCode": "<string>",
  "seriesId": "<string>",
  "settledAmount": "<string>",
  "settledAt": "<string>"
}

Autorizações

Authorization · string · header · obrigatório

JWT bearer token issued by the identity provider.

Cabeçalhos

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.

Parâmetros de caminho

id · string<uuid> · obrigatório

Identifier of the installment's boleto (UUID).

Exemplo:

"01928f6e-7a1b-7c3d-9e4f-5a6b7c8d9e0f"

Corpo

application/json

providerId · string · obrigatório

The provider's id of the title.

Maximum string length: 64

Exemplo:

"8c2f0b5e-1d3a-4c7e-9f6b-2a4d5e6f7a8b"

Resposta

200

application/json

OK

amount · string · obrigatório

cancelable · boolean · obrigatório

Whether cancelling this boleto would effect a cancellation at the provider. Always present. Derived from the boleto's state, not from any request field: true only for a CREATED boleto that carries a providerId. An already-canceled boleto reads false even though POST /v1/boletos/{id}/cancel answers it 200 as an idempotent replay.

createdAt · string · obrigatório

dueDate · string · obrigatório

id · string · obrigatório

kind · string · obrigatório

Issuance form of the boleto: SINGLE for a standalone boleto, INSTALLMENT for an installment of a series, BATCH for an item of a batch, which carries batchId and batchPosition.

ledgerId · string · obrigatório

Midaz ledger the boleto was written with. Always present.

midazAccountId · string · obrigatório

Midaz account the boleto was issued for: the midazAccountId it was created with. The settlement credit of a settled boleto is posted to this account. Always present.

organizationId · string · obrigatório

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

payer · object · obrigatório

Show child attributes

status · string · obrigatório

type · string · obrigatório

updatedAt · string · obrigatório

barcode · string

batchId · string<uuid>

Batch the boleto was created in, as one of its items. Present only on a boleto of kind BATCH, absent on every other kind.

Exemplo:

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

batchPosition · integer<int64>

Position of the boleto in its batch, zero-based: the position of its item in the batch request. Present only on a boleto of kind BATCH, absent on every other kind.

Intervalo obrigatório: 0 <= x <= 24

Exemplo:

3

canceledAt · string

cancellationReason · string

digitableLine · string

discount · object

Show child attributes

errorMessage · string

excessPayments · object[]

Payments a SETTLED hybrid boleto received after it was settled, by the leg that did not settle it, when the provider attaches them to the boleto. A payment by that leg that the provider does not attach to the boleto reaches the collection account without being listed here. They are never credited: the boleto stays settled by the leg in paidVia. At most one is recorded per leg: a later payment by a leg already listed is not added. Only a hybrid boleto carries them, and the member is absent when there is none.

Maximum array length: 10

Show child attributes

failedAt · string

fine · object

Show child attributes

guarantor · object

Final beneficiary (sacador avalista) of the boleto: the holder of the issuing account, read from that account's registration data at issuance. It is a snapshot: a later change to the registration does not change it. Absent on boletos issued before the final beneficiary was derived.

Show child attributes

inactivatedAt · string

installmentLabel · string

instructions · string

interest · object

Show child attributes

midazOperationId · string

ourNumber · string

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.

Exemplo:

"00000000029"

ourNumberDigit · string

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}.

Exemplo:

"3"

paidVia · enum<string>

Leg by which the boleto was paid: BOLETO for a payment of its barcode or digitable line, PIX for a payment of a hybrid boleto's Pix QR code. Present only on a SETTLED boleto, absent on every other status. A traditional boleto is always paid by BOLETO. Set once, when the boleto settles: a later payment by the other leg does not change it and, when the provider attaches it to the boleto, is listed in excessPayments.

Opções disponíveis: BOLETO, PIX

pixLocation · string

Location of the hybrid boleto's dynamic Pix QR code, as issued. For support and diagnostics: to pay, the payer uses qrCode. Only a HYBRID boleto carries it, and it is served together with qrCode, under the same rule: absent while the boleto is PENDING or FAILED, present once it is CREATED and on every later status; absent on every other type.

Exemplo:

"pix.example.com/qr/v2/cobv/5d9a8e91c88c43db942d01a0ad92ffc3"

pixTxId · string

Identifier of the due-date Pix charge attached to a hybrid boleto. Only a HYBRID boleto carries it, and only once its issuance is confirmed; absent on every other type.

Exemplo:

"35dabf21d3b941e8a937409b8749f281"

providerId · string

Identifier the payment provider assigned to this boleto. Quote it when you contact the provider about this boleto.

qrCode · string

Pix copy-and-paste code of a HYBRID boleto's Pix charge: the payload behind its QR code, which the payer scans or pastes to pay by Pix. Served only after the provider has registered the boleto, so it is never paid into a boleto whose registration fails: absent while the boleto is PENDING or FAILED, and so from the 201 and the 202 of its creation, which answer it PENDING; present on the read once the boleto is CREATED, and on every later status. Absent on a type without a Pix charge.

seriesId · string

settledAmount · string

settledAt · string