文档说明
基础信息
接口基础地址:
https://client.timesms.com/prod-api
认证方式
支持 Token 认证、OAuth2.0
token: {token}
数据格式
响应格式: JSON
Content-Type: application/json
响应码说明
全局响应码说明
| 响应码 | 说明 |
|---|---|
| 1 | token不能为空 |
| 2 | token失效，请重新登录 |
| 3 | 用户名不存在 |
| 4 | 密码错误 |
| 5 | 账户已禁用，请联系管理员 |
| 6 | 账户异常，请联系管理员 |
| 100 | 接口请求超过频率限制 |
| 500 | 输出具体错误信息 |
| 200 | 操作成功 |
用户登录
用户通过账号密码获取访问令牌
GET 请求的参数通过 URL 传递，而 URL 仅支持 ASCII 字符。中文、特殊符号需先通过 URL 编码（将字符转为 %XX 格式的 ASCII 字符串），后端再通过 URL 解码 还原原始值。关键：前端编码方式与后端解码方式必须一致（默认推荐 UTF-8 编码，）
/api/login
Query请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| username | string | 是 | 用户名（URL编码） |
| password | string | 是 | 密码（URL编码） |
请求示例
https://client.timesms.com/prod-api/api/login?username=testpwd1&password=123888
正确响应示例
{
"msg": "操作成功",
"code": 200,
"data": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzUxMiJ9.eyJzdWIiOiIxMjIiLCJpYXQiOjE3NjMwMTg0NTgsImV4cCI6MTc2MzYyMzI1OH0.w-hjTEWecXRmiz7GvfYreyrv4l_sbgtSUOSOpAxFNhFFfNGpZuUSKlifYhSGnkjpJCgQqevfOepy_0VJwtpMLw"
}
}
账户信息
获取用户名和余额
/api/account
Header请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| token | string | 是 | 用户token |
Query请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| 空 | 空 | 空 | 空 |
请求示例
https://client.timesms.com/prod-api/api/account
正确响应示例
{
"msg": "操作成功",
"code": 200,
"data": {
"balance": 0,
"username": "testpwd"
}
}
可用号码数量
获取可用号码数量
/api/getMobileCount
Header请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| token | string | 是 | 用户token |
Query请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| projectId | Long | 是 | 项目ID |
| countryId | Long | 是 | 国家ID |
请求示例
https://client.timesms.com/prod-api/api/getMobileCount?countryId=1000&projectId=1000
正确响应示例
{
"msg": "操作成功",
"code": 200,
"data": {
"count": 28
}
}
获取手机号
获取手机号
/api/getPhoneNumber
Header请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| token | string | 是 | 用户token |
Query请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| projectId | Long | 是 | 项目ID |
| countryId | Long | 是 | 国家ID |
| pubCode | String | 否 | 专属对接码，多个用逗号隔开 |
| phoneNumber | String | 否 | 指定手机号 |
| maxPrice | Double | 否 | 最大单价 |
请求示例
https://client.timesms.com/prod-api/api/getPhoneNumber?countryId=1000&projectId=1000&num=10
正确响应示例
{
"msg": "操作成功",
"code": 200,
"data": [
{
"orderId": 39, //订单ID
"phonum": "798899875", // 手机号码
"orderStatus": 1,// 订单状态
"countryId": 1000,// 国家ID
"projectId": 1000,// 项目ID
"updateTime": '2025-11-16 23:56:51',// 短信接收时间
"code": '524812',// 验证码
"content": ''// 短信内容
}
]
}
获取验证码
获取验证码
/api/verifyCode
Header请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| token | string | 是 | 用户token |
Query请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| orderId | Long | 是 | order ID |
请求示例
https://client.timesms.com/prod-api/api/verifyCode?orderId=18
正确响应示例
{
"msg": "操作成功",
"code": 200,
"data": {
"phonum": "7822525565",
"code": "3333333",
"content": "facebook verify is 3333333",
"updateTime": "2025-10-11 21:56:57"
}
}
加黑/释放手机号
重要申明：未收到短信的情况下，请主动调用释放接口，否则在后台强制释放前收到了短信照样计费
/api/blockOrRelease
Header请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| token | string | 是 | 用户token |
Query请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| type | Integer | 是 | 1：加黑；2：释放 |
| orderId | Long | 是 | 获取手机号返回的orderId值 |
请求示例
https://client.timesms.com/prod-api/api/blockOrRelease?type=1&orderId=19
正确响应示例
{
"msg": "操作成功",
"code": 200
}
状态反馈
调用该接口需要配置权限，注册默认没有此接口权限，如需开通请联系平台,
/api/stateReport
Header请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| token | string | 是 | 用户token |
Query请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| orderId | Long | 是 | 获取手机号返回的orderId值 |
| remark | String | 是 | 反馈信息（URL编码） |
请求示例
https://client.timesms.com/prod-api/api/stateReport?orderId=19&remark=success
正确响应示例
{
"msg": "操作成功",
"code": 200
}
再次使用
当需要再次使用手机号时调用（非指定取号多次收码）；收到验证码后调用；再次使用会重新结算费用，非特殊项目，请勿调用，避免账户余额减少
/api/again
Header请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| token | string | 是 | 用户token |
Query请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| orderId | Long | 是 | 获取手机号返回的orderId值 |
| min | Integer | 是 | 多少秒后再次使用，值范围1-18000秒，如果值为5，代表5秒后再次使用 |
请求示例
https://client.timesms.com/prod-api/api/again?orderId=19&min=5
正确响应示例
{
"msg": "操作成功",
"code": 200
}
获取价目表
获取价目表
/api/price
Header请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| token | string | 是 | 用户token |
Query请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| 无 | 无 | 无 | 无 |
请求示例
https://client.timesms.com/prod-api/api/price
正确响应示例
{
"msg": "操作成功",
"code": 200,
"data": [
{
"projectId": 1000,
"projectName": "Facebook",
"price": 5,
"countryId": 1000,
"countryName": "英国",
"countryEnglish": "uk"
},
{
"projectId": 1001,
"projectName": "Telegram",
"price": 2.5,
"countryId": 1000,
"countryName": "英国",
"countryEnglish": "uk"
}
]
}
获取项目列表
获取项目列表
/api/projectList
Header请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| token | string | 是 | 用户token |
Query请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| 无 | 无 | 无 | 无 |
请求示例
https://client.timesms.com/prod-api/api/projectList
正确响应示例
{
"msg": "操作成功",
"code": 200,
"data": [
{
"id": 1000,
"projectName": "Facebook"
},
{
"id": 1001,
"projectName": "Telegram"
}
]
}
获取国家列表
获取国家列表
/api/countryList
Header请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| token | string | 是 | 用户token |
Query请求参数
| 参数名 | 类型 | 是否必填 | 描述 |
|---|---|---|---|
| 无 | 无 | 无 | 无 |
请求示例
https://client.timesms.com/prod-api/api/countryList
正确响应示例
{
"msg": "操作成功",
"code": 200,
"data": [
{
"id": 1000,
"countryName": "英国",
"countryEnglish": "uk"
},
{
"id": 1001,
"countryName": "俄罗斯",
"countryEnglish": "rus"
}
]
}