商戶管理 API — Agent 指南
Base:https://<站台網域>/api/merchant/v1 認證:Authorization: Bearer <管理 Key> /llms.txt /docs
端點(🔒 = 保險絲管制)
GET /api/merchant/v1/me — 無需 scope — Key 自身:id/label/prefix/last4/scopes、保險絲狀態、限流資訊(limit/remaining/resetAt)、platform {id,name}、maxSpreadPct、defaultSpreadPct(手續費 %,字串|null)
GET /api/merchant/v1/channels — channels:read — 渠道列表(同後台 GET /api/platform/channels 回應)
POST /api/merchant/v1/channels — channels:write — 建渠道(body 同後台;system 型可帶 fieldMappings)
GET /api/merchant/v1/channels/:id — channels:read — 渠道詳情
PATCH /api/merchant/v1/channels/:id — channels:write — 改資料、三網址(quoteUrl/createOrderUrl/callbackUrl)、payUrlHostAllowlist、手續費 defaultSpreadPct(單一費用 %,字串|null,最多 3 位小數、可負=讓利;null=沿用商戶層;|值|>maxSpreadPct 422 SPREAD_EXCEEDS_LIMIT);改 URL 自動下線
DELETE /api/merchant/v1/channels/:merchantId — channels:write — 解綁(409 CHANNEL_HAS_OPEN_ORDERS)
POST /api/merchant/v1/channels/:merchantId/pause — channels:write — 停用
POST /api/merchant/v1/channels/:merchantId/resume — channels:write — 啟用
GET /api/merchant/v1/channels/:id/onboarding-status — channels:read — 上線檢查結果
PATCH /api/merchant/v1/channels/:id/online — channels:write — body {isOnline:boolean} 上線/下線(須通過檢查)
POST /api/merchant/v1/channels/:id/test-quote — channels:write — 測試詢價(真打)
POST /api/merchant/v1/channels/:id/test-create-order — channels:write — 測試建單(真打,不產生訂單)
POST /api/merchant/v1/channels/:id/test-callback — channels:write — 發回打測試單號
POST /api/merchant/v1/channels/:id/webhook-test — channels:write — 測試推送
POST /api/merchant/v1/channels/:id/quote-test — channels:read — 詢價試算(不持久化)
GET /api/merchant/v1/channels/:id/webhook-logs — channels:read — 推送紀錄(limit/offset)
GET /api/merchant/v1/channels/:id/quote-logs — channels:read — 詢價紀錄(page/limit)
GET /api/merchant/v1/channels/:id/field-mappings — channels:read — 欄位映射
PUT /api/merchant/v1/channels/:id/field-mappings — mappings:write — 整組取代 body {mappings:[{mappingType,ourField,merchantField,notes?}]}
POST /api/merchant/v1/channels/:id/field-mappings — mappings:write — 新增一筆
PATCH /api/merchant/v1/channels/:id/field-mappings/:mappingId — mappings:write — 改一筆
DELETE /api/merchant/v1/channels/:id/field-mappings/:mappingId — mappings:write — 刪一筆
POST /api/merchant/v1/channels/:id/field-mappings/suggest — channels:read — 貼 JSON 樣本 body {kind:"quote"|"create"|"webhook", sample:object} → {suggestions:[{ourField,merchantField,confidence,candidates[]}], unmatched:[ourField]}
POST /api/merchant/v1/channels/:id/webhook-secret/rotate 🔒 — integration:write — 重置渠道 Webhook Secret
GET /api/merchant/v1/channels/:id/credentials — integration:read — 回打憑證(masked:keyLast4、issuedAt、hasSecret)
POST /api/merchant/v1/channels/:id/credentials/rotate 🔒 — integration:write — 輪替回打憑證(一次性回明文)
PUT /api/merchant/v1/channels/:id/allowed-ips 🔒 — integration:write — 渠道回打 IP 白名單
GET /api/merchant/v1/webhook — integration:read — 商戶 Webhook URL
PUT /api/merchant/v1/webhook 🔒 — integration:write — 改 Webhook URL body {webhookUrl}
PUT /api/merchant/v1/default-spread — integration:write — 改商戶層手續費 body {defaultSpreadPct}(單一費用 %,字串|null;最多 3 位小數、可負=讓利);系統依方向套用(客戶買 ref×(1+pct/100)、客戶賣 ref×(1−pct/100));建單未帶 customerRate/fiatAmount 時套用,|值|>maxSpreadPct 回 422 SPREAD_EXCEEDS_LIMIT
PUT /api/merchant/v1/max-spread-pct — integration:write — 改最大價差(目前值由 GET /me 的 maxSpreadPct 讀取)body {maxSpreadPct:"5.00"}(0–100、2 位小數);商戶自訂客戶匯率/法幣數額與渠道參考匯率的差距上限,超過下單回 422 SPREAD_EXCEEDS_LIMIT
GET /api/merchant/v1/webhook-logs — integration:read — 商戶推送紀錄
POST /api/merchant/v1/webhook-test — integration:write — 測試推送到商戶 Webhook
GET /api/merchant/v1/allowed-ips — integration:read — 交易 API Key IP 白名單
PUT /api/merchant/v1/allowed-ips 🔒 — integration:write — 改白名單 body {allowedIps:string[]|null}
GET /api/merchant/v1/api-key — integration:read — 交易 API Key(masked)
POST /api/merchant/v1/api-key/rotate 🔒 — integration:write — 輪替交易 API Key(一次性回明文)
GET /api/merchant/v1/approvals — 無需 scope — 本 Key 相關待確認列表 ?status=pending|approved|rejected|expired|all
GET /api/merchant/v1/approvals/:id — 無需 scope — 單筆狀態;approved 時含 result(含一次性明文,僅第一次 GET 回傳後清除)
GET /api/merchant/v1/orders — orders:read — 訂單列表 ?status&channelId&limit&offset
GET /api/merchant/v1/orders/:id — orders:read — 訂單詳情
GET /api/merchant/v1/account — account:read — 金庫餘額+平台費(同後台 /api/platform/account)
GET /api/merchant/v1/account/ledger — account:read — 金庫流水 ?limit&offset錯誤碼
- MISSING_MANAGEMENT_KEY(HTTP 401)— 未帶 Authorization: Bearer <管理 Key>
- INVALID_MANAGEMENT_KEY(HTTP 401)— 管理 Key 無效(例如誤用交易 API Key 打管理 API)
- MANAGEMENT_KEY_REVOKED(HTTP 401)— 管理 Key 已被吊銷,請在後台重新建立
- MANAGEMENT_KEY_EXPIRED(HTTP 401)— 管理 Key 已過期,請在後台重新建立
- IP_NOT_ALLOWED(HTTP 403)— 來源 IP 不在此 Key 的 allowedIps 內
- INSUFFICIENT_SCOPE(HTTP 403)— 缺少 scope;回應含 requiredScope 欄位
- RATE_LIMITED(HTTP 429)— 每把 Key 每分鐘 120 次;依 Retry-After 稍後重試
- IDEMPOTENCY_MISMATCH(HTTP 409)— 同一 Idempotency-Key 但 body 不同
- IDEMPOTENCY_IN_PROGRESS(HTTP 409)— 同一 Idempotency-Key 的請求仍在處理中
- VALIDATION_ERROR(HTTP 400)— 請求參數不合法
- CHANNEL_NOT_FOUND(HTTP 404)— 找不到渠道(或不屬於此商戶)
- APPROVAL_NOT_FOUND(HTTP 404)— 找不到待確認記錄
- APPROVAL_NOT_PENDING(HTTP 409)— 待確認記錄已不是 pending(已處理或過期)
- CHANNEL_NOT_SYSTEM(HTTP 400)— 此操作僅限 system 型渠道
- URL_REQUIRED(HTTP 400)— 上線前須先設定必要網址
- WEBHOOK_URL_BLOCKED(HTTP 400)— Webhook URL 被安全檢查擋下(內網/不允許的位址)
- MAPPING_DUPLICATE(HTTP 409)— 欄位映射重複
- CHANNEL_HAS_OPEN_ORDERS(HTTP 409)— 渠道仍有未結訂單,無法解綁
規則(認證、限流、冪等、保險絲)
【認證】Authorization: Bearer $MK(管理 Key,mk_<prefix>_<secret>)。管理 Key 與交易 API Key(x-api-key)完全分開:互相打對方的 API 一律 401。管理 Key 由人類在商戶後台建立,明文只顯示一次。
【限流】每把 Key 每分鐘 120 次;超過回 429 RATE_LIMITED 並帶 Retry-After。GET /me 可看 limit/remaining/resetAt。
【冪等】所有寫操作(POST/PUT/PATCH/DELETE)請帶 Idempotency-Key header(1–128 字),伺服器保存 24 小時(每把 Key 獨立):
1. 同 key+同 body:回傳原 status 與 body,並加 header Idempotent-Replayed: true。
2. 同 key+不同 body:409 IDEMPOTENCY_MISMATCH。
3. 同 key 仍在處理中:409 IDEMPOTENCY_IN_PROGRESS(稍後用同 key 重試)。
【保險絲】標 🔒 的高敏感操作,在商戶保險絲開啟(預設開)時不會立即執行,而是回 202:{ "success": true, "status": "pending_approval", "approvalId": "...", "actionType": "...", "expiresAt": "..." }。流程:202 → 通知人類到後台「待確認」確認(需 TOTP)→ 用 GET /approvals/:id 查結果(approved 時含 result;一次性明文只在第一次 GET 回傳)。待確認 24 小時過期(expired)。保險絲關閉時直接執行並回 200。
actionType:platform.api_key.rotate、platform.webhook_url.set、platform.allowed_ips.set、channel.webhook_secret.rotate、channel.credentials.rotate、channel.allowed_ips.set。
【定價模型(v1.16)】渠道只認「法幣數額該收/該出多少」;渠道報價只是參考匯率(訂單 referenceRate)。商戶下單(POST /api/v1/orders/topup|withdraw 的 channelId/quoteId 路徑)可選自訂給客戶的價:買單 quoteId 路徑請帶 customerRate;fiatAmount 只能搭配 channelId+crypto+currency+cryptoAmount 形狀({quoteId, fiatAmount} 回 400 AMBIGUOUS_PRICE_SOURCE);賣單 withdraw 的 quoteId 路徑 customerRate/fiatAmount 皆可;兩者同帶但不一致 422 RATE_AMOUNT_CONFLICT,價差超過 maxSpreadPct 422 SPREAD_EXCEEDS_LIMIT(回應含 hint/maxSpreadPct/referenceRate);同 refId 重送但 customerRate/fiatAmount 不同 409 REF_ID_MISMATCH(交易 API 冪等靠 refId,不用 Idempotency-Key)。訂單 fiatAmount=商戶定的數額=建給渠道的數字;渠道端 payload 的 rate=參考匯率、不含 customerRate。訂單與 webhook 另帶 referenceRate/customerRate(null=等於參考)。【手續費(預設價差)v1.16.0-rc3】商戶只設一個數字 defaultSpreadPct(費用 %);優先序:請求 customerRate/fiatAmount > 渠道 defaultSpreadPct > 商戶 defaultSpreadPct(PUT /default-spread)> 參考價原價;系統依方向套用:客戶買 customerRate=參考×(1+pct/100),客戶賣=參考×(1−pct/100);正數=商戶多收、負數=讓利(兩邊同時);值字串、最多 3 位小數,|值|>maxSpreadPct 回 422 SPREAD_EXCEEDS_LIMIT(extra.maxSpreadPct)。渠道層由 PATCH /channels/:id(channels:write)的 defaultSpreadPct 設定,null=沿用商戶層;舊的 defaultSpreadBuyPct/defaultSpreadSellPct 已移除。訂單與 webhook 回 appliedSpreadPct(=設定值,帶符號;請求自帶定價時買單=(customerRate−ref)/ref、賣單=(ref−customerRate)/ref;無="0",舊單 null;後台一律照原值顯示,不換算方向)、appliedSpreadSource(request|channel|merchant|none);fiatAmount 取位依幣別(THB/HKD/CNY 2 位、IDR 0 位,half-up;IDR 帶小數回 400 INVALID_AMOUNT_PRECISION);POST /api/v1/quotes 與 GET /api/v1/channels 回 customerRate、appliedSpreadPct、appliedSpreadSource(channel|merchant|none)。平台不算商戶與渠道的差額、不出結算報表。
【永不開放】帳號、密碼、2FA、登入、管理 Key 的建立與吊銷,只能由人類在後台操作。
【錯誤格式】{ "success": false, "error": "<CODE>", "code": "<CODE>", "message": "...", "hint": "英文下一步建議", "docs": "/docs/agent-guide#<code 小寫>" }。缺 scope 時為 403 INSUFFICIENT_SCOPE 並帶 requiredScope。最小可用範例
BASE=https://<your-site-domain> # 站台網域,例如白標站 https://pay.example.com
MK=mk_xxxxxxxx_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx # 後台建立的管理 Key
# 1) 建 system 型渠道(需 channels:write)
curl -sS -X POST "$BASE/api/merchant/v1/channels" \
-H "Authorization: Bearer $MK" -H "Idempotency-Key: create-ch-001" \
-H "Content-Type: application/json" \
-d '{"name":"My Channel","contactEmail":"[email protected]","channelType":"system","quoteUrl":"https://ch.example.com/quote","createOrderUrl":"https://ch.example.com/orders","callbackUrl":"https://ch.example.com/callback"}'
# 2) 整組取代欄位映射(需 mappings:write;CHANNEL_ID 取自上一步回應)
curl -sS -X PUT "$BASE/api/merchant/v1/channels/$CHANNEL_ID/field-mappings" \
-H "Authorization: Bearer $MK" -H "Idempotency-Key: map-ch-001" \
-H "Content-Type: application/json" \
-d '{"mappings":[{"mappingType":"quote_field","ourField":"rate","merchantField":"data.price"}]}'
# 3) 上線(需 channels:write;須通過上線檢查)
curl -sS -X PATCH "$BASE/api/merchant/v1/channels/$CHANNEL_ID/online" \
-H "Authorization: Bearer $MK" -H "Idempotency-Key: online-ch-001" \
-H "Content-Type: application/json" -d '{"isOnline":true}'
# 4) 查上線檢查結果(需 channels:read)
curl -sS "$BASE/api/merchant/v1/channels/$CHANNEL_ID/onboarding-status" \
-H "Authorization: Bearer $MK"