知行之桥 MaBang 端口使用指南——Create Order 订单创建篇

原创

知行软件EDI

发布于 2026-09-29 10:25:20

一、功能背景

MaBang（马帮 ERP）端口用于连接马帮 ERP，实现订单创建及库存查询等业务。

MaBang 端口目前支持两种 API 模式：

API 模式	数据方向	作用
Create Order	工作流 → 马帮 ERP	将订单 JSON 提交至马帮，并自动检查订单创建结果
Get Inventory	马帮 ERP → 工作流	主动查询 SKU 及库存，并输出库存 JSON

本文主要介绍 Create Order（创建订单） 模式。

如需了解库存查询，请参考《知行之桥 MaBang 端口使用指南——Get Inventory 库存获取篇》。

典型使用场景

Create Order 适用于以下场景：

场景	说明
ERP 订单同步至马帮	将内部 ERP 生成的订单转换为马帮要求的 JSON 后自动提交
电商订单同步	将其他平台获取的订单统一转换并写入马帮
EDI 订单转马帮订单	接收 EDI 850、ORDERS 等订单后，经映射转换后提交至马帮
API 数据转马帮订单	从 REST、数据库等来源获取订单后自动写入马帮

典型工作流如下：

EDI / ERP / Database / REST
            │
            ▼
      XML Map / Script
            │
            ▼
        JSON端口转换为订单 JSON
            │
            ▼
      MaBang 端口
     Create Order
            │
            ▼
         马帮 ERP

【Create Order 典型工作流】

二、Create Order 工作原理

Create Order 并不是“发送后即代表订单创建成功”。

完整处理过程分为两个阶段：

订单 JSON
   │
   ▼
MaBang 端口
   │
   │ order-do-create-order
   ▼
马帮 API
   │
   ├─ 提交失败 → Error
   │
   └─ 提交成功
          │
          ▼
     消息进入待处理状态
          │
          │ 等待订单创建检查延迟
          ▼
order-do-create-order-check
          │
          ├─ isok = 1 → Success
          ├─ 尚未完成 → 继续保持待处理状态
          └─ 查询异常 → Error

MaBang 端口首先调用马帮订单创建接口：

order-do-create-order

提交订单。

如果订单提交阶段发生认证失败、数据校验失败、网络异常或接口错误，消息可能直接进入错误状态，不会进入待处理状态。

订单提交成功后，消息会暂时标记为：

待处理

达到配置的“订单创建检查延迟”后，端口会再次自动调用马帮订单创建结果检查接口：

order-do-create-order-check

查询订单最终处理结果。

只有马帮返回：

isok = 1

消息才会最终标记为成功。

【Create Order 订单处理流程图】

三、添加 MaBang 端口

进入知行之桥工作流页面：

工作流
→ 添加端口
→ 搜索 MaBang
→ 创建端口

建议使用容易识别的端口名称，例如：

MaBang_CreateOrder

如果项目还需要查询库存，建议另外创建：

MaBang_GetInventory

一个 MaBang 端口只配置一种 API 模式，这样更方便后期维护和问题排查。

【添加 MaBang 端口】

四、配置 MaBang 连接参数

进入：

MaBang_CreateOrder
→ 设置

Create Order 模式需要重点配置以下参数：

配置项	是否必填	说明
API URI	是	马帮 API 地址
API 密钥（API Key）	是	马帮提供的 appkey
API 令牌（API Token）	是	马帮提供的 appToken
API 模式（API Mode）	是	设置为 Create Order
TLS 服务器证书	否	控制 HTTPS 服务器证书验证方式

【Create Order 设置页面】

4.1 API URI

填写马帮提供的 API 地址。

例如：

https://gwapi.mabangerp.com/api/v2

实际使用时，应以马帮提供的正式接口地址为准。

4.2 API 密钥（API Key）

填写马帮提供的：

appkey

该字段用于标识调用马帮 API 的应用。

4.3 API 令牌（API Token）

填写马帮提供的：

appToken

MaBang 端口会使用 API Token 对请求进行 HMAC-SHA256 签名。

因此，上游业务系统只需要提供订单业务数据，不需要自行生成 API 签名。

4.4 API Mode

将：

API Mode

设置为：

Create Order

【API Mode 选择 Create Order】

五、准备订单 JSON

Create Order 模式接收的是马帮：

order-do-create-order

接口所需的业务数据 JSON。

其中必须包含：

platformOrderId

以下为一份完整的测试订单示例，仅用于展示常见字段结构，并不代表示例中的所有字段均为必填项。实际字段要求应以马帮接口及具体业务场景为准。

{
  "platformOrderId": "90000000001",
  "shopName": "Target TEST",
  "buyerUserId": "Test Buyer",
  "street1": "123 Test Street",
  "currencyId": "USD",
  "paidTime": "2026-09-06 21:07:00",
  "salesRecordNumber": "900000000000001",
  "platformTrackNumber": "",
  "shippingType": "",
  "warehouseName": "",
  "myLogisticsChannelId": "",
  "trackNumber1": "",
  "trackNumber2": "",
  "buyerName": "Test Buyer",
  "phone1": "(407) 000-0000",
  "phone2": "",
  "country": "",
  "countryCode": "US",
  "district": "",
  "province": "FL",
  "city": "Test City",
  "street2": "",
  "abnnumber": "",
  "email": "test@example.com",
  "doorcode": "",
  "tankno": "",
  "companyStreet": "",
  "postCode": "00000-0000",
  "buyerMessage": "",
  "shippingService": "",
  "dlypName": "",
  "transNumber": "",
  "deliveryRemark": "UPSN NS\nserviceLevel:Standard Service\n\nCoverage Code: 36\nWarehouse storage location number: TEST\nDelivery Reference: N\nSold:09/06/2026",
  "remark": "Thank you for your purchase. If you ordered additional items they will arrive separately.",
  "orderItemList": [
    {
      "title": "3",
      "platformSku": "TEST261603-Navy Blue-M",
      "quantity": "1",
      "pictureUrl": "",
      "itemId": "",
      "sellPrice": "20.0",
      "productUnit": "",
      "specifics": "Test Product NavyBlue M",
      "message": "",
      "productUrl": "",
      "salesRecordNumber": ""
    }
  ],
  "extendAttr": [
    {
      "key": "The requested shipping date",
      "val": "09/16/2026"
    },
    {
      "key": "The requested delivery date",
      "val": "09/24/2026"
    },
    {
      "key": "The date of the purchase order",
      "val": "09/06/2026"
    }
  ]
}

其中，shopName 需要填写马帮系统中已创建的店铺名称，并确保名称与马帮后台配置保持一致。

六、哪些字段不需要上游传入

MaBang 端口会自动生成 API 请求封装字段。

上游 JSON 无需传入：

api
appkey
timestamp
version
签名

端口会根据：

API URI
API Key
API Token

自动组装请求并生成签名。

因此，上游映射负责生成订单业务数据。MaBang 端口负责补充 api、appkey、timestamp、version 及签名等 API 请求封装字段。

七、发送测试订单

将第五步中准备的测试订单 JSON 上传至 MaBang Create Order 端口。

执行发送后，进入事务页面查看处理状态。

【测试订单进入 MaBang 端口】

八、理解待处理状态

Create Order 模式中，看到：

待处理

通常并不代表出现错误。

这是因为端口需要等待马帮系统完成订单处理。

流程如下：

提交订单成功
     ↓
待处理
     ↓
等待检查延迟
     ↓
查询马帮处理结果

默认订单创建检查延迟为：

180 秒

达到订单创建检查延迟后，后台会开始查询创建结果；如果订单仍未完成，系统会每分钟继续检查一次待处理订单。

因此，如果刚刚发送订单就立即查看事务，看到待处理属于正常现象。

【事务中的待处理状态】

九、订单最终状态

9.1 成功

当：

order-do-create-order-check

isok = 1

消息会标记为：

成功

这时才表示马帮确认订单处理成功。

9.2 待处理

如果马帮尚未完成处理：

待处理

状态会继续保留，等待下一次检查。

9.3 错误

如果在订单提交或订单结果检查过程中出现以下异常：

API 请求异常；
网络错误；
马帮返回接口错误；
认证失败；
数据校验失败；
请求超时；

消息会进入：

错误

此时应进入事务查看详细日志。

【事务中的日志位置】

十、配置订单创建检查延迟

进入：

MaBang_CreateOrder
→ 设置
→ 高级

找到：

订单创建检查延迟（秒）

默认值：

含义是：

创建订单请求提交后，等待多少秒再开始查询马帮的订单处理结果。

例如设置：

表示提交订单后约 3 分钟开始第一次状态检查。

一般情况下建议使用默认值。

如果马帮订单处理速度较慢，可以根据实际情况适当增加。

【订单创建检查延迟配置】

十一、配置发送自动化

完成手动测试后，可以启用自动发送。

进入：

MaBang_CreateOrder
→ 自动化

启用：

发送

启用后，当上游消息进入 MaBang 端口时，系统会自动调用马帮 Create Order API。

【Create Order 自动化发送配置】

典型生产工作流：

上游系统产生订单
       ↓
自动进入 MaBang 端口
       ↓
自动 Send
       ↓
调用马帮创建订单
       ↓
待处理
       ↓
自动检查状态
       ↓
Success / Error

十二、Timeout 配置

高级设置中的：

超时时间（秒）

用于控制单次马帮 API 请求最长等待时间。

默认：

【Timeout 配置】

如果出现请求超时，可以根据实际网络环境适当增加，例如：

但如果频繁超时，不建议只通过持续增大 Timeout 解决。

还应检查：

马帮 API 响应速度；
本地网络情况；
HTTP/HTTPS 代理；
防火墙；
DNS；
TLS 握手；
马帮服务状态。

十三、常见问题

13.1 订单一直是待处理

首先确认：

订单发送时间

和：

订单创建检查延迟

如果还没有达到检查时间，待处理属于正常现象。

如果已经等待较长时间仍然处于待处理状态，建议检查：

platformOrderId 是否正确；
马帮后台是否已经生成订单；
order-do-create-order-check 是否正常返回；
事务日志是否出现异常；
API Key / API Token 是否有效。

13.2 订单发送后立即 Error

进入：

事务
→ 查看详细日志

常见原因包括：

API URI 错误
API Key 错误
API Token 错误
JSON 格式错误
必填字段缺失
店铺信息错误
SKU 不存在
马帮接口业务校验失败
网络连接失败
请求超时

13.3 是否需要自己生成 HMAC-SHA256 签名？

不需要。

MaBang 端口会根据：

API Key
API Token

自动完成请求签名。

上游系统只需要提供订单业务 JSON。

十四、总结

MaBang 端口的 Create Order 模式用于将知行之桥工作流中的订单数据提交至马帮 ERP，并自动跟踪订单的最终创建结果。

在实际配置过程中，可以将整个处理流程概括为：

准备订单 JSON
      ↓
发送至 MaBang 端口
      ↓
调用 order-do-create-order
      ↓
订单提交成功
      ↓
进入待处理状态
      ↓
等待订单创建检查延迟
      ↓
调用 order-do-create-order-check
      ↓
确认订单最终处理结果
      ↓
成功 / 待处理 / 错误

使用 Create Order 模式时，需要重点注意以下几点：

上游系统只需要提供马帮订单所需的业务 JSON，无需自行生成 appkey、timestamp、签名等 API 请求参数；
shopName 应与马帮后台已经创建的店铺名称保持一致；
订单首次提交成功后进入“待处理”状态属于正常现象，并不代表订单处理失败；
MaBang 端口会根据“订单创建检查延迟”自动调用订单结果检查接口，持续确认马帮侧的最终处理结果；
只有马帮返回 isok = 1 后，端口中的文件才会最终进入“成功”状态；
如果订单提交或结果查询过程中出现认证、网络、数据校验或接口异常，应通过事务日志查看具体错误信息。

通过以上配置，即可在知行之桥中建立从上游业务系统到马帮 ERP 的自动化订单创建流程，减少人工录入，并通过端口事务状态和日志持续跟踪每笔订单的处理结果。

原创声明：本文系作者授权腾讯云开发者社区发表，未经许可，不得转载。

如有侵权，请联系 cloudcommunity@tencent.com 删除。

数据传输服务

#MaBang

#EDI

#知行之桥