共通規範¶
格式與型別¶
| 項目 | 規則 | 範例 |
|---|---|---|
| 格式 | JSON、UTF-8，Content-Type: application/json |
|
| 欄位命名 | 英文 snake_case | trade_record_id |
| 代碼值 | 英文大寫＋底線 | DINE_IN |
| 國家 | ISO 3166-1 alpha-2 | US、JP、TW |
| 幣別 | ISO 4217；小數位數依幣別 | USD 2 位、JPY 0 位、KWD 3 位 |
| 金額（decimal string） | 字串表示的十進位數，句點為小數點，小數位數須符合幣別；禁止使用 JSON number | "1234.50"、"-3.00" |
| 數量（decimal string） | 字串表示的十進位數（支援秤重品項） | "1"、"0.5" |
| 稅率 | 字串表示的小數（非百分比） | "0.09" = 9% |
| 時區 | IANA 時區名稱 | America/Los_Angeles |
| 時間（timestamp） | ISO 8601，必須含時區位移 | 2026-10-14T19:32:05-07:00 |
| 營業日（date） | YYYY-MM-DD，門市當地日期，依門市 workday_start 切日 |
2026-10-14 |
| 語言 | BCP 47 | en-US、ja-JP、zh-TW |
| 多語系文字 | 物件，key 為 BCP 47、value 為字串，至少一個 key | {"en-US":"Fries","zh-TW":"薯條"} |
| UUID | RFC 4122 字串 | 0b8d6c1e-1111-4a2b-9c3d-222233334444 |
金額請用字串
"amount": "24.51" 正確；"amount": 24.51 會被拒收（400 INVALID_PAYLOAD）。金額一律為門市當地幣別，不需換算匯率。
請求限制¶
| 項目 | 上限 |
|---|---|
| 每次請求記錄筆數 | 500 筆（或總部為該合作夥伴設定的上限，取較小者） |
| 請求本文大小 | 5 MB |
| 呼叫頻率 | 每個合作夥伴每分鐘 120 次 |
共通 Request Header¶
| Header | 必填 | 說明 |
|---|---|---|
x-functions-key |
Y（/health 除外） |
{api_key}，總部核發的 API 金鑰 |
Content-Type |
PUT/POST 必填 | application/json |
共通 Response Header¶
| Header | 說明 |
|---|---|
X-Request-Id |
每次請求的唯一識別碼。回報問題時請提供此值 |
Retry-After |
僅 429 回應，建議等待秒數 |
回應格式¶
寫入成功回 202，重複的 batch_id 回 200 ALREADY_RECEIVED。錯誤格式與代碼見錯誤代碼一覽表。
{ "batch_id": "0b8d6c1e-1111-4a2b-9c3d-222233334444", "status": "ACCEPTED", "record_count": 200, "warnings": [] }
版本政策¶
- 路徑含主版本
/v1。 - 新增欄位（請求選填欄位或回應欄位）不升版，呼叫端須忽略不認得的回應欄位。
- 刪除或變更欄位意義時升至
/v2，並與/v1並行一段期間。
個資限制¶
所有端點禁止傳送：完整卡號、CVV、持卡人姓名、顧客姓名／電話／Email／地址。卡號僅允許末四碼（card_last4）。
會員只能以會員代碼（member_id）識別。代碼須為合作夥伴會員系統內部的 ID，不得直接使用手機號碼、Email 或身分證號等個資當作會員代碼。若會員系統以手機號碼為主鍵，請改送內部流水號，或送雜湊值（例 SHA-256 加 salt）。