API 对接文档

本平台将短信、语音验证码、实名认证等服务聚合为统一 RESTful API。所有接口返回统一 JSON 格式：{"code":0,"msg":"success","data":{}}，其中 code=0 表示成功。

一、鉴权说明

1. 核心调用接口（短信/语音/实名认证）

使用 API Key 鉴权，请求头携带：

Authorization: Bearer {API_KEY}

API Key 在控制台「API Key」页面生成，每个产品类型（短信/语音/实名认证）使用独立 Key，且 Key 仅创建时完整显示一次。

2. 用户管理接口

使用登录返回的 JWT Token 鉴权，请求头同样携带 Authorization: Bearer {TOKEN}。

二、短信发送接口

POST/api/sms/send

鉴权：API Key（短信类型）

请求体

{
  "phone": "13800138000",
  "content": "您的验证码是123456"
}

参数说明

参数	类型	必填	说明
phone	string	是	接收手机号（支持国际区号，如 +8613800138000）
content	string	是	短信内容

响应示例

{
  "code": 0,
  "msg": "success",
  "data": {
    "call_id": 123,
    "status": "success",
    "deducted": true,
    "third_party_id": "xxx",
    "response_time": 4
  }
}

三、语音验证码接口

POST/api/voice/call

鉴权：API Key（语音类型）

请求体

{
  "phone": "13800138000",
  "code": "123456"
}

参数说明

参数	类型	必填	说明
phone	string	是	接收手机号
code	string	是	语音播报的验证码

四、实名认证接口

POST/api/id/verify

鉴权：API Key（实名认证类型）

请求体

{
  "name": "张三",
  "id_number": "110101199001011234",
  "face_image": ""
}

参数说明

参数	类型	必填	说明
name	string	是	姓名
id_number	string	是	身份证号
face_image	string	否	人脸图片（base64 或 URL）

五、用户管理接口

注册

POST/api/user/register

{"email": "user@example.com", "phone": "13800138000", "password": "123456"}

邮箱和手机号至少填一项，密码至少 6 位。

获取用户信息

GET/api/user/profile

鉴权：JWT。返回当前登录用户的 id、email、phone、status、created_at。

商品/套餐列表

GET/api/user/goods

返回上架中的商品（含 id、name、product_type、quantity、price、description）。

获取余额列表

GET/api/user/balances

API Key 列表 / 生成 / 禁用 / 删除

GET/api/user/api-keys

POST/api/user/api-keys/generate body: {"product_type":"sms"}

POST/api/user/api-keys/disable body: {"id":1}

POST/api/user/api-keys/delete body: {"id":1}

订单 / 购买 / 支付

GET/api/user/orders

POST/api/user/orders body: {"goods_id":1}

下单成功返回 pay_url（易支付链接），将用户跳转到该链接完成付款，付款成功后系统自动充值余额：

{
  "code": 0,
  "data": {
    "order_id": 1,
    "order_no": "xxx",
    "amount": "5.00",
    "pay_enabled": true,
    "pay_url": "https://支付网关/submit.php?..."
  }
}

调用日志 / 余额明细

GET/api/user/logs/calls

GET/api/user/logs/balance

六、错误码说明

code	说明
0	成功
401	未授权 / API Key 无效或已禁用
402	余额不足
403	API Key 与产品类型不匹配
429	请求过于频繁（触发限流）
1001-1042	用户/API Key 相关业务错误（注册、登录、生成、禁用、删除等）
1101-1103	短信参数错误
1201-1203	语音验证码参数错误
1301	实名认证参数错误
1401-1413	订单/支付相关错误