> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# MaBang 端口

> 连接马帮 ERP，创建订单并查询 SKU 库存，支持订单状态检查和 JSON 库存输出。

MaBang 端口连接马帮 ERP，支持将订单提交到马帮，以及主动获取 SKU 库存。一个端口执行一种 API 模式，可创建两个端口分别处理订单和库存。

## 核心功能

* 根据输入 JSON 创建订单，并在提交后自动检查处理结果。
* 按 SKU 创建日期分段查询 SKU，再分批获取库存数量。
* 将库存结果合并为 JSON 文件，传递给下游端口。
* 自动生成 API 请求封装和签名。

## 端口配置

### 设置选项卡

| 设置                                    | 说明                                                     |
| ------------------------------------- | ------------------------------------------------------ |
| **API URI**                           | 马帮 API 地址。必填，例如 `https://gwapi.mabangerp.com/api/v2`。  |
| **API 密钥（API Key）**                   | 马帮提供的应用标识 `appkey`。必填。                                 |
| **API 令牌（API Token）**                 | 马帮提供的 `appToken`，用于通过 HMAC-SHA256 对每个请求体签名。必填。         |
| **API 模式（API Mode）**                  | 选择创建订单（`Create Order`）或获取库存（`Get Inventory`）。默认为创建订单。  |
| **本地文件方案（Local File Scheme）**         | 库存输出文件的命名方案，支持宏。留空时使用 `inventory_yyyyMMddHHmmss.json`。 |
| **TLS 服务器证书（TLS Server Certificate）** | 可选，用于限制接受的服务器证书。留空时使用默认验证；**任何证书**表示接受任意服务器证书。         |

### 高级选项卡

| 设置                         | 说明                                                        |
| -------------------------- | --------------------------------------------------------- |
| **订单创建检查延迟（秒）**            | 创建订单模式下，提交后开始检查处理结果前的等待时间，单位为秒，默认为 `180`。                 |
| **SKU 创建起始日期（yyyy-MM-dd）** | 获取库存模式下，查询 SKU 的创建日期起点，格式为 `yyyy-MM-dd`，默认为 `2020-01-01`。 |
| **SKU 搜索日期步长**             | 每段 SKU 创建日期查询的天数，默认为 `30`。小于或等于 `0` 时使用默认值。               |
| **获取库存数量上限**               | 每批库存请求包含的 SKU 数量，默认为 `100`。设为 `0` 时在一次请求中查询全部 SKU。        |
| **超时时间（秒）**                | 每次马帮 API 请求的超时时间，单位为秒，默认为 `60`。                           |
| **启用 TLS 协议**              | HTTPS 连接使用的协议版本，默认为**自动**，可根据目标服务器的要求选择。                  |

## 创建订单

1. 填写 API URI、API 密钥和 API 令牌。
2. 将 API 模式设为 `Create Order`。
3. 将订单 JSON 消息传入端口，启用自动化中的**发送**以自动处理。
4. 在交易页面查看提交和后续检查结果。

输入应为 `order-do-create-order` 接口的业务数据 JSON 对象，其中必须包含 `platformOrderId`。端口自动添加 `api`、`appkey`、`timestamp`、`version` 和签名，因此输入无需包含这些请求封装字段。

以下示例仅展示输入结构；实际订单需按马帮接口和店铺配置补齐所需字段：

```json theme={null}
{
  "platformOrderId": "ORDER-10001",
  "shopName": "ExampleShop",
  "currencyId": "USD",
  "orderItemList": [
    {
      "platformSku": "SKU-001",
      "quantity": "1",
      "sellPrice": "10.00"
    }
  ]
}
```

订单提交成功后，输入消息先标记为**待处理（Pending）**。达到检查延迟后，端口通过 `order-do-create-order-check` 查询该订单的结果，后台每分钟检查一次待处理订单。返回 `isok=1` 后，消息才标记为成功；尚未完成时继续等待，查询异常时标记为错误。

## 获取库存

1. 将 API 模式设为 `Get Inventory`。
2. 根据需要设置 SKU 创建起始日期、SKU 搜索日期步长和获取库存数量上限。
3. 手动执行**接收**，或在自动化中设置接收计划。
4. 将输出连接到下游端口，处理生成的库存 JSON。

此模式无需输入文件。端口从指定日期开始分段查询 SKU 创建记录，处理分页，再通过 `stock-get-stock-quantity` 分批查询这些 SKU 的当前库存。因此，起始日期筛选的是 **SKU 创建时间**。

所有批次的库存结果会合并为一个文件，结构如下：

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

实际字段以接口返回为准；输出中的数量以字符串保存。未查到 SKU 时输出 `{"data":[]}`。获取库存模式用于接收操作，不支持发送输入消息。