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

一、功能背景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是马帮提供的appkeyAPI 令牌API Token是马帮提供的appTokenAPI 模式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 创建时间不是库存更新时间例如某个 SKUSKUABC-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 返回内容为准。十二、库存字段说明常见字段如下字段所在层级说明stockSkuSKUSKU 编号stockQuantitySKU当前 SKU 总库存warehouseSKU仓库库存列表warehouseIdwarehouse仓库 IDwarehouseNamewarehouse仓库名称stockQuantitywarehouse当前仓库存量waitingQuantitywarehouse等待处理数量allotShippingQuantitywarehouse调拨或待发相关数量shippingQuantitywarehouse发货相关数量十三、没有查询到 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 846MaBang_GetInventory │ ▼ JSON 端口JSON → XML │ ▼ XML Map │ ▼ X12 端口生成 846 │ ▼ AS2【Get Inventory 下游处理工作流】十五、配置自动化库存查询手动测试确认结果正确后可以配置自动查询。进入MaBang_GetInventory → 自动化配置接收文件的执行计划。例如每小时执行一次或每天固定时间执行【Get Inventory 接收文件自动化配置】启用后系统会按照计划自动执行接收文件 → 查询 SKU → 查询库存 → 输出 JSON → 发送至下游十六、Get Inventory 不支持 SendGet Inventory 是主动拉取模式。因此它不需要上游发送输入文件。也就是说Get Inventory 主要通过接收文件触发。不要将订单 JSON 或其他输入消息发送到 Get Inventory 模式的 MaBang 端口。如果需要发送订单应使用单独的MaBang_CreateOrder端口。十七、Timeout 配置高级设置中的超时时间秒默认60SKU 较多时库存查询可能需要多次请求。如果某个单次 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 创建起始日期是否覆盖实际 SKUSKU 数量较多时可以结合日期步长、库存数量上限及 Timeout 参数进行调整避免单次查询数据量过大手动测试确认库存结果正确后再配置接收文件自动化计划即可实现周期性的库存同步。通过以上配置可以在知行之桥中建立从马帮 ERP 到数据库、REST API、EDI 或文件系统的自动化库存同步流程并通过事务页面持续查看每次库存查询及文件处理结果。