知行之桥 MaBang 端口使用指南——Get Inventory 库存获取篇

一、功能背景

MaBang（马帮 ERP）端口可以连接马帮 ERP，实现订单创建和 SKU 库存查询。

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

本文主要介绍：

Get Inventory

即从马帮主动获取 SKU 库存。

如需了解订单创建，请参考《知行之桥 MaBang 端口使用指南——Create Order 订单创建篇》。

典型使用场景

典型工作流：

MaBang_GetInventory │ ▼ 库存 JSON │ ▼ JSON 端口（JSON → XML） │ ▼ XML Map │ ├──> Database ├──> REST ├──> X12 846 └──> File

如果使用 Script 直接解析库存 JSON 并生成目标格式，则可以不经过 JSON 端口和 XML Map。

【Get Inventory 典型工作流】

二、Get Inventory 工作原理

Get Inventory 与普通“接收文件”不同。

该模式不需要上游输入文件，而是由 MaBang 端口主动调用马帮 API 查询 SKU 和库存。

整体流程如下：

手动接收文件 / 自动化计划 │ ▼ MaBang 端口 │ ▼ 按 SKU 创建日期分段查询 │ ▼ 处理分页 │ ▼ 获取 SKU │ ▼ 按配置数量分批查询库存 │ ▼ stock-get-stock-quantity │ ▼ 合并所有库存结果 │ ▼ 输出 JSON │ ▼ 下游端口

【Get Inventory 查询流程图】

这里需要特别注意：

SKU 创建起始日期筛选的是 SKU 的创建时间，不是库存更新时间。

这是 Get Inventory 配置中最容易理解错误的地方。

三、添加 MaBang 端口

进入：

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

建议库存端口名称使用：

MaBang_GetInventory

如果项目同时使用创建订单功能，则另外创建：

MaBang_CreateOrder

不要在同一个端口中反复切换 Create Order 和 Get Inventory 模式。

【添加 MaBang Get Inventory 端口】

四、配置基础连接参数

进入：

MaBang_GetInventory → 设置

需要重点配置：

【Get Inventory 设置页面】

4.1 API URI

填写马帮提供的 API 地址，例如：

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

生产环境应以马帮实际提供的 API 地址为准。

4.2 API Key

填写：

appkey

4.3 API Token

填写：

appToken

端口会自动完成 HMAC-SHA256 请求签名，不需要用户自行实现。

4.4 API Mode

设置为：

Get Inventory【API Mode 选择 Get Inventory】

五、配置 SKU 查询范围

进入：

MaBang_GetInventory → 设置 → 高级设置

Get Inventory 最关键的三个参数是：

【Get Inventory 高级设置】

六、SKU 创建起始日期

配置项：

SKU 创建起始日期（yyyy-MM-dd）

默认：

2020-01-01

该参数决定从哪个日期开始查询创建的 SKU。

例如：

2025-01-01

表示只查询：

2025-01-01 之后创建的 SKU

需要特别注意

这里筛选的是：

SKU 创建时间

不是：

库存更新时间例如某个 SKU：

SKU：ABC-001 创建日期：2024-05-01 当前库存：100

如果配置：

SKU 创建起始日期 = 2025-01-01

那么该 SKU 可能不会进入本次 SKU 查询范围。

即使它现在仍然有库存，也不会因为库存近期更新而自动被查询出来。

因此，第一次配置生产环境时，建议确认企业最早使用马帮 SKU 的时间。

如果无法准确确认，可以使用一个更早的日期，例如：

2020-01-01

再进行测试。

七、SKU 搜索日期步长

配置项：

SKU 搜索日期步长

默认：

30

表示按每 30 天一个日期区间查询 SKU。

例如：

2026-01-01 ～ 2026-01-30

端口会根据配置的日期步长自动计算后续查询区间，并依次查询各时间段内创建的 SKU。

这样做的目的，是避免一次请求查询过大的时间范围。

如何设置

SKU 数量较少时：

30

一般即可。

如果 SKU 数量非常多，可以适当减小，例如：

7

或：

15

以缩小单次 SKU 查询范围。

当该值小于等于0时，系统使用默认值。

八、获取库存数量上限

配置项：

获取库存数量上限

默认：

100

表示每次调用库存接口时，最多将 100 个 SKU 放入一批请求。

例如查询得到：

350 个 SKU

如果：

获取库存数量上限 = 100

端口会拆分为：

第 1 批：100 个 SKU 第 2 批：100 个 SKU 第 3 批：100 个 SKU 第 4 批：50 个 SKU

并分别调用：

stock-get-stock-quantity

最后再将所有结果合并。

当该值设置为：

0

时，端口不按数量上限拆分库存查询请求。

对于 SKU 数量较多的生产环境，不建议这样配置，以避免单次请求数据量过大或增加超时风险。

九、本地文件名格式

Get Inventory 最终会生成一个 JSON 文件。

可以通过：

本地文件名格式

设置输出文件名。

如果留空，默认文件名类似：

inventory_yyyyMMddHHmmss.json

例如：

inventory_20260928103000.json

如果需要固定命名规则，可以根据项目需求调整。

【本地文件名格式配置】

十、首次手动测试

第一次配置完成后，建议先手动执行一次库存查询，确认 SKU 查询范围、库存结果和输出 JSON 均符合预期后，再启用自动化计划。

进入：

MaBang_GetInventory

在事务页面执行：

接收文件

端口会立即开始：

查询 SKU → 处理分页 → 查询库存 → 合并结果 → 生成 JSON

【手动执行接收文件】

十一、查看库存查询结果

执行接收文件后，继续在事务页面查看本次查询生成的消息。

【Get Inventory 事务页面】

如果查询成功，会生成一个库存 JSON。

结构示例如下：

{ "data": [ { "stockSku": "SKU-001", "stockQuantity": "100", "warehouse": [ { "warehouseId": "1", "warehouseName": "主仓库", "stockQuantity": "100", "waitingQuantity": "0", "allotShippingQuantity": "0", "shippingQuantity": "0" } ] } ] }

实际字段以马帮 API 返回内容为准。

十二、库存字段说明

常见字段如下：

十三、没有查询到 SKU 时的结果

如果当前查询范围内没有获取到 SKU，端口会输出：

{ "data": [] }

这并不一定表示 API 调用失败。

此时第一步应检查：

SKU 创建起始日期

是否设置过晚。

例如当前设置：

2026-01-01

但实际 SKU 都创建于：

2024-01-01 ～ 2025-12-31

那么返回：

{"data":[]}

就属于正常结果。

十四、连接下游端口

Get Inventory 查询完成后，端口会输出库存 JSON。由于 XML Map 处理的是 XML 数据，因此如果后续需要通过 XML Map 进行字段映射，应先使用 JSON 端口将库存 JSON 转换为 XML，再进入后续处理流程。

例如写入数据库：

MaBang_GetInventory │ ▼ JSON 端口（JSON → XML） │ ▼ XML Map │ ▼ Database

如果需要同步给第三方系统：

MaBang_GetInventory │ ▼ JSON 端口（JSON → XML） │ ▼ XML Map │ ▼ REST

如果目标 REST 接口要求 JSON，请根据 REST 端口及目标接口的数据格式要求，在 XML Map 后增加 JSON 端口，将 XML 转换为目标 JSON。

如果需要生成库存 EDI，例如 X12 846：

MaBang_GetInventory │ ▼ JSON 端口（JSON → XML） │ ▼ XML Map │ ▼ X12 端口（生成 846） │ ▼ AS2

【Get Inventory 下游处理工作流】

十五、配置自动化库存查询

手动测试确认结果正确后，可以配置自动查询。

进入：

MaBang_GetInventory → 自动化

配置：

接收文件

的执行计划。

例如：

每小时执行一次

或：

每天固定时间执行

【Get Inventory 接收文件自动化配置】

启用后，系统会按照计划自动执行：

接收文件 → 查询 SKU → 查询库存 → 输出 JSON → 发送至下游

十六、Get Inventory 不支持 Send

Get Inventory 是：

主动拉取模式。

因此它不需要上游发送输入文件。

也就是说，Get Inventory 主要通过：

接收文件触发。

不要将订单 JSON 或其他输入消息发送到 Get Inventory 模式的 MaBang 端口。

如果需要发送订单，应使用单独的：MaBang_CreateOrder端口。

十七、Timeout 配置

高级设置中的：超时时间（秒）默认：60

SKU 较多时，库存查询可能需要多次请求。

如果某个单次 API 请求出现超时，可以适当增加，例如：120

但如果库存查询经常超时，更建议同时检查：

• SKU 搜索日期步长是否过大；
• 获取库存数量上限是否过大；
• 网络延迟；
• 马帮 API 响应速度；
• HTTPS / TLS；
• 代理或防火墙。

十八、常见问题

18.1 点击接收文件后没有库存数据

建议依次检查：

API URI API Key API Token API Mode SKU 创建起始日期

尤其注意：

SKU 创建起始日期

筛选的是 SKU 创建时间。

18.2 返回 data 为空

如果输出：

{ "data": [] }

一般说明当前日期范围没有查询到 SKU。

建议先尝试将：

SKU 创建起始日期

向前调整。

例如：

2026-01-01

改为：

2020-01-01

再执行测试。

18.3 为什么有库存的 SKU 没有返回？

例如 SKU：

创建时间：2024-01-01 库存更新时间：2026-09-28 当前库存：100

如果配置：

SKU 创建起始日期 = 2025-01-01

该 SKU 可能不会进入查询结果。

因为端口首先按：

SKU 创建时间

筛选 SKU，然后才查询这些 SKU 的当前库存。

18.4 SKU 很多，查询比较慢

这是正常现象。

Get Inventory 的完整过程是：

分日期查询 SKU ↓ 处理分页 ↓ 收集 SKU ↓ 分批调用库存 API ↓ 合并所有批次 ↓ 输出一个 JSON

SKU 越多，需要执行的 API 请求越多。

可以根据实际情况调整：

SKU 搜索日期步长 获取库存数量上限 Timeout

18.5 Get Inventory 需要输入文件吗？

不需要。

Get Inventory 通过：

接收文件

主动向马帮获取数据。

因此不需要任何上游文件作为触发条件。

十九、总结

MaBang 端口的 Get Inventory 模式用于主动从马帮 ERP 获取 SKU 及库存数据，并将查询结果整理为 JSON 文件传递给后续工作流。

整个库存获取流程可以概括为：

手动接收文件 / 自动化计划 ↓ MaBang 端口 ↓ 按 SKU 创建日期分段查询 SKU ↓ 自动处理分页 ↓ 收集目标 SKU ↓ 按配置数量分批查询库存 ↓ 调用 stock-get-stock-quantity ↓ 合并所有库存结果 ↓ 生成 JSON ↓ JSON 端口（JSON → XML） ↓ XML Map / 后续业务处理 ↓ Database / REST / EDI / File

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

1. Get Inventory 属于主动拉取模式，不需要上游提供输入文件，而是通过“接收文件”触发库存查询；
2. SKU 创建起始日期筛选的是 SKU 的创建时间，而不是库存更新时间；
3. 端口会根据SKU 搜索日期步长分段查询 SKU，并自动处理分页；
4. 获取到目标 SKU 后，端口会根据获取库存数量上限分批调用stock-get-stock-quantity查询库存；
5. 所有批次查询完成后，端口会自动合并结果并生成统一的库存 JSON 文件；
6. 如果后续需要使用 XML Map 进行字段映射，应先通过 JSON 端口将库存 JSON 转换为 XML；如果使用 Script 直接解析 JSON 并生成目标格式，则可以省略该转换步骤；
7. 如果返回"data": []，并不一定表示接口调用失败，应首先确认 SKU 创建起始日期是否覆盖实际 SKU；
8. SKU 数量较多时，可以结合日期步长、库存数量上限及 Timeout 参数进行调整，避免单次查询数据量过大；
9. 手动测试确认库存结果正确后，再配置接收文件自动化计划，即可实现周期性的库存同步。

通过以上配置，可以在知行之桥中建立从马帮 ERP 到数据库、REST API、EDI 或文件系统的自动化库存同步流程，并通过事务页面持续查看每次库存查询及文件处理结果。