一句话定义

OpenAPI、事件订阅与异步回调是 Ftrans B2B 提供给外部系统的三种协同机制：接口让业务系统主动发起动作，事件订阅让平台主动通报状态变化，异步回调让耗时较长的任务在完成后把结果送回调用方。 三者之上有统一的调用审计日志。

一、这个能力解决什么问题

问题不是「能不能用程序传文件」，而是「集成之后，人工到底减没减下去」。

很多平台的开放能力只覆盖文件的上传下载，管理面的动作仍然留在后台界面里。于是集成后的真实状态往往是这样的：

还有一类更隐蔽的问题：集成成了审计的盲区。 平台里人工操作的每一步都有日志，但通过接口发生的动作如果没有记录，「谁在什么时候用程序做了什么」就说不清。对一个集中托管外部凭据的平台来说，这是不能接受的缺口。

二、怎么工作：调用、订阅、回调

2.1 标准化接口：覆盖的是管理动作，不只是文件

产品的标准化接口覆盖五类能力：

这个覆盖范围的意义在于：新伙伴上线这件事可以整条自动化。 建档、开目录、授权、配置收发关系、提交第一批文件，不需要中途插入一次「找管理员在后台点一下」。

具体的接口清单、请求方式与字段定义随实施交付接口文档，本页不展开——因为对选型判断有用的是覆盖范围，不是端点名称。

2.2 实时事件订阅：平台主动说，不用你问

平台侧的状态变化可以通过实时事件订阅推送给已订阅的系统，业务系统不必轮询。

这条机制解决的是前面那个「两头不讨好」的轮询问题。对业务系统来说，它关心的通常不是「现在什么状态」，而是「变了没有」——事件推送正好回答后者。

2.3 异步回调：长任务不该让调用方挂着等

对外交换任务天然是长任务。一次外发要经过内容识别与敏感内容检查，可能要等人工审批，还要等对端取件或回送回执——这个过程从几分钟到几天都有可能。

因此产品提供异步回调机制：调用方提交任务后即可返回，平台在处理完成后回调预留的地址送回结果。这不是性能优化，是对业务现实的正确建模——把一次可能等一天的审批塞进一个同步请求里，任何超时设置都是错的。

2.4 调用审计日志：接口不是审计盲区

每一次接口调用都有记录，与平台的七类日志（访问会话、文件操作、文件传输、系统管理、身份管理、身份认证、安全检测）一并归集，支持条件查询、详情查看与导出。

这条在安全评审时会被单独问到。答案是明确的：通过接口发生的动作和人工操作一样留痕，不存在「程序做的所以查不到」的情况。

2.5 接口提交的任务，走同一套安全治理

必须写明的一条规则：通过接口提交的交换任务，与人工在平台上提交的任务受同一套治理。

出向仍然是先受控入库、内容识别、敏感内容检查，需要时走审批，之后才加密外发；入向仍然是先落隔离区，解密验签之后才执行威胁检测。产品不提供「因为是系统调用所以跳过检查」的配置。

这一点值得在选型时确认，因为它直接决定了集成之后安全策略还成不成立。

2.6 另一类开放：把检测能力接出去

除面向业务系统的接口外，产品支持 ICAP 协议，可对接第三方防病毒与 DLP 系统，也支持按需对接第三方加解密系统。企业若已建有统一的内容检测能力，交换平台可以复用它，而不是另建一套检测策略。

三、配置与运维要点

3.1 凭据不因集成而外流

业务系统通过接口发起交换，用的是平台侧的接口凭据，拿不到外部伙伴的 FTP/SFTP 账号、对象存储密钥、PGP 私钥或协议证书私钥——这些由平台统一保管与使用。

集成扩大的是自动化范围，不是凭据的传播范围。 这条边界如果被打破，凭据收口这件事本身就白做了。

→ 托管范围、密钥存储形态与安全评审配合见 外部凭据托管的安全设计与评审配合

3.2 回调地址要能被平台访问到

异步回调是平台主动发起的请求，因此调用方需要提供一个平台侧可达的接收地址。在内外网分段的环境里，这一项通常涉及一次网络策略确认，建议在集成方案设计阶段就提出，而不是等到联调。

3.3 事件订阅与回调的取舍

两者可以配合使用，取舍标准很简单：

• 想知道「平台里发生了什么」 —— 用事件订阅，按需订阅关心的状态变化。
• 想知道「我提交的那一件事办完没有」 —— 用异步回调，结果直接送回发起方。

如果业务系统只关心自己提交的任务，回调通常就够了；如果它还要对平台上其他来源的交换做出反应，才需要订阅。

3.4 集成的时机：不要第一步就接

产品支持渐进式落地，集成排在第四阶段——纳管、规则化、自动化之后。理由是实践性的：伙伴档案与收发策略没有稳定下来之前接业务系统，等于把不确定的规则固化进接口调用，改起来更贵。前三个阶段跑顺了，第四阶段业务系统只需要知道「提交任务」与「接收结果」两件事。

3.5 不承担作业编排

产品提供接口与事件机制，但不包含通用的工作流编排与任务调度引擎。什么时候调用、按什么依赖顺序调用、失败后重试几次、重试间隔多久——这些决定属于调用方或企业既有的调度平台。

这是主动划定的边界。把编排放在调度平台、把交换与治理放在交换平台，两边的责任才分得清；两边都能定义任务，出问题时谁也说不清是谁触发的。

四、与其他能力的关系

• 四条链路的全貌 —— 接口只是其中一条，还有身份、审批、通知三条。→ 与既有业务系统协同
• 账号从哪来、怎么认证 —— 接口里的账号体系与身份认证对应的是这一套。→ 身份集成与统一认证
• 业务系统触发与结果回写的完整链路 —— 接口在实际场景里长什么样。→ PLM / ERP 的文件交换集成
• 接口提交的任务要经过的检查顺序 —— 出向与入向为什么不同。→ 文件出入向安全治理
• 凭据为什么不下发给调用方 —— 收口的对象与范围。→ 外部账号与密钥集中托管
• 典型的集成密度较高的行业 —— 内部系统体系成熟、对外交换是补进来的那一环。→ 集成电路与半导体的内外部文件交换