star-erp/docs/integration/products_api.md

商品查詢 API (External Product Fetch)

本 API 供外部系統（如 POS）從 Star ERP 獲取商品資料。支援分頁、關鍵字搜尋與增量同步。

1. 介面詳情

• Endpoint: GET /api/v1/integration/products
• Authentication: Bearer Token (Sanctum)
• Tenant Isolation: 需透過 X-Tenant-Domain Header 或網域識別租戶。

2. 請求參數 (Query Parameters)

參數名	類型	必填	說明
keyword	string	否	關鍵字搜尋（符合名稱、代碼、條碼或外部編號）。
category	string	否	分類名稱精準過濾（例如：飲品）。
updated_after	datetime	否	增量同步機制。僅回傳該時間點之後有異動的商品（格式：Y-m-d H:i:s）。
per_page	integer	否	每頁筆數（預設 50，最大 100）。
page	integer	否	分頁頁碼（預設 1）。

3. 回應結構 (JSON)

成功回應 (200 OK)

{
    "status": "success",
    "data": [
        {
            "id": 12,
            "code": "COKE-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
    }
}

4. 同步策略建議

初次同步 (Initial Sync)

1. 第一次串接時，不帶 updated_after。
2. 根據 meta.last_page 遍歷所有分頁，將全量商品存入 POS。

增量同步 (Incremental Sync)

1. 記錄上一次同步成功的時間戳記。
2. 定期調用 API 並帶入 updated_after={timestamp}。
3. 僅處理回傳的商品資料進行更新或新增。

5. 常見錯誤

• 401 Unauthorized: Token 無效或已過期。
• 422 Unprocessable Entity: 參數驗證失敗（例如 updated_after 格式錯誤）。