接口总览

所有接口共用同一套调用约定，先读这一篇，再去具体的接口文档。

基础信息

项目	说明
基础 URL	`https://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_id`	Header `X-APP-ID` / GET / POST	应用 ID
`app_key`	Header `X-APP-KEY` / GET / POST	应用密钥

服务端优先读取 Header，其次 GET，最后 POST，建议统一走 Header。

返回格式

所有接口统一返回以下结构：

{
    "code": 0,
    "msg": "success",
    "data": {},
    "request_id": "req_xxx"
}

字段	类型	说明
`code`	int	业务状态码，`0` 表示成功，非 0 见错误码表
`msg`	string	提示信息
`data`	object	业务数据，失败时可能为空
`request_id`	string	请求追踪 ID，排查问题时提供给技术支持

签名说明

当前版本直接使用 App ID + App Key 校验身份，不要求额外的签名参数。后续版本会升级为 RSA2 签名，升级前会提前公告并给出迁移方案，旧调用方式在过渡期内继续可用。

公共参数

业务参数之外，所有请求可携带以下公共参数：

参数	类型	必填	说明
`app_id`	string	是	应用 ID
`app_key`	string	是	应用密钥

参数类型

类型	说明	示例
string	字符串	姓名、手机号
integer	整数	次数、状态码
float	浮点数	金额、分值
boolean	布尔值	`generated` 等开关类字段
array	数组	不一致字段列表
object	对象	用户信息

通用错误码

错误码	说明
0	成功
1000	请求参数错误
1001	未提供认证信息
1002	App ID 无效
1003	App Key 错误
1004	应用已禁用
1005	未购买该 API 或套餐已用完
1009	API 不存在
1010	扣费失败
1011	服务器内部错误

完整错误码清单见错误码。