> ## 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":[]}`。取得庫存模式用於接收操作，不支援傳送輸入訊息。