Version: 1.0.0
S2S API 介接
合作夥伴與本平台之間的 Server-to-Server 介接。
所有 S2S API 都以 OAuth 2.0 Client Credentials Grant 認證。開始串接業務 API 前, 請先完成「開始串接」的兩支 API,確認憑證、授權與連線皆正常。
介接流程
- 開始串接:取得 Client Token,再呼叫串接測試(ping) 確認 token 與授權設定
- 用戶註冊:取得同意條款,代用戶註冊帳戶,之後可查詢用戶資訊與目前所在階段
- 代碼與選項:取得表單選項與回傳代碼的顯示名稱,供後續 KYC 與卡片 API 使用
- 會員 KYC:填寫草案、提交申請、查詢審核結果;需要補件時依待補件欄位補齊後確認送審
- 卡片:檢查申請資格、申請卡片,配發後寄送啟用碼並啟用卡片
各階段的 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
- HTTP: Bearer Auth
帶入取得 Client Token 回傳的 result.accessToken,格式 Authorization: Bearer {accessToken}。
Security Scheme Type: | http |
|---|---|
HTTP Authorization Scheme: | bearer |