📖 API 接口文档

短信服务平台 API 接口说明，帮助您快速接入短信服务

🚀 快速开始

1. 获取 API 密钥

登录用户中心，在 API密钥管理 页面创建您的 API Key 和 API Secret。

2. 完成实名认证

发送短信前需要完成 实名认证。

3. 调用 API

使用您的 API Key 和 Secret 调用下方的接口发送短信。

🔐 认证方式

所有 API 请求需要在 Header 中携带认证信息：

X-API-Key: 您的API Key
X-API-Secret: 您的API Secret

示例：

curl -X POST "https://aa.hebil.xyz/api/sms/send" \
  -H "X-API-Key: sk_xxxxxxxxxxxxxxxx" \
  -H "X-API-Secret: xxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"phone": "13800138000", "template_id": "123456", "params": {"code": "1234"}}'

📤 发送短信

POST /api/sms/send

请求参数

参数名 类型 必填 说明
phone string 是 接收短信的手机号
template_id string 是 短信模板ID（在云服务商处申请）
params object 否 模板参数，键值对形式
provider string 否 服务商：tencent / aliyun，默认使用系统配置

请求示例

{
    "phone": "13800138000",
    "template_id": "123456",
    "params": {
        "code": "1234",
        "time": "5"
    }
}

响应示例

// 成功
{
    "success": true,
    "message": "短信发送成功",
    "data": {
        "message_id": "xxx-xxx-xxx",
        "phone": "138****8000"
    }
}

// 失败
{
    "success": false,
    "message": "发送失败：余额不足"
}

📤 批量发送短信

POST /api/sms/batch-send

请求参数

参数名 类型 必填 说明
phones array 是 手机号数组，最多100个
template_id string 是 短信模板ID
params object 否 模板参数

请求示例

{
    "phones": ["13800138000", "13900139000"],
    "template_id": "123456",
    "params": {
        "code": "1234"
    }
}

📋 查询发送记录

GET /api/sms/records

请求参数

参数名 类型 必填 说明
page int 否 页码，默认1
per_page int 否 每页数量，默认10，最大100
status string 否 状态筛选：pending / success / failed
start_time string 否 开始时间，格式：YYYY-MM-DD HH:mm:ss
end_time string 否 结束时间

响应示例

{
    "success": true,
    "data": {
        "records": [
            {
                "id": 1,
                "phone": "138****8000",
                "template_id": "123456",
                "status": "success",
                "created_at": "2024-01-01 12:00:00"
            }
        ],
        "total": 100,
        "page": 1,
        "per_page": 10
    }
}

👤 查询账户信息

GET /api/account/info

响应示例

{
    "success": true,
    "data": {
        "balance": 100.00,
        "total_sent": 1000,
        "today_sent": 50,
        "verification_status": "approved"
    }
}

❌ 错误码说明

HTTP状态码 说明
200 请求成功
400 请求参数错误
401 认证失败，API Key 或 Secret 无效
403 权限不足，如未完成实名认证
429 请求频率超限
500 服务器内部错误

📦 SDK & 示例代码

PHP 示例

<?php
$apiKey = 'your_api_key';
$apiSecret = 'your_api_secret';

$data = [
    'phone' => '13800138000',
    'template_id' => '123456',
    'params' => ['code' => '1234']
];

$ch = curl_init('https://aa.hebil.xyz/api/sms/send');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Content-Type: application/json',
    'X-API-Key: ' . $apiKey,
    'X-API-Secret: ' . $apiSecret
]);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);

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

$result = json_decode($response, true);
print_r($result);

Python 示例

import requests

api_key = 'your_api_key'
api_secret = 'your_api_secret'

response = requests.post(
    'https://aa.hebil.xyz/api/sms/send',
    json={
        'phone': '13800138000',
        'template_id': '123456',
        'params': {'code': '1234'}
    },
    headers={
        'X-API-Key': api_key,
        'X-API-Secret': api_secret
    }
)

print(response.json())