Sssms 短信接口调用说明

一、接口基础说明

Sssms API 支持通过 HTTPS 调用短信发送、余额查询、短信状态查询、上行短信接收、回调通知和任务查询等功能。

二、发送短信接口

用于发送国内或国际短信，支持普通发送和定时发送。

1. 请求地址

POST /api/v3/send

POST https://www.5188sms.com/api/v3/send

2. 请求头

Authorization: Bearer YOUR_TOKEN
Content-Type: application/x-www-form-urlencoded

3. 请求参数

4. cURL 调用示例

curl -X POST "https://www.5188sms.com/api/v3/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "phone=8613800138000" \
  -d "content=您的验证码是123456，有效期5分钟。" \
  -d "country_code=CN"

5. 定时短信示例

curl -X POST "https://www.5188sms.com/api/v3/send" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "phone=8613800138000" \
  -d "content=您的验证码是123456，有效期5分钟。" \
  -d "country_code=CN" \
  -d "schedule_at=2026-05-12 18:00:00"

三、查询账户余额

用于查询账户短信余额，包括总余额、国内短信余额、国际短信余额、双向短信余额等。

1. 请求地址

GET /api/v3/balance?token=YOUR_TOKEN

GET https://www.5188sms.com/api/v3/balance?token=YOUR_TOKEN

2. cURL 调用示例

curl "https://www.5188sms.com/api/v3/balance?token=YOUR_TOKEN"

3. 返回示例

{
  "code": 1,
  "msg": "ok",
  "data": {
    "sms_balance": "0.00",
    "standard_domestic_balance": "0.00",
    "prea_domestic_balance": "0.00",
    "international_balance": "0.00",
    "twoway_balance": "0.00",
    "domestic_test_used": 0,
    "international_test_used": 0,
    "is_subaccount": 0
  }
}

4. 返回字段说明

四、查询短信发送状态

发送短信后，可根据返回的批次号查询短信发送状态。

1. 请求地址

GET /api/v3/status?token=YOUR_TOKEN&batch_no=SMS...

GET https://www.5188sms.com/api/v3/status?token=YOUR_TOKEN&batch_no=SMS...

2. 参数说明

3. cURL 调用示例

curl "https://www.5188sms.com/api/v3/status?token=YOUR_TOKEN&batch_no=SMS..."

五、上行短信接收接口

当用户回复短信时，可通过上行短信接口接收用户回复内容。实际使用时，需要在平台后台配置您的接收地址，或按照平台要求对接上行消息。

请求地址

POST /api/v3/inbound

建议您的业务系统接收并记录以下信息：手机号、短信内容、接收时间、国家/地区、批次号或消息 ID 等。具体字段请以平台实际回调数据为准。

六、短信回调通知接口

短信发送结果可通过回调方式异步通知到您的系统。您可以在业务系统中准备一个可公网访问的接口，用于接收发送成功、发送失败、状态更新等通知。

请求地址

POST /api/v3/callback

建议您的回调接口返回成功响应，并做好签名校验、日志记录、重复通知去重等处理。

七、查询任务信息

用于查询当前账户相关的任务或处理信息。

1. 请求地址

GET /api/v3/worker?token=YOUR_TOKEN

GET https://www.5188sms.com/api/v3/worker?token=YOUR_TOKEN

2. cURL 调用示例

curl "https://www.5188sms.com/api/v3/worker?token=YOUR_TOKEN"

八、多语言调用示例

1. PHP 发送短信示例

<?php
$url = "https://www.5188sms.com/api/v3/send";
$token = "YOUR_TOKEN";

$data = [
  "phone" => "8613800138000",
  "content" => "您的验证码是123456，有效期5分钟。",
  "country_code" => "CN"
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
  "Authorization: Bearer " . $token,
  "Content-Type: application/x-www-form-urlencoded"
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, http_build_query($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

$response = curl_exec($ch);
curl_close($ch);

echo $response;
?>

2. Python 发送短信示例

import requests

url = "https://www.5188sms.com/api/v3/send"
headers = {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/x-www-form-urlencoded"
}
data = {
    "phone": "8613800138000",
    "content": "您的验证码是123456，有效期5分钟。",
    "country_code": "CN"
}

response = requests.post(url, headers=headers, data=data)
print(response.text)

3. JavaScript / Node.js 发送短信示例

const params = new URLSearchParams({
  phone: "8613800138000",
  content: "您的验证码是123456，有效期5分钟。",
  country_code: "CN"
});

fetch("https://www.5188sms.com/api/v3/send", {
  method: "POST",
  headers: {
    "Authorization": "Bearer YOUR_TOKEN",
    "Content-Type": "application/x-www-form-urlencoded"
  },
  body: params
})
.then(res => res.json())
.then(console.log)
.catch(console.error);

4. C# 发送短信示例

using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();
        client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_TOKEN");

        var data = new FormUrlEncodedContent(new[]
        {
            new KeyValuePair<string, string>("phone", "8613800138000"),
            new KeyValuePair<string, string>("content", "您的验证码是123456，有效期5分钟。"),
            new KeyValuePair<string, string>("country_code", "CN")
        });

        var response = await client.PostAsync("https://www.5188sms.com/api/v3/send", data);
        string result = await response.Content.ReadAsStringAsync();

        Console.WriteLine(result);
    }
}

5. Golang 发送短信示例

package main

import (
  "fmt"
  "io"
  "net/http"
  "net/url"
  "strings"
)

func main() {
  apiURL := "https://www.5188sms.com/api/v3/send"

  form := url.Values{}
  form.Set("phone", "8613800138000")
  form.Set("content", "您的验证码是123456，有效期5分钟。")
  form.Set("country_code", "CN")

  req, _ := http.NewRequest("POST", apiURL, strings.NewReader(form.Encode()))
  req.Header.Set("Authorization", "Bearer YOUR_TOKEN")
  req.Header.Set("Content-Type", "application/x-www-form-urlencoded")

  client := &http.Client{}
  resp, err := client.Do(req)
  if err != nil {
    panic(err)
  }
  defer resp.Body.Close()

  body, _ := io.ReadAll(resp.Body)
  fmt.Println(string(body))
}

6. 查询余额示例

curl "https://www.5188sms.com/api/v3/balance?token=YOUR_TOKEN"

九、注意事项

• 请使用 HTTPS 请求接口，避免 Token 泄露。
• 真实 Token 只应保存在服务端环境变量或后台配置中，不建议写入前端代码。
• 发送短信接口使用 Authorization: Bearer YOUR_TOKEN 进行鉴权。
• 余额、状态、任务等查询接口使用 token=YOUR_TOKEN 作为查询参数。
• 如果余额返回为 0.00，说明当前账户没有可用短信额度，需要充值或申请测试额度。
• 如果使用中文短信内容，请确保请求编码为 UTF-8。
• 建议保存发送接口返回的批次号，方便后续通过 /api/v3/status 查询短信状态。