交易型態對照¶

合作夥伴 POS 的交易代碼（例 Refund）各家不同，需透過對照表轉成總部標準交易型態（例 REFUND）。交易推送時只需送原始代碼（source_transaction_type），總部依對照表轉換。

上傳對照表¶

PUT /mappings/transaction-types

上傳「合作夥伴自家交易代碼 → 總部標準代碼」對照。整份取代：每次都要送完整清單，未列出的舊對照會失效。

權限¶

API 金鑰（x-functions-key）

Request¶

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

Body

欄位	型別	必填	說明
batch_id	UUID	Y	冪等鍵
mappings	array	Y	至少 1 筆
mappings[].source_code	string	Y	合作夥伴原始代碼（同一份內不可重複），即交易的 `source_transaction_type`
mappings[].source_name	string	N	合作夥伴原始名稱
mappings[].standard_code	string	Y	標準代碼，須存在於標準交易型態清單

範例¶

{
  "batch_id": "6f1c2e0a-3b7d-4c55-9a0e-1f2b3c4d5e6f",
  "mappings": [
    { "source_code": "Sale",   "source_name": "Sale",   "standard_code": "SALE" },
    { "source_code": "Refund", "source_name": "Refund", "standard_code": "REFUND" },
    { "source_code": "Void",   "source_name": "Void",   "standard_code": "VOID" }
  ]
}

Response¶

202 Accepted

{ "batch_id": "6f1c2e0a-3b7d-4c55-9a0e-1f2b3c4d5e6f", "status": "ACCEPTED", "record_count": 3, "warnings": [] }

同一 batch_id 重送回 200 ALREADY_RECEIVED。

錯誤¶

HTTP	code	情況
400	UNKNOWN_STANDARD_CODE	`standard_code` 不在標準清單
400	INVALID_PAYLOAD	缺欄位、`source_code` 重複等
401	UNAUTHORIZED	未帶 API 金鑰或金鑰錯誤

注意事項¶

整份取代

新增一個代碼時，也要把既有的對照一起送出，否則舊對照會失效。

Note

交易中出現尚未對照的 source_transaction_type 時，API 仍會照收，但該交易在補上對照前不會計入報表。

查詢對照表¶

GET /mappings/transaction-types

查詢自己目前生效的對照表。

權限¶

API 金鑰（x-functions-key）

Response¶

200 OK

欄位	型別	說明
partner_id	string	合作夥伴代碼
batch_id	UUID \| null	目前生效版本的 `batch_id`；尚未上傳過為 `null`
updated_at	timestamp \| null	最後更新時間（UTC）
mappings	array	同上傳格式；尚未上傳過為 `[]`

{
  "partner_id": "US-ADL-001",
  "batch_id": "6f1c2e0a-3b7d-4c55-9a0e-1f2b3c4d5e6f",
  "updated_at": "2026-10-15T09:00:00Z",
  "mappings": [
    { "source_code": "Refund", "source_name": "Refund", "standard_code": "REFUND" }
  ]
}

錯誤¶

HTTP	code	情況
401	UNAUTHORIZED	未帶 API 金鑰或金鑰錯誤