📘 SMS API 接口文檔

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

1. 發送 SMS（Bulk SMS Send）

支持向多個全球或港澳台號碼批量提交發送自定義簡訊內容。

接口地址

請求參數 (JSON Body)

參數名	類型	必填	說明
user	String	是	API 商戶帳號
pwd	String	是	API 商戶密碼
phone	String	是	接收簡訊的手機號碼。多個號碼請用英文半形逗號 (,) 分隔，須含國際區號（如 85288888888,85299999999）。
msg	String	是	發送的簡訊文本內容。
sender	String	否	簡訊發送者名稱（Sender ID / 品牌簽名），如無指定可傳空字串 ""。

請求示例 (Payload)

{
  "user": "852555555",
  "pwd": "j1iaauc4",
  "phone": "85288888888",
  "msg": "這是一條測試短信",
  "sender": ""
}

響應參數

參數名	類型	說明
code	String	狀態碼。1 代表提交成功，其他代碼代表失敗。
msg	String	詳細說明或錯誤原因（如：提交成功）。
list	Object	提交結果統計數據物件。
└ total	Integer	本次請求提交的手機號碼總數量。
└ success	Integer	成功進入發送隊列的條數。
└ msg_hash	String	任務唯一識別碼（批次 Hash），用於後續查詢發送狀態。

返回示例 (JSON)

{
  "msg": "提交成功",
  "code": "1",
  "list": {
    "total": 1,
    "success": 1,
    "msg_hash": "d25d1e44-91c9-4a49-921a-6f728679cb06"
  }
}

2. 查詢發送狀態（Query Status via URL）

通過 URL 查詢參數（Query String）實時獲取簡訊批次任務的投遞狀態。

接口地址

請求參數 (URL Query)

參數名	類型	必填	說明
user	String	是	API 商戶帳號
pwd	String	是	API 商戶密碼
msg_hash	String	是	發送 SMS 時系統返回的任務唯一識別碼（msg_hash）。

請求網址示例

http://<server_ip>/publicApi/hk/sms/sms_api_msg?user=test&pwd=test&msg_hash=d25d1e44-91c9-4a49-921a-6f728679cb06

3. 查詢發送狀態（Query Status via JSON Body）

通過請求體傳入 JSON 參數進行狀態查詢，適合密鑰安全傳輸與高併發對接場景。

接口地址

請求參數 (JSON Body)

參數名	類型	必填	說明
user	String	是	API 商戶帳號
pwd	String	是	API 商戶密碼
msg_hash	String	是	發送 SMS 時系統返回的任務唯一識別碼（msg_hash）。

請求示例 (Payload)

{
  "user": "852555555",
  "pwd": "j1iaauc4",
  "msg_hash": "d25d1e44-91c9-4a49-921a-6f728679cb06"
}

狀態查詢接口響應參數（接口 2 與 接口 3 通用）

參數名	類型	說明
code	String	狀態碼。1 代表查詢成功。
msg	String	詳細說明。
list	Array	簡訊狀態明細列表（包含批次內各號碼的投遞詳情）。
└ phone	String	接收簡訊的手機號碼。
└ rate	String	簡訊發送單價。
└ charge	String	本次扣費總金額（rate * 條數）。
└ status	String	文字狀態描述：發送中 / 成功 / 失敗。
└ status_code	String	狀態數字碼： 0 待發送 | 1 發送中 | 2 發送成功 | 3 發送失敗
└ create_date	String	商戶提交任務的時間。
└ delivery_date	String	電信商回傳的回執送達時間（如尚未送達則為空）。
└ final_result	String	電信商原始回執最終狀態碼，詳見下方說明。
└ remark	String	系統備註。

返回示例 (JSON)

{
  "msg": "查詢成功",
  "code": "1",
  "list": [
    {
      "delivery_date": "",
      "charge": "0.840",
      "phone": "85288888888",
      "rate": "0.420",
      "remark": "",
      "status": "發送中",
      "status_code": "1",
      "create_date": "2025-11-24 16:05:50.0",
      "final_result": ""
    }
  ]
}

📋 電信商最終回執狀態（final_result）說明