知行之桥 MaBang 端口使用指南——Get Inventory 库存获取篇
© All rights reserved. • 西安知行软件有限公司 • 陕ICP备09022277号
一、功能背景
MaBang（马帮 ERP）端口可以连接马帮 ERP，实现订单创建和 SKU 库存查询。
MaBang 端口目前支持两种 API 模式：
| API 模式 | 数据方向 | 作用 |
|---|---|---|
| Create Order | 工作流 → 马帮 ERP | 将订单 JSON 提交至马帮，并检查订单创建结果 |
| Get Inventory | 马帮 ERP → 工作流 | 主动查询 SKU 及当前库存，输出库存 JSON |
本文主要介绍：
Get Inventory即从马帮主动获取 SKU 库存。
如需了解订单创建，请参考《知行之桥 MaBang 端口使用指南——Create Order 订单创建篇》。
典型使用场景
| 场景 | 说明 |
|---|---|
| 定时同步库存 | 每小时或每天从马帮获取最新库存 |
| EDI 库存同步 | 获取库存后转换成 X12 846 等库存报文 |
| 多仓库存汇总 | 获取 SKU 总库存及各仓库明细 |
典型工作流：
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
→ 设置需要重点配置：
| 配置项 | 是否必填 | 说明 |
|---|---|---|
| API URI | 是 | 马帮 API 地址 |
| API 密钥（API Key） | 是 | 马帮提供的 appkey |
| API 令牌（API Token） | 是 | 马帮提供的 appToken |
| API 模式（API Mode） | 是 | 设置为 Get Inventory |
| 本地文件名格式 | 否 | 控制库存输出文件名称 |
| TLS 服务器证书 | 否 | HTTPS 服务器证书校验 |
【Get Inventory 设置页面】
4.1 API URI
填写马帮提供的 API 地址，例如：
https://gwapi.mabangerp.com/api/v2生产环境应以马帮实际提供的 API 地址为准。
4.2 API Key
填写：
appkey4.3 API Token
填写：
appToken端口会自动完成 HMAC-SHA256 请求签名，不需要用户自行实现。
4.4 API Mode
设置为：
Get Inventory
【API Mode 选择 Get Inventory】
五、配置 SKU 查询范围
进入：
MaBang_GetInventory
→ 设置
→ 高级设置Get Inventory 最关键的三个参数是：
| 配置项 | 默认值 | 作用 |
|---|---|---|
| SKU 创建起始日期 | 2020-01-01 |
从哪个 SKU 创建日期开始查询 |
| SKU 搜索日期步长 | 30 |
每次查询多少天范围内创建的 SKU |
| 获取库存数量上限 | 100 |
每批库存请求查询多少个 SKU |
【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 返回内容为准。
十二、库存字段说明
常见字段如下：
| 字段 | 所在层级 | 说明 |
|---|---|---|
| stockSku | SKU | SKU 编号 |
| stockQuantity | SKU | 当前 SKU 总库存 |
| warehouse | SKU | 仓库库存列表 |
| warehouseId | warehouse | 仓库 ID |
| warehouseName | warehouse | 仓库名称 |
| stockQuantity | warehouse | 当前仓库存量 |
| waitingQuantity | warehouse | 等待处理数量 |
| allotShippingQuantity | warehouse | 调拨或待发相关数量 |
| shippingQuantity | warehouse | 发货相关数量 |
十三、没有查询到 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
↓
合并所有批次
↓
输出一个 JSONSKU 越多，需要执行的 API 请求越多。
可以根据实际情况调整：
SKU 搜索日期步长
获取库存数量上限
Timeout18.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 模式时，需要重点注意以下几点：
- Get Inventory 属于主动拉取模式，不需要上游提供输入文件，而是通过“接收文件”触发库存查询；
SKU 创建起始日期筛选的是 SKU 的创建时间，而不是库存更新时间；- 端口会根据
SKU 搜索日期步长分段查询 SKU，并自动处理分页； - 获取到目标 SKU 后，端口会根据
获取库存数量上限分批调用stock-get-stock-quantity查询库存； - 所有批次查询完成后，端口会自动合并结果并生成统一的库存 JSON 文件；
- 如果后续需要使用 XML Map 进行字段映射，应先通过 JSON 端口将库存 JSON 转换为 XML；如果使用 Script 直接解析 JSON 并生成目标格式，则可以省略该转换步骤；
- 如果返回
"data": []，并不一定表示接口调用失败，应首先确认 SKU 创建起始日期是否覆盖实际 SKU； - SKU 数量较多时，可以结合日期步长、库存数量上限及 Timeout 参数进行调整，避免单次查询数据量过大；
- 手动测试确认库存结果正确后，再配置接收文件自动化计划，即可实现周期性的库存同步。
通过以上配置，可以在知行之桥中建立从马帮 ERP 到数据库、REST API、EDI 或文件系统的自动化库存同步流程，并通过事务页面持续查看每次库存查询及文件处理结果。
