# 商品查詢 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)
```json
{
    "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` 格式錯誤）。