# SOHO Wallet / Stellabit — 商戶管理 API(給 AI Agent) > 商戶後台能做的事,管理 API 都能做。 Base URL:https://<站台網域>/api/merchant/v1(站台網域=您目前使用的站台,例如 https://stellabit.cc 或白標站網域) 認證:Authorization: Bearer <管理 Key>(mk_...)。管理 Key 由人類在商戶後台建立;與交易 API Key(x-api-key)不通用。 完整文件:/docs(「管理 API(給 Agent)」)、/docs/agent-guide ## 端點(🔒 = 保險絲管制,回 202 待人類確認) 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 ## 錯誤碼(錯誤回應含 hint 與 docs 欄位) 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__)。管理 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": "", "message": "...", "hint": "英文下一步建議", "docs": "/docs/agent-guide#" }。缺 scope 時為 403 INSUFFICIENT_SCOPE 並帶 requiredScope。 ## 最小可用範例 BASE=https:// # 站台網域,例如白標站 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":"ops@ch.example.com","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"