Skip to main content
Version: 1.0.0

S2S API 介接

合作夥伴與本平台之間的 Server-to-Server 介接。

所有 S2S API 都以 OAuth 2.0 Client Credentials Grant 認證。開始串接業務 API 前, 請先完成「開始串接」的兩支 API,確認憑證、授權與連線皆正常。

介接流程​

  1. 開始串接:取得 Client Token,再呼叫串接測試(ping) 確認 token 與授權設定
  2. 用戶註冊:取得同意條款,代用戶註冊帳戶,之後可查詢用戶資訊與目前所在階段
  3. 代碼與選項:取得表單選項與回傳代碼的顯示名稱,供後續 KYC 與卡片 API 使用
  4. 會員 KYC:填寫草案、提交申請、查詢審核結果;需要補件時依待補件欄位補齊後確認送審
  5. 卡片:檢查申請資格、申請卡片,配發後寄送啟用碼並啟用卡片

各階段的 API 依建議的呼叫順序排列在左側目錄。

環境變數​

建議將下列值存為環境變數,不要寫死在 request 內。

變數說明
auth-base-url認證服務位址(取得 Client Token、用戶註冊)
api-base-url業務 API 服務位址(串接測試、用戶、代碼與選項、會員 KYC)
card-base-url卡片服務位址(卡片)
s2s-client-id本平台配發的 client id
s2s-client-secret本平台配發的 client secret

client 憑證由本平台於介接作業開始時另行提供,請妥善保管,勿提交至版本控制或前端程式碼。

共用 Header​

Header說明
Authorization所有業務 API 必帶,格式 Bearer {accessToken}
X-Company-Uid企業用戶編號,也就是合作夥伴系統內的用戶編號,於註冊時與本平台帳戶綁定。針對單一用戶的 API 以此指定要操作的用戶
X-Idempotency-Key冪等鍵,會寫入資料的 API 必帶。由呼叫端產生 UUID,同一把鍵只會實際執行一次;結果不明時以同一把鍵重送即可
Accept-Language選填,回應語系,可為 en-US、zh-TW、zh-CN,影響錯誤訊息與顯示名稱;未帶或不支援時使用系統預設語系

操作對象與所屬專案一律由 client token 與 X-Company-Uid 決定,不由 request body 指定, 因此一組 client 只能存取自己的用戶。

回應格式​

所有 API 共用同一組回應外層:成功時資料放在 result,失敗時由 code、message、detail 帶回錯誤資訊。

Authentication​

帶入取得 Client Token 回傳的 result.accessToken,格式 Authorization: Bearer {accessToken}。

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer