Create instruction batch

Allows sending, in a single request, multiple instructions of the same type (write-off, rebate, extension, protest, etc.) over distinct bank slips. QI Tech validates the whole batch and either accepts every item or processes none.

• If any item fails semantic validation, no items in the batch are processed. The error response details, per rejected item, the reason for rejection.
• If every item passes, the occurrences are created and processed individually, asynchronously. The requester is notified via webhook as each occurrence changes status.

Idempotency

The batch-level request_control_key guarantees idempotency: resending the same key returns the batch already created, without duplication.

Each item also has its own request_control_key and is individually idempotent. Resending an item with a request_control_key already used makes the entire batch be rejected.

Attention!

This operation is only available for wallets registered with the QI SCD registration institution.

Request

ENDPOINT

/v2/bank_slip/account/ACCOUNT_KEY/requester_profile/REQUESTER_PROFILE_KEY/occurrence_batches

METHOD

POST

Path parameters

Field	Type	Description	Characters
account_key	uuidv4	Unique account identification key, in uuid v4 format	36
requester_profile_key	uuidv4	Unique wallet identification key, in uuid v4 format	36

Request Body

{
  "request_control_key": "614a451d-3b82-460e-bcc0-2caf3dde711f",
  "occurrence_type": "extension",
  "items": [
    {
      "bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5",
      "request_control_key": "c86d8902-a5ae-4d1f-8872-e6fea1268aab",
      "new_due_date": "2026-08-15"
    },
    {
      "bank_slip_key": "5e3a1b2c-7d9f-4e88-9012-3a4b5c6d7e8f",
      "request_control_key": "b3a428fd-58ee-4d6f-8872-633874ebf5e2",
      "new_due_date": "2026-08-20"
    }
  ]
}

Request Body Params

Field	Type	Description	Characters
request_control_key *	string	Unique batch key, defined by the client. Ensures batch idempotency	1–64
occurrence_type *	string	Instruction type applied to every item. See occurrence_type enumerators	-
items *	Array of item object	List of instructions (minimum 1, maximum 10000)	-

occurrence_type enumerators

Enumerator	Description
extension	Due-date extension — requires new_due_date on each item
rebate	Apply rebate — requires rebate_amount on each item
cancel_rebate	Cancel a previously applied rebate
write_off	Write off the bank slip
protest_request	Protest request
protest_cancel_request	Withdraw a pending protest request
protest_remove_request	Remove (cancel) a registered protest

item object

Field	Type	Description	Characters
bank_slip_key *	uuidv4	Key of the bank slip the instruction will be applied to	36
request_control_key *	string	Unique item key, defined by the client. Ensures per-item idempotency	1–64
new_due_date	string	New due date (YYYY-MM-DD). Required when occurrence_type=extension	10
rebate_amount	float	Rebate amount. Required when occurrence_type=rebate	-

Response

STATUS

201

Response Body

{
  "batch_key": "f2d3e1b9-4a5c-46e7-8f12-9a8b7c6d5e4f",
  "occurrence_quantity": 2,
  "accepted_quantity": 2,
  "semantic_errors": []
}

Response Body Params

Field	Type	Description	Characters
batch_key *	uuidv4	Unique batch key. Use it to query the batch detail	36
occurrence_quantity *	integer	Total number of items sent in the batch	-
accepted_quantity *	integer	Number of items accepted in the batch	-
semantic_errors *	array	Empty array on success. On semantic rejection, see Error Response	-

Error Response

STATUS

4xx

Response Body: Error

{
  "title": "title",
  "description": "description in English",
  "translation": "descrição em português",
  "code": "code",
  "extra_fields": {}
}

On semantic rejection (BLP000112), the reasons field of the response details every rejected item:

Response Body: Semantic rejection

{
  "title": "Unprocessable Entity",
  "description": "Rejected Remittance",
  "translation": "Remessa Rejeitada",
  "code": "BLP000112",
  "reasons": [
    {
      "occurrence_sequence": "0",
      "bank_slip_key": "960f78d4-4426-4762-98da-3ce3713ae0a5",
      "request_control_key": "c86d8902-a5ae-4d1f-8872-e6fea1268aab",
      "errors": [
        {
          "reason_code": "15",
          "translation_pt_br": "Boleto não encontrado",
          "translation_en_us": "Bank slip not found",
          "created_at": "2026-06-09T17:08:33"
        }
      ]
    }
  ]
}

reasons[] object fields

Field	Type	Description
occurrence_sequence *	string	Item position in the request's items array (starting at "0")
bank_slip_key *	uuidv4	Bank slip key of the rejected item
request_control_key *	string	Item's client-provided control key
errors *	array	List of rejection reasons (an item may have multiple)
errors[].reason_code *	string	Rejection reason code (Febraban standard)
errors[].translation_pt_br	string	Portuguese description of the reason
errors[].translation_en_us	string	English description of the reason
errors[].created_at	string	Catalog registration date of the reason

Error codes

HTTP code status	QI code code	Title title	Description (eng) description	Description (pt-br) translation
400	QIT000001	Bad Request	Schema Error	Schema Inválido
400	BKS000141	Bad Request	Bank slip registration is restricted to QI SCD.	Registro de boleto permitido apenas para QI SCD.
404	BKS000013	Not Found	Requester profile not found	Carteira não encontrada
409	BKS000014	Conflict	Request control key already sent or duplicated sent: <request_control_key>	Chave de controle da requisição já utilizada ou enviada duplicada: <request_control_key>
422	BLP000112	Unprocessable Entity	Rejected Remittance	Remessa Rejeitada