跳到主要内容

创建指令批次

通过单次请求，对多个不同的 Boleto 提交同一类型的指令（注销、折扣、展期、抗议等）。QI Tech 会对整个批次进行校验，要么所有项均被接受，要么全部不予处理。

  • 若任一项未通过语义校验，则该批次所有项均不会被处理。错误响应会逐项说明拒绝原因。
  • 若所有项均通过校验，相应的事件将异步创建并逐一处理。每当事件状态变更时，系统将通过 webhook 通知请求方。
幂等性

批次级的 request_control_key 保证幂等性：重复使用同一密钥再次发送，将返回已创建的批次，不会重复创建。

每个项目也拥有自己的 request_control_key，并在项目级别保持幂等性。若再次使用已使用过的 request_control_key 提交项目，整个批次将被拒绝。

注意！

本操作仅适用于注册在 QI SCD 注册机构下的钱包。

Request​

ENDPOINT
/v2/bank_slip/account/ACCOUNT_KEY/requester_profile/REQUESTER_PROFILE_KEY/occurrence_batches
MÉTODO
POST

路径参数​

字段类型描述字符数
account_keyuuidv4账户唯一识别密钥，格式为 uuid v436
requester_profile_keyuuidv4钱包唯一识别密钥，格式为 uuid v436
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​

字段类型描述字符数
request_control_key *string客户定义的批次唯一密钥，用于保证批次的幂等性1–64
occurrence_type *string应用于所有项目的指令类型。详见 occurrence_type 枚举-
items *item 对象 数组指令列表（最少 1 项，最多 10000 项）-

occurrence_type 枚举​

枚举值描述
extension到期日延期 —— 每项需提供 new_due_date
rebate应用折扣 —— 每项需提供 rebate_amount
cancel_rebate取消已应用的折扣
write_off注销 Boleto
protest_request抗议申请
protest_cancel_request撤回待处理的抗议申请
protest_remove_request删除（取消）已登记的抗议

item 对象​

字段类型描述字符数
bank_slip_key *uuidv4指令将应用的 Boleto 密钥36
request_control_key *string客户定义的项目唯一密钥，用于保证项目级幂等性1–64
new_due_datestring新的到期日（YYYY-MM-DD）。当 occurrence_type=extension 时必填10
rebate_amountfloat折扣金额。当 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​

字段类型描述字符数
batch_key *uuidv4批次唯一密钥，用于查询批次详情36
occurrence_quantity *integer批次中发送的总项目数-
accepted_quantity *integer批次中被接受的项目数-
semantic_errors *array成功时为空数组。语义校验失败时请参阅 Error Response-

Error Response​

STATUS
4xx
Response Body: Error
{
  "title": "标题",
  "description": "description in English",
  "translation": "descrição em português",
  "code": "代码",
  "extra_fields": {}
}

语义校验失败时（BLP000112），响应中的 reasons 字段会列出每个被拒绝的项目：

Response Body: 语义校验失败
{
  "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[] 对象字段​

字段类型描述
occurrence_sequence *string项目在请求 items 数组中的位置（从 "0" 开始）
bank_slip_key *uuidv4被拒项目对应的 Boleto 密钥
request_control_key *string客户为该项目提供的控制密钥
errors *array拒绝原因列表（同一项目可能存在多个原因）
errors[].reason_code *string拒绝原因代码（Febraban 标准）
errors[].translation_pt_brstring原因的葡萄牙语描述
errors[].translation_en_usstring原因的英语描述
errors[].created_atstring原因在目录中的登记日期

错误代码​

HTTP 代码
status		QI 代码
code		标题
title		描述（英）
description		描述（葡）
translation
400QIT000001Bad RequestSchema ErrorSchema Inválido
400BKS000141Bad RequestBank slip registration is restricted to QI SCD.Registro de boleto permitido apenas para QI SCD.
404BKS000013Not FoundRequester profile not foundCarteira não encontrada
409BKS000014ConflictRequest control key already sent or duplicated sent: <request_control_key>Chave de controle da requisição já utilizada ou enviada duplicada: <request_control_key>
422BLP000112Unprocessable EntityRejected RemittanceRemessa Rejeitada