一、接入流程
機構開通後即可在機構工作枱創建 API 密鑰，用密鑰簽名調用開放接口。
| 步驟 | 操作 | 說明 |
|---|
| 1 | 申請機構帳號 | 通過 商務聯繫頁 提交申請，我們完成資質審核後開通機構帳號。 |
| 2 | 工作枱創建密鑰 | 登入 機構工作枱，在「API 密鑰」創建 AccessKey / SecretKey，配置 QPS 與每日配額。 |
| 3 | 充值或配置賬期 | 按次計費從機構餘額扣減；餘額不足返回 4050。 |
| 4 | 簽名調用接口 | 用 HMAC-SHA256 對待簽串簽名，隨請求頭攜帶，逐商品調用。 |
二、接口鉴权
密鑰在創建時完整展示一次，SecretKey 僅此一次可見，洩露可在工作枱即時重置。
| 請求頭 | 說明 |
|---|
| X-AK | AccessKey 標識 |
| X-Timestamp | 請求時間戳（秒）。與服務端偏差超過容忍窗口返回 4071 |
| X-Nonce | 一次性隨機串，同一 nonce 在窗口內不可重複，重複返回 4072 |
| X-Signature | 對下述待簽串的 HMAC-SHA256（Base64）簽名值 |
待簽串（以換行符 \n 連接）：
AccessKey + "\n" + Timestamp + "\n" + Nonce + "\n" + productCode
計算簽名：
X-Signature = Base64( HMAC_SHA256( SecretKey, 待簽串 ) )
端點：POST /open/v1/{productCode} productCode 為路徑參數，同時參與簽名。
三、請求示例
curl -X POST "https://api.herecredit.com.hk/open/v1/ENT_BASIC" \
-H "X-AK: ak_live_xxxxxxxxxxxx" \
-H "X-Timestamp: 1760000000" \
-H "X-Nonce: 8f2c1a9d4e" \
-H "X-Signature: <Base64(HMAC-SHA256)>" \
-H "Content-Type: application/json" \
-d '{
"requestId": "req_20261019_093812",
"purpose": "DUE_DILIGENCE",
"uscc": "91330100MA2****001"
}'
合規內建：每次調用必須攜帶 purpose。平台逐筆比對「本次用途」與「該數據源允許用途」，不匹配直接返回 4030 且不計費。
四、返回信封
所有響應使用統一信封，業務性結果（含合規拒絕）一律以 HTTP 200 + 業務 code 返回，便於用同一套邏輯處理。
{
"code": "0", // "0" 為成功；其餘為業務碼
"message": "success",
"data": { // 查詢結果（訂單號、狀態、費用、餘額、主體資訊、數據來源、報告編號/核驗碼…）
"orderNo": "ORD20261019...",
"status": "SUCCESS",
"cost": 0.20,
"dataSources": [ ... ]
},
"billing": { "productCode": "ENT_BASIC", "cost": 0.20, "balance": 99647.60 }
}
五、商品與定價
能力即商品：每個能力有獨立編碼、獨立定價、獨立場景。正在載入商品……
調用失敗或合規拒絕不計費；同一 requestId 重複提交不重複計費（冪等）。個人信貸資料類商品僅限信資通會員機構調用，非會員調用返回 4042。
六、錯誤碼
| code | 含義與處理 |
|---|
| 0 | 成功 |
| 4000 | 參數不合法——主體（subjectId / uscc / name）需三選一，商品碼需存在 |
| 4030 | 用途不匹配：本次用途不在數據源允許範圍內，已拒絕且不計費 |
| 4031 | 分層準入：個人信貸資料僅限信資通會員機構查詢 |
| 4040 | 主體不存在 |
| 4041 | 商品不存在或未啟用 |
| 4042 | 該商品僅限會員機構調用 |
| 4050 | 賬戶可用餘額不足 |
| 4070 | 簽名校驗失敗——核對待簽串順序與 SecretKey |
| 4071 | 請求已過期——校準本地時鐘後重試 |
| 4072 | 重複請求——nonce 已使用，每次調用生成新 nonce |
| 4080 | 超出調用頻率限制（QPS） |
| 4081 | 超出當日調用配額 |
| 5000 | 系統繁忙，請稍後重試 |
關於個人信貸資料：速度貓國際控股有限公司為平安壹賬通信用服務（香港）有限公司（PAOCCRA）之推廣方；個人信貸資料服務由 PAOCCRA 提供，並僅向信資通會員機構開放。本平台不承接以自身名義的個人信貸資料查詢。
