商业票据(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 | ✅ |
在 CED0006 中登记的签署人组决定了由哪位代表代表发行人签署。同一位代表也是在阶段 2 中签署自动签署加入协议的人,私有证书所代表的正是其权限。请在提交发行人进行分析之前正确登记 — 事后变更需要重新执行阶段 2。
5. 阶段 2 — 启用自动签署 🆕
本阶段是使自动化流程成为可能的新功能。它每个发行人只执行一次,在发行人登记审核通过之后进行,最终产出一张 QI Tech 私有证书,其适用范围严格限定于本次集成的 NC 文件。
加入协议授权的内容。 该协议授予 QI Tech 一项有限授权,用于签发并保管一张在 CertifiQI 中释放的内部私有证书,且仅可用于代表发行人签署本 NC 流程中的文件 — 绝不可用于任何其他文件、产品或交易对手。该协议由 CED0006 中登记的代表通过人脸识别生物特征一次性签署。
签署时点。 该协议被包含在第一笔发行的签署包中。因此第一笔操作仍然包含人工签署环节;从第二笔操作开始,发行人侧的签署完全自动化。
| 代码 | 步骤 | 描述 | 文档链接 | 前提条件 | 状态 |
|---|---|---|---|---|---|
| ASG0001* | 查询自动签署资格 | 读取发行人的 signature_configuration 字段块,确认该发行人已审核通过且具备启用自动签署的资格 | 文档链接 (待发布) | CED0011 或 CED1003 | 🆕 |
| ASG0002* | 申请启用自动签署 | 为已审核通过的发行人申请启用,指明签署人组以及将签署加入协议的代表。返回状态为 pending_agreement 的 auto_signature_key | 文档链接 (待发布) | ASG0001、CED0006 | 🆕 |
| ASG0003* | 查询加入协议签署链接 | 查询代表用于通过人脸识别签署加入协议的链接。在第一笔发行中,该链接作为操作签署包的一部分交付 | 文档链接 (待发布) | ASG0002 | 🆕 |
| ASG0004* | Webhook — 加入协议已签署 | 接收确认加入协议已 签署并通过校验的 webhook | 文档链接 (待发布) | CAB0003、ASG0003 | 🆕 |
| ASG0005 | 私有证书签发 | QI Tech 创建私有证书并在 CertifiQI 中释放,范围限定于该发行人的 NC 文件。目前为人工操作(每个发行人一次,由 QI Tech 执行);API 自动化已列入路线图,不阻塞上线 | — | ASG0004 | ⚙️ 🆕 |
| ASG0006* | 查询自动签署状态 | 通过 auto_signature_key 或 issuer_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 | ✅ |