WINGSING 雲通訊平台 API 開發文檔 (V2.0)

1. 概述

歡迎使用 WINGSING 雲通訊平台 API。本文件旨在為開發者提供清晰、完整的接口說明，以實現您的應用系統與 WINGSING 平台之間的高效整合。

我們的 API 採用業界通用的 REST 風格設計，同時支持 HTTP 及 HTTPS 協議，並兼容 GET 與 POST 請求方式。為保障帳戶安全，每次 API 請求均須攜帶 username 和 password 參數，否則將被視為未經授權的請求並被系統拒絕。

API 請求基礎 URL:

• HTTP: http://%%SERVERIP:PORT%%/api

• HTTPS: https://%%SERVERIP:PORT%%/api

• 
  

2. 短信提交接口 (Submit SMS)

此接口用於向 WINGSING 平台提交單則或多則短信以進行發送。

2.1 請求參數說明

必填參數

選填參數

2.2 請求示例

GET 請求

http://%%SERVERIP:PORT%%/api?username=WS_USER_01&password=user_password&command=submit&ani=WINGSING&dnis=85291234567&message=Your%20verification%20code%20is%206688.&longMessageMode=split

POST 請求 (JSON)

curl -X POST 'http://%%SERVERIP:PORT%%/api?username=WS_USER_01&password=user_password&command=submit' \
-H 'Content-Type: application/json' \
-d '{
    "ani": "WINGSING",
    "dnis": "85291234567,85298765432",
    "message": "【WINGSING】This is a test message.",
    "longMessageMode": "split"
}'

2.3 響應格式

成功響應 (單號碼或群發) 系統返回 HTTP 200 OK，響應主體為 JSON 格式。

• 單號碼:

  {
      "message_id": "ws-a1b2c3d4-e5f67890"
  }
  
  

• 多號碼:

  [
      {
          "dnis": "85291234567",
          "message_id": "ws-c0d59d-908efa-515011"
      },
      {
          "dnis": "85298765432",
          "message_id": "ws-09c84c-226060-864263"
      }
  ]
  
  

成功響應 (長短信 split 模式)

[
    {
        "dnis": "85291234567",
        "message_id": "ws-3bef56819305-f55f-44b4",
        "segment_num": "1"
    },
    {
        "dnis": "85291234567",
        "message_id": "ws-7d4e5a0d14af-4a16-7ee6",
        "segment_num": "2"
    }
]

失敗響應

• 無可用路由: HTTP/1.1 400 Bad Request NO ROUTES

• 認證失敗: HTTP/1.1 401 Unauthorized Not authorized (check login and password)

• (更多 HTTP 狀態碼詳見附錄)

3. 回執狀態推送接口 (Delivery Receipt Push - Webhook)

當短信的最終投遞狀態更新時，WINGSING 平台會主動將狀態報告推送到您預先設定的 URL 地址。

3.1 推送格式

平台將以 GET 或 POST 方式向您的 URL 發送請求。

GET 示例 http://your.server.com/dlr_receiver?msgid=ws-b159d0-8d0c77&state=DELIVRD&reasoncode=000&to=85291234567&time=2025-08-10T18:13:00Z&mcc=454&mnc=00

POST 示例 (JSON Body)

{
    "msgid": "ws-440896-49e938-838927",
    "state": "DELIVRD",
    "reasoncode": "000",
    "to": "85291234567",
    "time": "2025-08-10T17:45:00Z",
    "mcc": "454",
    "mnc": "00"
}

3.2 推送參數

4. 上行回覆推送接口 (MO Message Push - Webhook)

當用戶回覆您的短信時，WINGSING 平台會將上行內容實時推送到您預先設定的 URL 地址。

4.1 推送格式

平台將以 GET 或 POST 方式向您的 URL 發送請求。

GET 示例 http://your.server.com/mo_receiver?from=85291234567&to=WINGSING&time=250810192030&message=STOP&message_id=mo-xyz-789

4.2 推送參數

5. 回執狀態查詢接口 (Query Delivery Status)

此接口用於主動查詢特定短信的投遞狀態，狀態報告在提交後24小時內可供查詢。

5.1 請求格式

GET https://%%SERVERIP:PORT%%/api?username=WS_USER_01&password=user_password&messageid=ws-a1b2c3d4-e5f67890&command=query

5.2 請求參數

5.3 響應結果

{
    "status": "DELIVRD",
    "delivery_time": "250810193309",
    "mccmnc": "45400",
    "error_code": "000",
    "system_delivery_time": "250810193309"
}

6. 附錄

6.1 長短信拆分規則

1. 純 GSM 7-bit 字符 (如英文、數字): 內容長度（簽名+正文）不超過160字符，按1條計費。超過160字符，則按每153字符為一條進行拆分計費。

2. 包含非 GSM 字符 (如中文、日文): 內容長度（簽名+正文）不超過70字符，按1條計費。超過70字符，則按每67字符為一條進行拆分計費。

6.2 回執狀態碼說明

6.3 HTTP 響應狀態碼