# 第三方系統 API 對接手冊 Star ERP 系統提供外部整合 API (Integration API) 供電商前台、POS 機或其他第三方系統串接。 所有的整合 API 均受到 Laravel Sanctum Token 與多租戶 (Multi-tenant) Middleware 保護。 ## 基礎連線資訊 - **API Base URL**: `https://[租戶網域]/api/v1/integration` (依實際部署網址為準，單機開發為 `http://localhost/api/v1/integration`) - **Headers 要求**: - `Accept: application/json` - `Content-Type: application/json` - `Authorization: Bearer {YOUR_API_TOKEN}` (由 ERP 系統管理員核發的 Sanctum Token) - **速率限制**：每位使用者每分鐘最多 60 次請求。超過時會回傳 `429 Too Many Requests`。 --- ## 1. 商品資料讀取 (Product Retrieval) 此 API 用於讓外部系統（如 POS）依據關鍵字、分類或最後更新時間，從 ERP 中批量抓取商品資料。支援分頁與增量同步。 - **Endpoint**: `/products` - **Method**: `GET` ### Query Parameters | 參數名稱 | 類型 | 必填 | 說明 | | :--- | :--- | :---: | :--- | | `product_id` | Integer| 否 | 依 ERP 商品 ID (`products.id`) 精準篩選 | | `external_pos_id` | String | 否 | 依外部 POS 端的唯一識別碼 (`external_pos_id`) 精準篩選 | | `barcode` | String | 否 | 依商品條碼 (Barcode) 精準篩選 | | `code` | String | 否 | 依商品代碼 (Code) 精準篩選 | | `category` | String | 否 | 分類名稱精準過濾 | | `updated_after` | String | 否 | 增量同步機制。僅回傳該時間點之後有異動的商品 (格式: `YYYY-MM-DD HH:mm:ss`) | | `per_page` | Integer| 否 | 每頁筆數 (預設 50, 最大 100) | | `page` | Integer| 否 | 分頁頁碼 (預設 1) | ### Response **Success (HTTP 200)** 僅開放公開價格 `price`，隱藏敏感成本與會員價。 ```json { "status": "success", "data": [ { "id": 12, "code": "PROD-001", "barcode": "4710001", "name": "可口可樂 600ml", "external_pos_id": "POS-P-001", "category_name": "飲品", "brand": "可口可樂", "specification": "600ml", "unit_name": "瓶", "price": 25.0, "is_active": true, "updated_at": "2026-03-19 09:30:00" } ], "meta": { "current_page": 1, "last_page": 5, "per_page": 50, "total": 240 } } ``` --- ## 2. 商品資料同步 (Upsert Product) 此 API 用於將第三方系統（如 POS）的產品資料單向同步至 ERP。採用 Upsert 邏輯：若 `external_pos_id` 存在則更新資料，不存在則新增產品。 - **Endpoint**: `/products/upsert` - **Method**: `POST` ### Request Body (JSON) | 參數名稱 | 類型 | 必填 | 說明 | | :--- | :--- | :---: | :--- | | `external_pos_id` | String | **是** | 在 POS 系統中的唯一商品 ID (Primary Key) | | `name` | String | **是** | 商品名稱 (最大 255 字元) | | `category` | String | **是** | 商品分類名稱。若系統中不存在則自動建立 (最大 100 字元) | | `unit` | String | **是** | 商品單位 (例如：個、杯、件)。若不存在則自動建立 (最大 100 字元) | | `code` | String | 否 | 商品代碼。若未提供將由 ERP 自動產生 (最大 100 字元) | | `price` | Decimal | 否 | 商品售價 (預設 0) | | `barcode` | String | 否 | 商品條碼 (最大 100 字元)。若未提供將由 ERP 自動產生 | | `brand` | String | 否 | 商品品牌名稱 (最大 100 字元) | | `specification` | String | 否 | 商品規格描述 (最大 255 字元) | | `cost_price` | Decimal | 否 | 成本價 (預設 0) | | `member_price` | Decimal | 否 | 會員價 (預設 0) | | `wholesale_price` | Decimal | 否 | 批發價 (預設 0) | | `is_active` | Boolean| 否 | 是否上架/啟用 (預設 true) | | `updated_at` | String | 否 | POS 端的最後更新時間 (格式: YYYY-MM-DD HH:mm:ss) | **請求範例：** ```json { "external_pos_id": "POS-PROD-9001", "name": "特級冷壓初榨橄欖油 500ml", "category": "調味料", "unit": "瓶", "price": 380.00, "barcode": "4711234567890", "brand": "健康王", "specification": "500ml / 玻璃瓶裝", "cost_price": 250.00, "member_price": 350.00, "wholesale_price": 300.00, "is_active": true, "updated_at": "2024-03-15 14:30:00" } ``` > [!TIP] > **自動編碼與分類機制**： > - **必填項**：`category` 與 `unit` 為必填。若 ERP 中無對應名稱，將會依據傳入值自動建立。 > - **自動編碼**：若未提供 `code` (商品代碼)，將由 ERP 自動產生 8 位隨機代碼。 > - **自動條碼**：若未提供 `barcode` (條碼)，將由 ERP 自動產生 13 位隨機數字條碼。 > - 建議在同步後儲存回傳的 `id`、`code` 與 `barcode`，以利後續精確對接。 ### Response 回傳 ERP 端的完整商品主檔資訊，供外部系統回存 ID 或代碼。 ### 回傳範例 (Success) - **Status Code**: `200 OK` ```json { "message": "Product synced successfully", "data": { "id": 1, "external_pos_id": "POS-P-999", "code": "A1B2C3D4", "barcode": "4710009990001" } } ``` --- ## 3. 門市庫存查詢 (Query Inventory) 此 API 用於讓外部系統（如 POS）依據特定的「倉庫代碼」，查詢該倉庫目前所有商品的庫存餘額。 **注意**：此 API 會回傳該倉庫內的所有商品數量，不論該商品是否已綁定外部 POS ID。 - **Endpoint**: `/inventory/{warehouse_code}` - **Method**: `GET` ### URL 路徑參數 | 參數名稱 | 類型 | 必填 | 說明 | | :--- | :--- | :---: | :--- | | `warehouse_code` | String | **是** | 要查詢的倉庫代碼 (例如：`STORE-001`，測試可使用預設建立之 `api-test-01`) | ### Query Parameters (選填) | 參數名稱 | 類型 | 說明 | | :--- | :--- | :--- | | `product_id` | String | 依 ERP 商品 ID (`products.id`) 篩選。 | | `external_pos_id` | String | 依外部 POS 端的唯一識別碼 (`external_pos_id`) 篩選。 | | `barcode` | String | 依商品條碼 (Barcode) 篩選商品。 | | `code` | String | 依商品代碼 (Code) 篩選商品。 | 若不帶任何參數，將回傳該倉庫下所有商品的庫存餘額。 ### Response **Success (HTTP 200)** 回傳該倉庫內所有的商品目前庫存總數及詳細資訊。若商品未建置 `external_pos_id`，該欄位將顯示為 `null`。 ```json { "status": "success", "warehouse_code": "api-test-01", "data": [ { "product_id": 1, "external_pos_id": "PROD-001", "product_code": "PROD-A001", "product_name": "特級冷壓初榨橄欖油 500ml", "barcode": "4710123456789", "category_name": "調味料", "unit_name": "瓶", "price": 450.00, "brand": "奧利塔", "specification": "500ml/瓶", "batch_number": "PROD-A001-TW-20231026-01", "expiry_date": "2025-10-26", "quantity": 15 }, { "external_pos_id": null, "product_code": "MAT-001", "product_name": "未包裝干貝醬原料", "barcode": null, "category_name": "原料", "unit_name": "kg", "price": 0.00, "brand": null, "specification": null, "batch_number": "MAT-001-TW-20231020-01", "expiry_date": "2024-04-20", "quantity": 2.5 } ] } ``` **Error: Warehouse Not Found (HTTP 404)** 當傳入系統中不存在的倉庫代碼時發生。 ```json { "status": "error", "message": "Warehouse with code 'STORE-999' not found." } ``` --- ## 4. 訂單資料寫入與扣庫 (Create Order) 此 API 用於讓第三方系統（如 POS 結帳後）將「已成交」的訂單推送到 ERP。 **重要提醒**：寫入訂單時，ERP 會無條件扣除庫存。若指定的「批號」庫存不足，系統會自動轉向 `NO-BATCH` 庫存項目扣除；若最終仍不足，則會在 `NO-BATCH` 產生負數庫存。 - **Endpoint**: `/orders` - **Method**: `POST` ### Request Body (JSON) | 欄位名稱 | 型態 | 必填 | 說明 | | :--- | :--- | :---: | :--- | | `external_order_id` | String | **是** | 第三方系統中的唯一訂單編號，不可重複 (Unique) | | `name` | String | **是** | 訂單名稱或客戶名稱 (最多 255 字元) | | `warehouse_code` | String | **是** | 指定扣除庫存的倉庫代碼 (例如：`api-test-01` 測試倉)。若找不到對應倉庫將直接拒絕請求 | | `payment_method` | String | 否 | 付款方式，僅接受：`cash`, `credit_card`, `line_pay`, `ecpay`, `transfer`, `other`。預設為 `cash` | | `total_amount` | Number | **是** | 整筆訂單的總交易金額 (例如：500) | | `total_qty` | Number | **是** | 整筆訂單的商品總數量 (例如：5) | | `sold_at` | String(Date) | 否 | 交易發生時間，預設為當下時間 (格式: YYYY-MM-DD HH:mm:ss) | | `items` | Array | **是** | 訂單明細陣列，至少需包含一筆商品 | #### `items` 陣列欄位說明： | 欄位名稱 | 型態 | 必填 | 說明 | | :--- | :--- | :---: | :--- | | `product_id` | Integer | **是** | **ERP 內部的商品 ID (`id`)**。請優先使用商品同步 API 取得此 ID | | `batch_number` | String | 否 | **商品批號**。若提供，將優先扣除該批號庫存；若該批號無剩餘或找不到，將自動 fallback 至 `NO-BATCH` 扣除 | | `qty` | Number | **是** | 銷售數量 (必須 > 0) | | `price` | Number | **是** | 銷售單價 | **注意**：請確保傳入正確的 `product_id` 以便 ERP 準確識別商品與扣除庫存。 **請求範例：** ```json { "external_order_id": "ORD-20231024-001", "name": "陳小明-干貝醬訂購", "warehouse_code": "STORE-01", "payment_method": "credit_card", "total_amount": 1050, "total_qty": 3, "sold_at": "2023-10-24 15:30:00", "items": [ { "product_id": 15, "batch_number": "BATCH-2024-A1", "qty": 2, "price": 500 } ] } ``` ### Response **Success (HTTP 201)** ```json { "message": "Order synced and stock deducted successfully", "order_id": 42 } ``` #### 錯誤回應 (HTTP 422 Unprocessable Entity - 驗證失敗) 當傳入資料格式有誤、商品 ID 於系統中不存在（如 `items` 內傳入了無法辨識的商品 ID），或是倉庫代碼無效時返回。 - **`message`** (字串): 錯誤摘要。 - **`errors`** (物件): 具體的錯誤明細列表，能一次性回報多個商品不存在或其它欄位錯誤。 ```json { "message": "Validation failed", "errors": { "items": [ "The following product IDs are not found: 15, 22. Please ensure these products exist in the system." ], "warehouse_code": [ "Warehouse with code STORE-999 not found." ] } } ``` #### 錯誤回應 (HTTP 500 Internal Server Error - 伺服器異常) 當系統發生預期外的錯誤（如資料庫連線失敗）時返回。 ```json { "message": "Sync failed: An unexpected error occurred." } ``` --- ## 幂等性說明 (Idempotency) 訂單 API 支援幂等性處理：若傳入已存在的 `external_order_id`，系統不會報錯，而是回傳該訂單的資訊： ```json { "message": "Order already exists", "order_id": 42 } ``` 這讓第三方系統在網路問題導致重送時，不會產生重複訂單或重複扣庫。 --- ## 常見問題與除錯 (FAQ) 1. **收到 `401 Unauthorized` 錯誤？** - 請檢查請求標頭 (Header) 是否有正確攜帶 `Authorization: Bearer {Token}`。 - 確認該 Token 尚未過期或被撤銷。 2. **收到 `422 Unprocessable Entity` 錯誤？** - 代表傳送的 JSON 欄位不符合格式要求，例如必填欄位遺漏、數量為負數、或 `payment_method` 不在允許的值中。Laravel 會在回應的 `errors` 物件中詳細說明哪個欄位驗證失敗。 3. **收到 `429 Too Many Requests` 錯誤？** - 代表已超過速率限制（每分鐘 60 次），請稍後再試。 4. **庫存扣除邏輯** - POS 訂單寫入視為「已發生之事實」，系統會無條件扣除庫存。若該產品在指定倉庫原先庫存為 0，訂單寫入後庫存將變為負數，提醒門市人員需進行調撥補貨。