📘 OTP API 接口文檔

⚠️ API 帳號/密碼、IP 白名單配置、接口伺服器地址，請聯繫管理員獲取！

版本：v2.0 | 更新日期：2026-05-21

1. 發送 OTP（Send OTP）

向指定的海外或港澳台手機號碼發送驗證碼簡訊。

接口地址

GET / POST /publicApi/hk/sms/otp_api_foreign

請求參數

參數名	類型	必填	說明
user	String	是	API 商戶帳號
pwd	String	是	API 商戶密碼
phone	String	是	接收簡訊的手機號碼。注意：須包含國際區號，例如香港：`85252525252`
code	String	是	根據是否傳入 `tid`，此欄位定義不同： 1. 未傳 tid (自定義內容)：須填寫完整簡訊文本。範例：`【品牌簽名】您的驗證碼為:123456 (有效時間5分鐘)` 2. 已傳 tid (模板模式)：只需填寫純驗證碼變數值。範例：`123456`
sign	String	是	安全簽名驗證。生成規則：`MD5(phone + "\|" + code + "\|otp")` 注意：MD5 結果須轉為 32 位小寫字串。
sender	String	否	簡訊發送者名稱（Sender ID / 品牌簽名）
tid	String	否	系統模板 ID。填寫後系統將自動調用對應模板，並將 `code` 欄位的值替換至模板中的 `{code}` 變數。

📋 簡訊自定義內容範例：
【AAA】驗證碼為:123456 (有效時間5分鐘)
⚠️ 註：自定義內容模式下，code 參數值發送前請務必進行 URL 編碼（URL Encode）。

💡 請求網址示例 (GET)

1. 自定義內容模式（未傳 tid）：

http://<server_ip>/publicApi/hk/sms/otp_api_foreign?user=admin&pwd=123456&sign=2bd9260149a085c269876abf734ab607&phone=85252422222&code=%E3%80%90AAA%E3%80%91%E9%A9%97%E8%AD%89%E7%A2%BC%E7%82%BA:111111(%E6%9C%89%E6%95%88%E6%99%82%E9%96%935%E5%88%86%E9%90%98)

2. 模板模式（已傳 tid=1）：

http://<server_ip>/publicApi/hk/sms/otp_api_foreign?user=admin&pwd=123456&sign=2bd9260149a085c269876abf734ab607&phone=85252422222&code=111111&tid=1

響應參數

參數名	類型	說明
code	String	狀態碼。`0` 表示成功，其他代碼請參考錯誤代碼表
msg	String	詳細說明或失敗原因

返回示例 (JSON)

{
  "code": "0",
  "msg": "发送成功!"
}

2. 查詢餘額（Query Balance）

查詢商戶帳戶的當前可用餘額及凍結金額。

接口地址

GET / POST /publicApi/hk/sms/otp_api_balance

示例 URL

http://<server_ip>/publicApi/hk/sms/otp_api_balance?user=test&pwd=test

請求參數

參數名	類型	必填	說明
user	String	是	API 商戶帳號
pwd	String	是	API 商戶密碼

響應參數

參數名	類型	說明
code	String	狀態碼。`1` 表示查詢成功
msg	String	詳細說明
list	Array	數據列表嵌套物件
└ balance	String	帳戶可用餘額
└ freeze	String	帳戶凍結金額

返回示例 (JSON)

{
  "code": "1",
  "msg": "查詢成功",
  "list": [
    {
      "balance": "126764.080",
      "freeze": "0.000"
    }
  ]
}

3. 錯誤代碼（Error Codes）

狀態碼	說明
0	發送成功
101	接口關閉，請聯繫客服人員！
102	IP 未加白名單，請聯繫管理員配置！
103	帳戶或密碼不正確，請檢查後重新提交！
104	安全簽名（sign）無效
105	驗證碼內容（code）超出長度範圍
106	帳戶餘額不足
-1	發送失敗