跳到主要内容

商业票据(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 执行(集成方无需操作,但必须观察由此产生的状态)
*同质化验收的必测步骤
顺序前提

自动签署仅在发行人登记审核通过后才能配置。 授权自动签署的加入协议在第一笔发行的签署包中签署。从第二笔发行开始,发行人侧的签署完全自动化。因此阶段 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 文件。

加入协议授权的内容。 该协议授予 QI Tech 一项有限授权,用于签发并保管一张在 CertifiQI 中释放的内部私有证书,且仅可用于代表发行人签署本 NC 流程中的文件 — 绝不可用于任何其他文件、产品或交易对手。该协议由 CED0006 中登记的代表通过人脸识别生物特征一次性签署。

签署时点。 该协议被包含在第一笔发行的签署包中。因此第一笔操作仍然包含人工签署环节;从第二笔操作开始,发行人侧的签署完全自动化。

代码步骤描述文档链接前提条件状态
ASG0001*查询自动签署资格读取发行人的 signature_configuration 字段块,确认该发行人已审核通过且具备启用自动签署的资格文档链接 (待发布)CED0011 或 CED1003🆕
ASG0002*申请启用自动签署为已审核通过的发行人申请启用,指明签署人组以及将签署加入协议的代表。返回状态为 pending_agreementauto_signature_key文档链接 (待发布)ASG0001、CED0006🆕
ASG0003*查询加入协议签署链接查询代表用于通过人脸识别签署加入协议的链接。在第一笔发行中,该链接作为操作签署包的一部分交付文档链接 (待发布)ASG0002🆕
ASG0004*Webhook — 加入协议已签署接收确认加入协议已签署并通过校验的 webhook文档链接 (待发布)CAB0003、ASG0003🆕
ASG0005私有证书签发QI Tech 创建私有证书并在 CertifiQI 中释放,范围限定于该发行人的 NC 文件。目前为人工操作(每个发行人一次,由 QI Tech 执行);API 自动化已列入路线图,不阻塞上线ASG0004⚙️ 🆕
ASG0006*查询自动签署状态通过 auto_signature_keyissuer_key 查询启用情况,确认已转为 active。在达到该状态之前,任何 NC 都不得依赖自动签署文档链接 (待发布)ASG0002🆕
ASG0007*Webhook — 自动签署已生效接收表明证书已可用、发行人已启用自动签署的 webhook文档链接 (待发布)CAB0003、ASG0005🆕
ASG0008查询已签署的加入协议查询已签署的加入协议文件,供集成方自身留档与审计追溯文档链接 (待发布)ASG0004🆕
ASG0009撤销自动签署撤销启用状态及关联证书 — 在代表变更、签署人组变更或发行人提出要求时必须执行。撤销后,发行恢复为人工签署流程,直至重新执行阶段 2文档链接 (待发布)ASG0006🆕

5.1 启用状态机

状态含义新 NC 的签署行为
not_requested发行人已审核通过,但从未提交启用申请人工签署(QI SIGN)
pending_agreement已申请启用;加入协议尚未签署人工签署 — 协议随本次操作的签署包一同传递
pending_certificate协议已签署;QI Tech 正在签发证书人工签署 — 在转为 active 之前暂缓新的发行
active证书已在 CertifiQI 中释放自动
revoked启用已被撤销人工签署(QI SIGN)
同质化要求

集成方必须在沙盒环境中证明:其系统在创建操作前会读取启用状态,并在两个方向上正确路由 — 状态为 active 时走自动签署,其余所有状态走 QI SIGN 回退路径(COM0015 / COM0016)。任何假定状态恒为 active 的集成,都会在每个新发行人的第一笔发行时出错。


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

7.2 签署 — 自动路径(自动签署状态为 active 的发行人)🆕

代码步骤描述文档链接前提条件状态
COM0020*自动审核通过在自动签署已生效且业务条件已预先批准的情况下,操作从分析状态自动转为已批准,无需人工介入。集成方通过 webhook 观察该状态转换文档链接 (待发布)COM0011、ASG0006⚙️ 🆕
COM0021*设立条款自动签署QI Tech 使用在 CertifiQI 中释放的私有证书代表发行人签署设立条款。不会为发行人生成签署链接文档链接 (待发布)COM0020⚙️ 🆕
COM0022*Webhook — 操作已签署接收确认该操作的所有签署均已完成的 webhook文档链接CAB0003、COM0021🆕
COM0023*查询已签署文件通过唯一键值查询该操作的已签署文件,包括签署证据报告文档链接COM0022

7.3 签署 — 人工回退路径(QI SIGN)

每个发行人的第一笔发行(其中包含加入协议)以及任何启用状态不为 active 的发行人,都必须走此路径。

代码步骤描述文档链接前提条件状态
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 签署包中被引用。从发行人自己的清算账户向供应商付款可以维系商业关系:供应商看到的是来自其自身客户的付款。

代码步骤描述文档链接前提条件状态
PAY0001*查询发行人清算账户查询发行时为发行人开立的清算账户,包括其标识信息与余额文档链接 (待确认)COM0022🆕
PAY0002*确认资金到位确认第 6.1 段划转的资金已清算至清算账户文档链接TFI0004
PAY0003*发起对第三方的付款通过 BaaS API 从发行人清算账户向供应商发起付款。预计需 4 周开发文档链接 (待发布)PAY0002🆕
PAY0004*查询付款状态通过唯一键值查询某笔付款的状态文档链接 (待确认)PAY0003🆕
PAY0005*Webhook — 付款已清算接收确认供应商已收款的 webhook文档链接 (待确认)CAB0003、PAY0003🆕
一期范围

一笔 NC 对应一笔付款。 付款拆分 — 即一张票据为多笔供应商付款提供资金 — 在本期不受支持,计划纳入项目二期。集成方必须据此建模其请求:一笔操作,一个收款方。


10. Webhook 汇总

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

事件阶段它解锁了什么
发行人状态变更1审核关口 — 使阶段 2 的申请成为可能
加入协议已签署2证书签发开始
自动签署已生效2此后所有发行均可自动执行
操作状态变更4可见分析 → 已批准的过程
操作已签署4生成认购通知书
认购通知书已签署5触发向 WL 清算账户的资金划转(TFI0002)
账户交易(internal_funds_transfer6.1确认资金已到达 WL 清算账户 — 放行向供应商的付款
付款已清算6.2闭合整个周期

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

#待办事项责任方影响
1确认 NC 的业务条件 — 分期数、支付方式与合同模板。自动签署必须覆盖客户使用的所有业务模式;任何超出预先批准范围的情形都会回退到人工签署客户阻塞自动签署范围的界定
2确定向供应商付款的方式:Pix/二维码或 boleto。Pix/二维码较为直接;boleto 所需开发量显著更大客户 + QI Tech决定阶段 6 的开发规模
3从清算账户向第三方付款 — 预计需 4 周开发QI Tech阻塞阶段 6
4通过 API 创建证书 — 目前为人工操作(每个发行人一次,由 QI Tech 执行);时间表评估中。不阻塞上线QI Tech影响开户规模化能力,不影响最初的几笔操作
5发布阶段 2 的端点契约(ASG)以及自动审核/签署行为(COM0020–COM0022)QI Tech阻塞阶段 2 的同质化
6确认付款拆分属于二期范围客户 + QI Tech界定一期的边界
7确认第 6.1 段转账中作为来源被扣款的是哪个 QI Conta,以及 WL 清算账户与 NC 签署包中引用的账户是同一个还是另一个客户 + QI Tech确定 TFI0002 的 ACCOUNT_KEYtarget_account

12. 错误映射

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

自动签署特有的错误 — 在启用状态不为 active 时尝试发行、证书已被撤销、业务条件超出已批准范围,或签署人组与证书持有人不匹配 — 将在 ASG 端点发布时一并加入同一目录。