門市¶

PUT /stores

門市主檔批次 upsert：依 store_id 新增或更新。請在上線前，或門市資料異動時送出。

權限¶

API 金鑰（x-functions-key）

Request¶

Header	必填	說明
x-functions-key	Y	`{api_key}`
Content-Type	Y	`application/json`

Body

欄位	型別	必填	說明
batch_id	UUID	Y	冪等鍵
stores	array of Store	Y	1～500 筆；每筆 `store_id` 須為總部登記給合作夥伴的門市

Store¶

欄位	型別	必填	說明
store_id	string	Y	門市代碼（合作夥伴內唯一）
store_name	string	Y	門市名稱
country_code	string	Y	ISO 3166-1 alpha-2
currency	string	Y	ISO 4217，該門市所有金額使用此幣別
time_zone	string	Y	IANA 時區
locale	string	Y	BCP 47
workday_start	string	Y	營業日切日時間 `HH:mm`（門市當地時間），例 `04:00` 表示凌晨 4 點前的交易算前一營業日
prices_include_tax	boolean	Y	商品售價是否含稅
status	enum	Y	`ACTIVE` / `INACTIVE`
last_modified_at	timestamp	Y	最後異動時間

範例¶

{
  "batch_id": "3a9e7d10-5f2b-4c8e-8d11-0a1b2c3d4e5f",
  "stores": [
    {
      "store_id": "US001",
      "store_name": "Main St",
      "country_code": "US",
      "currency": "USD",
      "time_zone": "America/Los_Angeles",
      "locale": "en-US",
      "workday_start": "04:00",
      "prices_include_tax": false,
      "status": "ACTIVE",
      "last_modified_at": "2026-10-14T10:00:00-07:00"
    }
  ]
}

Response¶

202 Accepted

{ "batch_id": "3a9e7d10-5f2b-4c8e-8d11-0a1b2c3d4e5f", "status": "ACCEPTED", "record_count": 1, "warnings": [] }

同一 batch_id 重送回 200 ALREADY_RECEIVED。

錯誤¶

HTTP	code	情況
400	INVALID_PAYLOAD	格式、必填、代碼錯誤
400	BATCH_TOO_LARGE	筆數超過上限
401	UNAUTHORIZED	未帶 API 金鑰或金鑰錯誤
403	STORE_NOT_ALLOWED	`store_id` 不屬於該合作夥伴
413	PAYLOAD_TOO_LARGE	請求本文超過 5 MB

注意事項¶

Note

新門市請先聯絡總部登記 store_id，登記後才能推送該門市資料。
workday_start 決定交易歸屬的營業日，請與 POS 的日結切點一致。
currency 必須與該門市交易、日結的幣別相同。