基于 Flow API 的对外订单接口适配与后端系统解耦方案

知行之桥 EDI 系统支持将由多个功能端口组成的工作流对外发布为可调用的 API 接口，称为 Flow API（工作流 API）。

外部系统向该 API 发起请求后，请求体数据将进入对应的工作流进行处理，其最终输出结果将作为接口的响应（Response）返回给调用方。

Flow API主要在两种场景内使用：

  1. 按照交易伙伴的接口规范对外暴露 API，在接收到请求后，将请求体中的业务数据转发至其他系统接口进行处理，并基于下游接口的响应结果生成并返回接口响应。

  2. 按照交易伙伴的接口规范对外暴露 API，在接收到请求后，使用请求体中的业务参数进行数据库查询或数据处理，并基于查询结果生成并返回接口响应。

本文主要就场景1的配置案例，对 Flow API 的配置方案进行说明。在实际项目中，可在此基础上结合具体业务需求，对工作流结构及相关配置进行相应调整与扩展。

场景2可以参考：知行之桥三种接口详解：Webhook、Flow API 与 Admin API 中对Flow API的讲解。

需求案例

注：本案例为便于展示和理解，将部分接口鉴权字段（如 appId）直接写在脚本中；在实际项目中，建议将此类敏感信息统一存储并维护在配置库中。

扩展阅读：知行之桥 – 全局配置库 | 版本 26.2.9636

交易伙伴要求对外提供一个用于接收订单的接口，并按照其约定的接口结构返回订单创建结果，以反映后端业务系统的处理状态。同时，该接口还要求实现特定的鉴权机制（如基于签名的鉴权），以满足其安全控制要求。

由于后端业务系统在接口形式、请求体结构或处理方式等方面不便直接满足该接口规范要求，因此需要在知行之桥 EDI 系统中构建 Flow API，通过工作流方式对请求进行接收、处理与转发，以实现该业务需求。

Flow API将由多个功能端口连成的工作流组成，校验交易伙伴请求体中的sign值 -> 提取交易伙伴请求体中的订单JSON -> 调用后端业务系统接口-> 生成交易伙伴期待的响应。

交易伙伴期待的接口结构

Header说明
Content-Type 固定为 application/json
x-cdata-authtoken 知行之桥分配Authtoken值
Body 说明
appId 知行之桥分配appId
sign HMAC-SHA256加密+HEX
密钥：appKey; 加密内容：data值
data 实际的业务数据
项目内容
Body结构 {“appId”: “your_app_id”,”sign”: “calculated_sign”,”data”: “{“PONumber”: “PO20260120001″,”buyerCode”: “BUY001″ }”}
响应结构Sign正确 {
“code”: “SUCCESS”,（或”code”: “ERROR”）
“message”: “PO created successfully”（或创建失败的描述）
}
响应结构Sign错误 {
“code”: “SIGN_INVALID”,
“message”: “Signature verification failed”
}

知行之桥配置

步骤1：搭建Flow API并创建authtoken

我们需要将下面这些功能端口连成工作流以实现本例需求。

如果需要在调用后端业务系统前进行数据映射，可以在FlowAPI_Rest端口前增设XMLMAP等端口。

端口
类型		端口名称用途说明
Script FlowAPI_SignVerify 校验交易伙伴请求 Body 中的 sign 值是否正确
Branch FlowAPI_Sign_Branch 根据 sign 校验结果对请求进行分流
Script FlowAPI_InvalidSign sign 校验失败时，生成错误 response 并返回给交易伙伴
Rest FlowAPI_Rest 对 sign 校验通过的请求，调用后端业务系统接口
Script FlowAPI_Rest_Response 基于后端业务系统response 生成最终 response 并返回给交易伙伴

如下图所示，在完成各功能端口的连接并形成完整工作流后 -> 点击工作流右上角【多选】-> 框选搭建好的工作流 -> 右击【创建工作流API】-> 弹窗中配置Flow API的URL。

到此，以上述功能端口连成的工作流就暴露为了一个Flow API。

Flow API默认包含authtoken鉴权，【系统设置】-> 【添加用户】-> 勾选【API访问启用】-> 复制存留【身份认证令牌（authtoken）】-> 【添加用户】。

调用Flow API时，请求Header设置x-cdata-authtoken参数值为此身份认证令牌值即可。

如果期待不包含此Header参数，可以将令牌直接配置在请求URL上，参考资料

步骤2：功能端口配置

2.1 FlowAPI_SignVerify端口配置

该Script端口将配置下面的脚本，校验请求体中的sign值，输出订单JSON（请求体中data元素的值）。

项目内容
Sign值正确 输出文件消息头verifySign属性值=true
Sign值错误 输出文件消息头verifySign属性值=false 


<!--设置 appId appKey-->
<arc:set attr="appId.data" value="DEMO_FLOWAPI_001" />
<arc:set attr="appKey.data" value="6f1a9c8b2d4e7f0a3c5e9b8a1d2f4c6e" />
<!--从请求体中获取订单json-->
<arc:set attr="dataBody.data" value="[_message.body]" />
<!--Get Sign and data from Request Body-->
<arc:set attr="json.text" value="[dataBody.data]"/>
<arc:set attr="json.jsonpath" value="/json"/>
<arc:call op="jsonDOMSearch" in="json" out="result">
<arc:set attr="dataBody.sign" value="[jsonpath(sign)]" />
<arc:set attr="dataBody.bodyData" value="[jsonpath(data)]" />
</arc:call>
<!--生成sign以备校验 -->
<arc:set attr="encIn.format" value="HMAC" />
<arc:set attr="encIn.hmackey" value="[appKey.data]" />
<arc:set attr="encIn.hmacalgorithm" value="SHA" />
<arc:set attr="encIn.hmacbits" value="256" />
<arc:set attr="encIn.outformat" value="HEX" />
<arc:set attr="encIn.data">[dataBody.bodyData]</arc:set>
<arc:call op="encEncode" in="encIn" out="encOut">
<arc:set attr="sign.data" value="[encOut.encodeddata]" />
</arc:call>
<!--校验sign值 -->
<arc:if exp="[dataBody.sign | equals([sign.data])]">
<arc:set attr="out.header:verifySign" value="true" />
<arc:else>
<arc:set attr="out.header:verifySign" value="false" />
</arc:else>
</arc:if>
<arc:set attr="out.data" value="[dataBody.bodyData]" />
<arc:set attr="out.filename" value="FlowAPIData.json" />
<arc:push item="out" />


2.2 FlowAPI_Sign_Branch端口配置


该Branch端口通过输入文件消息头verifySign属性值分流文件。


点击端口 -> 如果【消息头】verifySign -> 【字符串】-> 【等于】true -> 【等于】false。




2.3 FlowAPI_InvalidSign端口配置


该Script端口生成sign值错误对应的response，所以需要将FlowAPI_Sign_Branch端口的【等于】false连接到FlowAPI_InvalidSign端口的输入。




FlowAPI_InvalidSign端口配置如下脚本，生成sign值错误对应的response给交易伙伴。


<arc:set attr="output.data">{



"code": "SIGN_INVALID",
"message": "Signature verification failed",
"success": false



}</arc:set>
<arc:set attr='output.Filename' value='[Filename]' />
<arc:push item="output" />


2.4 FlowAPI_Rest端口配置


该REST端口使用sign值正确的请求体中的订单JSON调用后端业务系统的接口，所以需要将FlowAPI_Sign_Branch端口的【等于】true连接到FlowAPI_Rest端口的输入。




具体配置参考REST端口帮助文档


当前我们使用知行之桥上的一个webhook接口模拟后端业务系统接口，并假设该接口response如下：（Webhook模拟接口的配置参见3.2）





项目内容





PONumber为10位，则订单创建成功
{“isok”: “1”}




PONumber长度异常，则订单创建失败
{“isok”: “0”, “message”:”PONumber INVALID”}






2.5 FlowAPI_Rest_Response端口配置




该Script端口将后端业务系统接口的response转换为交易伙伴要求的response。


下面的脚本将转换2.4中Webhook接口的response转换。


<!--获取业务系统response中的isok参数值-->
<arc:set attr="json.uri" value="[FilePath]" />
<arc:set attr="json.jsonpath" value="/json" />
<arc:call op="jsonDOMSearch" in="json" >
<arc:set attr="response.isok" value="[jsonpath(isok)]" />
<arc:set attr="response.message" value="[jsonpath(message)]" />
</arc:call>
<!--基于isok参数值对应生成成功/失败的response给交易伙伴-->
<arc:if exp="[response.isok]==1">
<arc:set attr="output.data">{"code": "SUCCESS","message": "PO created successfully"}</arc:set>
<arc:else>
<arc:set attr="output.data">{"code": "ERROR","message": "[response.message]"}</arc:set>
</arc:else>
</arc:if>
<arc:set attr="output.filepath" value="[FilePath]" />
<arc:push item="output" />


2.6 测试


使用Postman调用Flow API:


Header配置


Body配置


（模拟生成此请求体的方法参见3.1）






步骤3：如何模拟交易伙伴完整测试Flow API


3.1 模拟生成交易伙伴的请求体


新建Script端口配置如下脚本。


<!--设置 appId appKey-->
<arc:set attr="appId.data" value="DEMO_FLOWAPI_001" />
<arc:set attr="appKey.data" value="6f1a9c8b2d4e7f0a3c5e9b8a1d2f4c6e" />
<!--Read input file-->
<arc:set attr="input.file" value="[FilePath]" />
<arc:call op="fileRead" in="input" out="result" >
<arc:set attr="fileOut.data" value="[result.file:data]" />
</arc:call>
<!--生成 Sign-->
<arc:set attr="encIn.format" value="HMAC" />
<arc:set attr="encIn.hmackey" value="[appKey.data]" />
<arc:set attr="encIn.hmacalgorithm" value="SHA" />
<arc:set attr="encIn.hmacbits" value="256" />
<arc:set attr="encIn.outformat" value="HEX" />
<arc:set attr="encIn.data">[fileOut.data]</arc:set>
<arc:call op="encEncode" in="encIn" out="encOut">
<arc:set attr="sign.data" value="[encOut.encodeddata]" />
</arc:call>
<!--组装请求体-->
<arc:set attr="out.data">{"appId": "[appId.data]","sign": "[sign.data]","data": "[fileOut.data|jsonescape()]"}</arc:set>
<arc:set attr="out.filename" value="FlowAPIData.json" />
<arc:push item="out" />


Script端口输入如下内容的文件，即可生成对应的请求体。


输入：


{"PONumber": "PO20260120","buyerCode": "BUY001"}


输出：


{"appId": "DEMO_FLOWAPI_001","sign": "E04F563FAC10FF69C349A7478155C9F479323CCB64570BE05CA54A7BC26DE5F5","data": "{\"PONumber\": \"PO20260120\",\"buyerCode\": \"BUY001\"}\r\n"}




3.2 创建模拟业务系统接口的Webhook接口


新建Webhook端口：


【用户】界面添加用户配置调用Webhook接口的身份验证令牌。


【事件】-> 【响应Response】-> 配置下述脚本，实现对PONumber长度的校验及response生成。


<!--基于PONumber值长度判断成功/失败，仅模拟业务系统接口-->
<arc:set attr="json.text">[_message.body]</arc:set>


<arc:set attr="json.jsonpath" value="/json"/>
<arc:call op="jsonDOMSearch" in="json" out="result">
<arc:if exp="[jsonpath(PONumber)|getlength]==10">
<arc:set attr="_response.write">{"isok": "1"}</arc:set>
<arc:else>
<arc:set attr="_response.write">{"isok": "0", "message":"PONumber INVALID"}</arc:set>
</arc:else>
</arc:if>
</arc:call>




阅读原文







            

            
posted @ 
2026-07-27 10:55 
EDI电子数据交换 
阅读(4) 
评论(0) 
 
收藏 
举报