跳到主要内容

商业票据（NC）书写 API 集成路线图 — 自动签署

本路线图描述了集成合作伙伴在进入生产环境发行商业票据（NC）之前，需要在 QI Tech 沙盒环境中测试的所有资源和功能。

这是 QI Tech 标准 NC 集成路线图的定制版本，针对全自动发行流程进行了调整：一旦发行人完成登记、审核通过并启用自动签署，此后的每一笔发行都通过 API 端到端运行，无需人工签署环节。

注意

所有测试必须强制在 QI Tech 沙盒环境中进行。在沙盒环境中执行的操作均为虚拟金融操作，仅用于 API 功能测试。

1. 范围与阶段划分​

流程分为六个阶段。阶段 0 至 4 依赖 API 中已有的功能。自动签署启用阶段（阶段 2）依赖 QI Tech 侧的新开发。阶段 6 分为两部分：向 WL 清算账户划转资金（6.1）使用已存在的 BaaS 端点，今天即可完成同质化；向供应商付款（6.2）依赖新开发。

图例含义
✅现已可用 — 可立即在沙盒环境中完成同质化
🆕新开发 — 端点契约待发布；发布后开始同质化
⚙️由 QI Tech 执行（集成方无需操作，但必须观察由此产生的状态）
*同质化验收的必测步骤
顺序前提

自动签署仅在发行人登记审核通过后才能配置，但可以（也应当）在第一笔发行之前完成。加入协议在独立的签署信封中、通过独立的链接签署，与任何操作无关：无需先创建 NC 即可启用，也不存在必须先走一次的"人工发行"。因此阶段 2 是每个发行人一次性的关口，而非每笔操作都要执行的步骤 — 只要在第一笔发行前完成，该发行人的所有发行（含第一笔）都将自动签署。

2. 端到端流程​

3. 阶段 0 — 注册与 API 认证​

代码步骤描述文档链接前提条件状态
CAB0001*公钥交换与平台运营团队（suporte-dcm@qitech.com.br）进行公钥交换文档链接—✅
CAB0002*调用认证测试获取 API 密钥后，完成调用认证测试文档链接

文档链接		CAB0001✅
CAB0003*Webhooks 配置配置 QI Tech 发送 webhooks 的 URL文档链接

文档链接

文档链接		CAB0001、CAB0002✅
注意

在本流程中，webhooks 配置是强制性的，而非可选项。由于分析、审核和签署均为自动执行，集成方没有任何人工确认节点 — webhooks 是在不轮询的情况下观察操作进展的唯一途径。

4. 阶段 1 — 发行人同质化​

注意

如果客户已完成与 QI Tech 出让人登记系统的集成，可以重复使用这些登记，从而大幅简化系统中的同质化流程。

4.1 阶段 1A — 已在 QI Tech 出让人系统中登记的发行人​

代码步骤描述文档链接前提条件状态
CED1001*重用出让人登记通过 CNPJ 重用已有的出让人登记文档链接CAB0002✅
CED1002*列出已登记的发行人按 CNPJ 或名称筛选，列出已登记的发行人文档链接CED1001✅
CED1003*发行人详情通过 issuer_key 查询已登记发行人的详细信息文档链接CED1001✅

4.2 阶段 1B — 通过本系统登记的发行人​

代码步骤描述文档链接前提条件状态
CED0001*发行人基础登记使用基础登记数据创建发行人文档链接CAB0002✅
CED0002*上传 / 删除发行人文件为已登记的发行人添加和删除关联文件文档链接

文档链接		CED0001✅
CED0003*登记 / 删除发行人代表为已登记的发行人添加和删除关联代表文档链接

文档链接		CED0001✅
CED0004*上传 / 删除代表文件为已登记发行人的代表添加和删除关联文件文档链接

文档链接		CED0001、CED0003✅
CED0005*登记 / 删除发行人银行账户为已登记的发行人添加和删除关联银行账户文档链接

文档链接		CED0001✅
CED0006*登记 / 删除发行人签署人组为已登记的发行人添加和删除关联签署人组文档链接

文档链接		CED0001、CED0003✅
CED0007*登记 / 删除发行人联系信息为已登记的发行人添加和删除关联联系信息文档链接

文档链接		CED0001✅
CED0008*提交发行人进行分析将发行人转入分析状态，送入校验流程文档链接CED0001 → CED0007✅
CED0009*变更发行人登记重新开放发行人以供编辑文档链接CED0001 → CED0007✅
CED0010*列出已登记的发行人按 CNPJ 或名称筛选，列出已登记的发行人文档链接CED0001✅
CED0011*发行人详情通过 issuer_key 查询已登记发行人的详细信息文档链接CED0001✅
通往阶段 2 的关口

在 CED0006 中登记的签署人组决定了由哪位代表代表发行人签署。同一位代表也是在阶段 2 中签署自动签署加入协议的人，私有证书所代表的正是其权限。请在提交发行人进行分析之前正确登记 — 事后变更需要重新执行阶段 2。

5. 阶段 2 — 启用自动签署 ✅​

本阶段每个发行人只执行一次，在发行人登记审核通过之后立即进行，最终产出一张 QI Tech 私有证书，其适用范围严格限定于本次集成的 NC 文件。

由集成方发起启用申请。 该 POST 请求仅在发行人登记审核通过后才被接受，不存在自动创建。客户须已开通自动签署功能 — 该功能由 QI Tech 按客户开通，并包含加入协议模板的配置。

该申请会一并开启签署信封。 生成加入协议与创建信封均在该调用内完成，响应状态即为 pending_signature 并带有 envelope_key — 随后即可查询签署链接，无需等待 webhook。

加入协议授权的内容。 该协议授予 QI Tech 一项有限授权，用于签发并保管一张在 CertifiQI 中释放的内部私有证书，且仅可用于代表发行人签署本 NC 流程中的文件 — 绝不可用于任何其他文件、产品或交易对手。该协议由发行人登记的签署人组一次性签署 — 每位签署人都会获得各自专属的签署链接。

签署时点。 该协议拥有独立的签署信封与签署链接，在启用时生成，且与任何操作无关。发行人审核通过后即可签署，即在第一笔发行之前 — 这也是推荐路径，因为这样发行人在发起第一笔操作时自动签署就已处于生效状态。若操作创建时阶段 2 尚未完成，该笔操作会像其他非 enabled 状态的发行人一样，走 QI SIGN 人工回退路径。

代码步骤描述文档链接前提条件状态
ASG0001*为客户开通自动签署QI Tech 为客户开通自动签署并配置加入协议模板。未开通时，该客户下的任何发行人都不会创建自动签署文档链接—⚙️
ASG0002*申请启用对已审核通过的发行人调用 POST /issuer_management/issuer/{issuer_key}/auto_signature。同一次调用即生成加入协议并开启签署信封：返回的 issuer_auto_signature_key 与 envelope_key 状态已为 pending_signature。若发行人未审核通过，则以 ISS0000032 拒绝文档链接ASG0001、CED0011 或 CED1003✅
ASG0003Webhook — 协议已送签接收状态为 pending_signature 的 issuer_management.auto_signature_status_change webhook。它确认 ASG0002 响应中已返回的内容，并通知该租户的其他消费方文档链接CAB0003、ASG0002✅
ASG0004*查询签署链接GET .../auto_signature/signers 按签署人返回各自的链接与签署状态。请引导发行人的每一位签署人访问其专属链接。这些链接与任何操作无关 — 可在第一笔发行之前使用文档链接ASG0002✅
ASG0005*Webhook — 自动签署已生效接收状态为 enabled 的 webhook，确认协议已签署且发行人已启用自动签署文档链接CAB0003、ASG0004✅
ASG0006*查询自动签署状态通过 issuer_key 查询启用情况，确认已转为 enabled，并查看事件历史。在达到该状态之前，任何 NC 都不得依赖自动签署文档链接ASG0002✅
ASG0007私有证书签发QI Tech 创建私有证书并在 CertifiQI 中释放，范围限定于该发行人的 NC 文件。目前为人工操作（每个发行人一次，由 QI Tech 执行）；自动化已列入路线图，不阻塞上线—ASG0005⚙️
ASG0008取消自动签署取消启用状态 — 在签署人组变更或发行人提出要求时需要执行。需向 QI Tech 提出，暂无公开端点。取消后，发行恢复为人工签署流程，直至重新申请启用—ASG0006⚙️
自动取消

当发行人离开 approved 状态时（即转为 reproved、expired 或 canceled），自动签署会被自动取消。登记重新审核通过后，需要重新完成启用流程。

5.1 启用状态机​

状态含义新 NC 的签署行为
无自动签署记录从未申请启用，或客户未开通人工签署（QI SIGN）
pending_term_generation已申请启用；加入协议尚未生成人工签署
pending_signature协议已生成并送签；各签署人链接可用人工签署 — 协议通过各自专属链接签署，与操作无关
enabled协议已签署；发行人已启用自动签署自动
reproved协议信封被拒签、取消或已过期人工签署（QI SIGN）
canceled启用已被取消人工签署（QI SIGN）
同质化要求

集成方必须在沙盒环境中证明：其系统在创建操作前会读取启用状态，并在两个方向上正确路由 — 状态为 enabled 时走自动签署，其余所有状态走 QI SIGN 回退路径（COM0015 / COM0016）。任何假定状态恒为 enabled 的集成，都会在阶段 2 尚未完成的发行人上出错。

6. 阶段 3 — 投资人同质化​

注意

如果客户使用固定基金，可以在初始配置阶段完成登记，从而大幅简化集成。 对本流程而言，固定基金路径是预期的配置方式。

6.1 在初始配置阶段登记的投资人 — 推荐路径​

代码步骤描述文档链接前提条件状态
INV1001*列出已登记的投资人按 CNPJ 或名称筛选，列出已登记的基金文档链接CAB0002✅
INV1002*投资人详情通过 investor_key 查询已登记投资人的详细信息文档链接CAB0002✅

6.2 通过本系统登记的投资人 — 仅在不使用固定基金时适用​

代码步骤描述文档链接前提条件状态
INV0001*投资人基础登记使用基础登记数据创建投资人文档链接CAB0002✅
INV0002*上传 / 删除投资人文件为已登记的投资人添加和删除关联文件文档链接

文档链接		INV0001✅
INV0003*登记 / 删除投资人代表为已登记的投资人添加和删除关联代表文档链接

文档链接		INV0001✅
INV0004*上传 / 删除代表文件为已登记投资人的代表添加和删除关联文件文档链接

文档链接		INV0001、INV0003✅
INV0005*登记 / 删除投资人银行账户为已登记的投资人添加和删除关联银行账户文档链接

文档链接		INV0001✅
INV0006*登记 / 删除投资人签署人组为已登记的投资人添加和删除关联签署人组文档链接

文档链接		INV0001✅
INV0007*登记 / 删除投资人联系信息为已登记的投资人添加和删除关联联系信息文档链接

文档链接		INV0001✅
INV0008*提交投资人进行分析将投资人转入分析状态，送入校验流程文档链接INV0001 → INV0007✅
INV0009*变更投资人登记重新开放投资人以供编辑文档链接INV0001 → INV0007✅
INV0010*列出已登记的投资人按 CNPJ 或名称筛选，列出已登记的基金文档链接INV0001✅
INV0011*投资人详情通过 investor_key 查询已登记投资人的详细信息文档链接INV0001✅

7. 阶段 4 — NC 发行​

发行人和投资人登记完成后，即可发行商业票据。通过 API 发行是本次集成的核心前提：基于页面的操作流程无法支撑预期的业务量。

7.1 创建操作​

代码步骤描述文档链接前提条件状态
COM0001*模拟财务条件模拟一笔操作的财务条件与还款计划文档链接CAB0002✅
COM0002*创建 NC 操作根据财务数据和投资人数据创建一笔新的商业票据操作文档链接COM0001、CED0011/CED1003、INV1002✅
COM0003*登记 / 删除关联方为一笔操作添加和删除关联方文档链接COM0002✅
COM0004*上传 / 删除关联方代表文件为关联方代表添加和删除关联文件文档链接COM0002、COM0003✅
COM0005*登记 / 删除关联方签署人组为关联方代表添加和删除关联签署人组文档链接COM0002、COM0003✅
COM0006预览设立条款依据预定义模板生成某笔操作的设立条款草稿文档链接COM0002✅
COM0007*变更设立条款模板变更某笔操作所使用的设立条款模板文档链接COM0002✅
COM0008*上传文件上传与操作关联的文件。返回的 document_key 可用于例如担保系统文档链接COM0002✅
COM0009*登记担保为一笔操作添加担保文档链接COM0002、COM0008✅
COM0010*登记 / 删除合同或担保的关联方为操作中某份具体合同或担保添加和删除关联方文档链接COM0002、COM0003✅
COM0011*提交操作进行分析将操作转入"分析中"，送入合规校验流程文档链接COM0002 → COM0009✅
COM0012*提交已签署的批准会议纪要针对 SA 或 COP 类型发行人，以 base64 载荷提交外部签署的批准会议纪要，由系统分析并批准文档链接COM0002✅
COM0013*按筛选条件查询操作使用可选筛选条件查询商业票据操作文档链接COM0002 → COM0009✅
COM0014*按键值查询操作使用唯一键值查询某笔具体操作的完整详情文档链接COM0002 → COM0009✅
COM0024*在创建时声明第三方收款方在创建操作的请求体中发送 third_party_disbursement，表示释放的金额将支付给供应商，而不是支付到发行人的清算账户。需先开通该功能文档链接COM0002⚙️ 🆕
COM0025*变更第三方收款方替换仍处于 in_filling 状态的操作的第三方拨付指令 — 在 TED、boleto 与 Pix 之间切换，或更正收款方信息文档链接COM0002⚙️ 🆕
第三方拨付 — 需申请开通的功能 🆕

该功能默认不开通；集成前请先向 QI Tech 申请开通。未开通时，创建操作会以 COM000062 被拒绝，且不会保存任何数据。

三条互斥的通道：

  • TED — payment_method: "ted"，配合 target_account。
  • Boleto — payment_method: "bank_slip"，配合 47 位的 digitable_line，其最后 10 位数字（以分为单位）必须正好等于操作的 released_amount。
  • Pix 🆕 — payment_method: "pix"，配合 pix_key 与 pix_key_type（cpf、cnpj、phone、email 或 evp）。CPF 与 CNPJ 的密钥传输时不带格式符号。

在 TED 与 boleto 通道中，收款方由付款信息本身标识。由于 Pix 密钥无法说明收款人是谁，Pix 通道还要求提供 beneficiary 对象 🆕 — 第三方的完整资格信息，字段与关联方相同，用于在公司会议纪要中记录该笔付款。该对象在 TED 与 boleto 通道中也可选提供。

收款方信息随操作一起流转，并与操作一同被签署。付款在拨付时自动执行 — 无需调用任何付款端点（见 §9.2）。

7.2 签署 — 自动路径（自动签署状态为 enabled 的发行人）🆕​

代码步骤描述文档链接前提条件状态
COM0020*自动审核通过在自动签署已生效且业务条件已预先批准的情况下，操作从分析状态自动转为已批准，无需人工介入。集成方通过 webhook 观察该状态转换文档链接 （待发布）COM0011、ASG0006⚙️ 🆕
COM0021*设立条款自动签署QI Tech 使用在 CertifiQI 中释放的私有证书代表发行人签署设立条款。不会为发行人生成签署链接文档链接 （待发布）COM0020⚙️ 🆕
COM0022*Webhook — 操作已签署接收确认该操作的所有签署均已完成的 webhook文档链接CAB0003、COM0021🆕
COM0023*查询已签署文件通过唯一键值查询该操作的已签署文件，包括签署证据报告文档链接COM0022✅
COM0026*客户接受日志上传以 base64 负载的形式，向操作附加包含最终客户接受证据的 PDF。上传为可选项，仅在 in_filling 状态下、且发行人的自动签署为 enabled 时才被接受文档链接COM0002, ASG0006⚙️ 🆕
接受日志 — 客户同意的证据 🆕

在自动流程中不会为最终客户生成签署链接，因此其同意不会被签署信封记录下来。接受日志正是承载这一证据的地方： 一份包含接受记录的 PDF，在操作处于 in_filling 状态时附加到操作上。

上传为可选项 — 发行不依赖它，缺少它也不会阻塞任何环节。该文件仅作为证据保存：它不会进入签署信封， 不会进入已签署文件包（COM0023），也不会改变自动审批（COM0020）。该操作会在按键值查询中开始返回 acceptance_log_document_key。

发行人的自动签署不为 enabled 时，请求会以 COM000077 被拒绝。再次上传会替换当前生效的文件；没有删除端点。

7.3 签署 — 人工回退路径（QI SIGN）​

任何启用状态不为 enabled 的发行人都必须走此路径，包括阶段 2 尚未完成的发行人。不存在必须先走一次的"人工发行"：若操作创建时自动签署已生效，第一笔发行同样是自动的。

代码步骤描述文档链接前提条件状态
COM0015*查询 QI SIGN 签署链接通过唯一键值，查询某笔具体操作在 QI SIGN 中的全部签署链接文档链接COM0002 → COM0009✅
COM0016*查询已签署合同链接通过唯一键值，查询某笔具体操作在 QI SIGN 中的全部已签署文件文档链接COM0002 → COM0009✅

8. 阶段 5 — 认购与实缴​

操作签署完成后，认购通知书会自动生成并提供给投资人签署。若投资人同样启用了自动签署，本步骤也无需任何人工介入。

代码步骤描述文档链接前提条件状态
INT0001*按键值查询实缴流程使用唯一键值查询某个实缴（integralização）流程的详情文档链接COM0022✅
INT0002*查询认购查询进行中的认购文档链接INT0001✅
INT0003登记认购登记投资人认购特定份额数量的意向 — 在需要调整认购日期时非常有用文档链接INT0001、INT0002✅
INT0004取消认购取消一笔认购 — 在需要调整认购日期时非常有用文档链接INT0001、INT0002✅
INT0005*Webhook — 认购通知书已签署接收确认认购通知书已签署的 webhook。这是客户系统用于发起阶段 6.1 资金划转（TFI0002）的触发信号文档链接CAB0003、INT0002🆕

9. 阶段 6 — 资金划转与付款 🆕​

阶段 6 包含两段。第一段（6.1）由集成方自身的系统在收到认购通知书签署 webhook 时触发，将资金转入 WL 清算账户。第二段（6.2）从该账户向供应商付款。

9.1 第一段 — 划转至 WL 清算账户 🆕​

触发信号。 认购通知书已签署 webhook（INT0005）是授权本次资金划转的事件。收到该 webhook 后，客户系统在 BaaS API 中发起一笔付款，向 WL 的清算账户划转资金。QI Tech 不发起此划转 — 这是集成方侧的动作，且该 webhook 是其唯一触发信号。在 INT0005 到达之前，本段中的任何动作都不得触发：针对尚未签署的通知书发起的划转没有任何操作作为支撑。

由于资金来源和目标均为 QI Conta，因此这是一笔内部转账（QI Conta → QI Conta），实时清算，不依赖 Pix 或 TED 通道。

代码步骤描述文档链接前提条件状态
TFI0001*查询 WL 清算账户查询将接收资金的 WL 清算账户，包括其标识信息与余额文档链接CAB0002✅
TFI0002*发起内部转账收到 INT0005 后，从来源 QI Conta 向 WL 清算账户发起转账。请求中必须携带该操作的唯一键值，以便将入账金额对账回该笔 NC文档链接INT0005、TFI0001✅
TFI0003*查询转账查询已发起的转账，确认资金已清算至 WL 清算账户文档链接TFI0002✅
TFI0004*Webhook — 交易已清算接收确认 WL 清算账户已入账的账户变动 webhook。这是第 6.2 段的触发信号文档链接CAB0003、TFI0002✅
TFI0005转账回单申请转账回单，供集成方自身留档与审计追溯文档链接TFI0002✅
幂等性

Webhook 可能被重复投递多次。集成方必须以操作为键管理转账，确保重复投递的 INT0005 不会针对同一笔 NC 发起第二次转账。操作键值与入账交易之间的对账由集成方负责。

TFI0002 — 发起内部转账​

ENDPOINT
/account/ACCOUNT_KEY/ted
方法
POST

ACCOUNT_KEY 是被扣款的来源 QI Conta。target_account 是 WL 清算账户 — 在内部路径下，其 ispb 为 QI Tech 自身的 ISPB（32402502），正是这一点使该笔转账在账户之间清算，而不是通过 TED 通道对外发出。

Request Body
{
  "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
  "target_account": {
    "account_branch": "0001",
    "account_number": "2359934",
    "account_digit": "2",
    "owner_document_number": "09080702000105",
    "owner_name": "WL 清算账户",
    "ispb": "32402502",
    "account_type": "checking_account"
  },
  "transaction_amount": 150000.00
}
request_control_key 即幂等键

请从 NC 操作键值确定性地派生该值，而不要每次尝试都生成新的 UUID。重复投递的 INT0005 若产生相同的 request_control_key，会被作为重复请求拒绝，而不会向清算账户重复付款。

Response Body — 201
{
  "request_control_key": "0c3d2a3e-c121-464e-b5a4-8e69e0c17bbd",
  "ted_key": "8cb70dea-9fb0-4a68-9572-99a72849c8d6",
  "created_at": "2021-10-22T20:30:23.459Z",
  "ted_status": "sent",
  "transaction_amount": 150000.00,
  "fee_amount": 0.0,
  "transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec"
}

TFI0004 — 确认入账的 Webhook​

WL 清算账户的入账以 account_transaction webhook 的形式送达，其 data.amount 为正值，且 source_sub_type = internal_funds_transfer。将 data.transaction_key 与 TFI0002 返回的 transaction_key 进行匹配，即可闭环回到该笔 NC 操作。

WEBHOOK_TYPE
account_transaction
Webhook Body
{
    "key": "<ACCOUNT-KEY>",
    "data": {
        "amount": 150000.00,
        "origin": {
            "name": "来源账户",
            "branch": "0001",
            "document": "32402502000135",
            "account_key": "5d068423-6094-49e4-b15b-7740038295a8",
            "account_digit": "5",
            "account_number": "00002"
        },
        "timestamp": "2022-09-02T21:36:33.446120",
        "destination": {
            "name": "WL 清算账户",
            "branch": "0001",
            "document": "09080702000105",
            "account_key": "6d30a0b1-cb90-4ceb-b1ea-5bd600cdf3c8",
            "account_digit": "2",
            "account_number": "2359934"
        },
        "reference_key": "983b4a28-7de6-4e71-97ef-60fb50c7b013",
        "reference_type": "movement_request",
        "account_balance": 150000.00,
        "source_sub_type": "internal_funds_transfer",
        "transaction_key": "46804f32-101e-4702-8fbc-c2dbc4c2caec",
        "source_sub_type_str": "Transferência Interna"
    },
    "datetime": "2022-09-02T21:36:33.446120",
    "webhook_type": "account_transaction"
}
请勿以严格方式映射 webhooks

QI Tech 的 webhook 载荷随时可能新增字段。请采用宽容的解析方式 — 拒绝未知字段的集成会在未来的版本发布中出错。

9.2 第二段 — 向供应商付款 🆕​

发行人的清算账户由 QI Tech 在发行时免费开立，并在 NC 签署包中被引用。从发行人自己的清算账户向供应商付款可以维系商业关系：供应商看到的是来自其自身客户的付款。

该付款不是由集成方发起的调用。 收款方在操作本身中声明（third_party_disbursement，见 §7.1 的 COM0024/COM0025），与设立条款一同被签署；当资金清算后，QI Tech 会自动执行拨付。集成方通过 webhook 跟踪 — 本通道中不存在需要调用的"发起付款"端点。

代码步骤描述文档链接前提条件状态
PAY0001*查询发行人清算账户查询发行时为发行人开立的清算账户，包括其标识信息与余额文档链接 （待确认）COM0022🆕
PAY0002*确认资金到位确认第 6.1 段划转的资金已清算至清算账户文档链接TFI0004✅
PAY0003*向收款方自动拨付在操作中声明了 third_party_disbursement 后，QI Tech 会从发行人的清算账户通过 TED、boleto 或 Pix 向供应商付款，无需集成方任何操作文档链接PAY0002、COM0024⚙️ 🆕
PAY0004*查询付款状态通过清算账户中的交易键值查询该笔拨付的状态文档链接PAY0003🆕
PAY0005*Webhook — 付款已清算接收确认供应商已收款的 webhook文档链接 （待确认）CAB0003、PAY0003🆕

可用通道​

通道payment_method字段路由方式
TEDtedtarget_account通过 financial_institution_ispb
Boletobank_slipdigitable_line（47 位）通过可键入行本身
Pixpixpix_key + pix_key_type通过密钥，走 Pix 通道

在 Pix 通道中，beneficiary 对象为必填 — 仅凭密钥无法识别收款人。二维码不受支持，也不在计划内。

Boleto — 金额必须与释放金额一致

Boleto 的金额取自可键入行的最后 10 位数字，以分为单位，且必须等于操作的 financial.released_amount。任何差异都会以 COM000061 被拒绝。

由于计算得到的 released_amount 会因费用而与 financial 中申请的金额不同，实际可行的做法是：先创建操作，读取响应中的 released_amount，然后再附上正好为该金额的 boleto。请勿修改真实可键入行中的金额 — 这会使其校验位失效，boleto 将无法支付。

一期范围

一笔 NC 对应一笔付款。 Boleto 必须覆盖释放金额的全额：付款拆分 — 即一张票据为多笔付款提供资金，或一部分付给供应商、一部分付给发行人 — 在本期不受支持，计划纳入项目二期。集成方必须据此建模其请求：一笔操作，一个收款方，全额支付。

10. Webhook 汇总​

由于本流程取消了所有人工确认节点，以下是集成方必须消费、以便端到端跟踪一笔操作的事件。

事件阶段它解锁了什么
发行人状态变更1审核关口 — 开放阶段 2 的启用申请
自动签署转为 pending_signature2信封已在申请中开启 — 确认各签署人链接可用
自动签署转为 enabled2此后所有发行均可自动执行
操作状态变更4可见分析 → 已批准的过程
操作已签署4生成认购通知书
认购通知书已签署5触发向 WL 清算账户的资金划转（TFI0002）
账户交易（internal_funds_transfer）6.1确认资金已到达 WL 清算账户 — 放行向供应商的付款
付款已清算6.2闭合整个周期

11. 上线前需要关闭的待办事项​

#待办事项责任方影响
1确认 NC 的业务条件 — 分期数、支付方式与合同模板。自动签署必须覆盖客户使用的所有业务模式；任何超出预先批准范围的情形都会回退到人工签署客户阻塞自动签署范围的界定
2确定向供应商付款的方式 部分已解决 🆕 — TED 与 boleto 均已实现，申请开通后即可使用。Pix 密钥通道同样已实现，申请开通后即可使用，需提供 beneficiary 对象；二维码既不受支持也不在计划内客户不再阻塞阶段 6
3向第三方付款 — 预计需 4 周开发 已解决 🆕 — 交付路径与原先设想不同：收款方在操作中声明，拨付自动执行，无需调用付款端点。目前仅剩文档发布与功能开通两项待办QI Tech已解除阻塞
4通过 API 创建证书 — 目前为人工操作（每个发行人一次，由 QI Tech 执行）；时间表评估中。不阻塞上线QI Tech影响开户规模化能力，不影响最初的几笔操作
5发布阶段 2 的端点契约（ASG） 已解决 — 阶段 2 已在发行人自动签署中发布。仅剩自动审核/签署行为（COM0020–COM0022）待发布QI Tech阻塞阶段 4 自动路径的同质化
6确认付款拆分属于二期范围 — 已由实现确认 🆕：boleto 必须等于释放金额的全额，因此一笔操作只支付一个收款方客户 + QI Tech界定一期的边界
7确认第 6.1 段转账中作为来源被扣款的是哪个 QI Conta，以及 WL 清算账户与 NC 签署包中引用的账户是同一个还是另一个客户 + QI Tech确定 TFI0002 的 ACCOUNT_KEY 与 target_account
8为将要使用第三方拨付的客户开通该功能 — 该功能默认不开通，未开通时创建操作会以 COM000062 被拒绝 🆕QI Tech阻塞客户使用该功能
9发布 third_party_disbursement 对象页面，并将 COM000061、COM000062 与 COM000063 加入错误目录 🆕QI Tech阻塞第三方拨付通道的同质化
10在文档中发布 Pix 密钥通道 — beneficiary 对象、pix_key_type 的取值，以及错误目录中的 COM000071 🆕QI Tech阻塞 Pix 通道的同质化

12. 错误映射​

来自发行人、投资人和商业票据 API 的错误已收录于错误目录。

发行人未审核通过时启用申请以 ISS0000032 拒绝，客户未开通时以 ISS0000033 拒绝，已存在生效启用记录时以 ISS0000029 拒绝。当发行人没有生效中的启用记录时，查询接口返回 ISS0000028；reproved 或 canceled 之后同样如此。其余自动签署特有的错误 — 在启用状态不为 enabled 时尝试发行、业务条件超出已批准范围，或签署人组与证书持有人不匹配 — 将在自动签署行为（COM0020–COM0022）发布时一并加入同一目录。