雲尚API

介面總覽

所有介面共用同一套呼叫約定，先讀這一篇，再去看具體的介面文件。

基礎資訊

項目說明
基礎 URLhttps://yunsapi.com/api/v3/
資料格式JSON
字元編碼UTF-8
請求方式絕大多數為 POST，部分介面支援 GET
認證方式App ID + App Key

呼叫方式

支援兩種寫法，效果相同：

方式格式
路徑方式（建議）POST /api/v3/{api_code}
參數方式POST /api/v3/index.php?code={api_code}

以簡訊驗證碼介面為例：

# 路徑方式
curl -X POST https://yunsapi.com/api/v3/dxyzm \
  -H "X-APP-ID: YOUR_APP_ID" \
  -H "X-APP-KEY: YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"13800138000"}'

# 參數方式
curl -X POST "https://yunsapi.com/api/v3/index.php?code=dxyzm" \
  -H "X-APP-ID: YOUR_APP_ID" \
  -H "X-APP-KEY: YOUR_APP_KEY" \
  -H "Content-Type: application/json" \
  -d '{"phone":"13800138000"}'

認證方式

每個請求都必須攜帶認證憑證，三種傳法任選，優先順序為 Header > GET > POST：

參數位置說明
app_idHeader X-APP-ID / GET / POST應用 ID
app_keyHeader X-APP-KEY / GET / POST應用密鑰

伺服器優先讀取 Header，其次 GET，最後 POST，建議統一走 Header。

回傳格式

所有介面統一回傳以下結構：

{
    "code": 0,
    "msg": "success",
    "data": {},
    "request_id": "req_xxx"
}
欄位類型說明
codeint業務狀態碼，0 表示成功，非 0 見錯誤碼表
msgstring提示訊息
dataobject業務資料，失敗時可能為空
request_idstring請求追蹤 ID，排查問題時提供給技術支援

簽名說明

目前版本直接使用 App ID + App Key 驗證身份，不要求額外簽名參數。後續版本會升級為 RSA2 簽名，升級前會提前公告並提供遷移方案，舊呼叫方式在過渡期內繼續可用。

公共參數

業務參數之外，所有請求可攜帶以下公共參數：

參數類型必填說明
app_idstring是應用 ID
app_keystring是應用密鑰

參數類型

類型說明範例
string字串姓名、手機號
integer整數次數、狀態碼
float浮點數金額、分數
boolean布林值generated 等開關類欄位
array陣列不一致欄位清單
object物件使用者資訊

通用錯誤碼

錯誤碼說明
0成功
1000請求參數錯誤
1001未提供認證資訊
1002App ID 無效
1003App Key 錯誤
1004應用已停用
1005未購買該 API 或套餐已用完
1009API 不存在
1010扣費失敗
1011伺服器內部錯誤

完整錯誤碼清單見 錯誤碼。