免费注册

API 接口文档

本文档描述系统提供的所有 HTTP API 接口，仅支持普通用户 API Key + API Secret 认证，可用于发送短信、查询余额、提交模板及查询模板状态。

通用说明

所有接口均采用 HTTP POST 方式调用，请求体为 JSON 格式（Content-Type: application/json），响应也为 JSON 格式。

API 基础地址： https://vsjb.skvk.eu.cc/api/
所有接口地址均以此为基础，例如发送短信接口为 https://vsjb.skvk.eu.cc/api/send.php

认证方式

本系统仅提供普通用户认证方式，请在每个请求的参数中携带：

参数名类型必填说明
api_keystring是API Key，登录后在个人中心获取
api_secretstring是API Secret，与 API Key 配对使用

同时支持通过 HTTP Header 传递：API-Key 与 API-Secret。

通用响应格式

{
    "code": 0,           // 0 表示成功，其他为错误码
    "msg": "success",    // 提示信息
    "data": {            // 业务数据，不同接口返回结构不同
        // ...
    }
}

1. 发送短信接口

通过 HTTP POST JSON 方式调用，实现短信发送功能。支持单发和批量发送。

请求地址

POST https://vsjb.skvk.eu.cc/api/send.php

请求参数

参数名类型必填说明
api_keystring是API Key
api_secretstring是API Secret
phonestring / array是手机号，支持单个手机号字符串、逗号分隔字符串或手机号数组（批量发送）
template_codestring是模板 CODE：本地模板 ID（"提交模板"接口返回的 template_code）或上游模板编码（upstream_template_code），需已审核通过
template_paramsobject否模板参数，JSON 对象格式，如 {"code":"1234"}
sign_namestring否短信签名，不填使用系统默认签名

请求示例

POST https://vsjb.skvk.eu.cc/api/send.php
Content-Type: application/json

{
    "api_key": "ak_xxxxxxxxxxxxxxxx",
    "api_secret": "sk_xxxxxxxxxxxxxxxx",
    "phone": "13800138000",
    "template_code": "12",
    "template_params": {
        "code": "1234"
    }
}

响应示例（成功）

{
    "code": 0,
    "msg": "发送成功，共1条",
    "data": {
        "success_count": 1,
        "fail_count": 0,
        "log_ids": [101],
        "details": [
            {
                "phone": "13800138000",
                "status": "success",
                "log_id": 101
            }
        ]
    }
}

响应示例（失败）

{
    "code": 1,
    "msg": "余额或额度不足，需发送1条，请充值",
    "data": null
}

批量发送示例

{
    "api_key": "ak_xxxxxxxxxxxxxxxx",
    "api_secret": "sk_xxxxxxxxxxxxxxxx",
    "phone": ["13800138000", "13800138001", "13800138002"],
    "template_code": "13",
    "template_params": {
        "order_no": "ORD20260726001",
        "amount": "99.00"
    }
}
注意：
  • 批量发送手机号数量不能超过 500 个/次
  • 营销类短信建议在 8:00-22:00 之间发送
  • 每条短信将消耗 1 条额度或扣除对应余额

2. 查询余额接口

查询当前账户的余额和剩余短信额度。

请求地址

POST https://vsjb.skvk.eu.cc/api/query_balance.php

请求参数

参数名类型必填说明
api_keystring是API Key
api_secretstring是API Secret

请求示例

POST https://vsjb.skvk.eu.cc/api/query_balance.php
Content-Type: application/json

{
    "api_key": "ak_xxxxxxxxxxxxxxxx",
    "api_secret": "sk_xxxxxxxxxxxxxxxx"
}

响应示例

{
    "code": 0,
    "msg": "",
    "data": {
        "balance": "99.5000",
        "quota_count": 1000
    }
}

响应字段说明

字段类型说明
balancestring账户余额（元），用于按需付费发送
quota_countint剩余短信条数（套餐额度）

3. 提交模板接口

提交短信模板。模板先进行本地审核（人工 / 规则自动 / AI，见后台"系统设置-模板审核"），本地通过后按设置自动或手动提交至上游服务商审核，本地与上游均通过后才可用于发送短信。支持同内容模板自动复用：同一账户提交相同内容与签名的模板时，自动复用已有模板，避免重复提交。

请求地址

POST https://vsjb.skvk.eu.cc/api/template_submit.php
兼容说明：旧接口地址 POST /api/submit_template.php 仍可使用，功能一致，仅为兼容旧客户端保留。

请求参数

参数名类型必填说明
api_keystring是API Key
api_secretstring是API Secret
template_namestring是模板名称（1-100 字符）
template_contentstring是模板内容，变量用 ${变量名} 表示，如 您的验证码是${code}
template_typeint是模板类型：1=验证码，2=通知，3=营销
sign_namestring否短信签名，不填使用系统默认签名
remarkstring是申请说明（必填，1-255 字符），填写模板使用场景可加快上游审核
template_variablesarray / string否模板变量属性，JSON 数组或 JSON 字符串：[{"name":"code","desc":"验证码","type":"numberCaptcha"}]；也支持对象映射 {"code":{"desc":"验证码","type":"numberCaptcha"}} 或简化映射 {"code":"验证码"}。不传时系统自动识别内容中的 ${变量} 并提醒补充。type 必须使用下方"变量属性对照表"中的上游标准属性值，且需与模板类型匹配。
template_ruleobject / string否模板规则配置，JSON 对象或字符串，随变量属性一并上传上游

变量属性对照表（type 取值必须严格对照上游支持的标准属性）

属性值（type）含义可用模板类型
numberCaptcha数字验证码1=验证码（专用）
characterWithNumber2字母数字组合（密码/令牌）1=验证码（专用）
time时间/日期2=通知，3=营销
money金额/数字2=通知，3=营销
user_nick用户昵称2=通知，3=营销
unit_name企业/组织名称2=通知，3=营销
license_plate_number车牌号2=通知，3=营销
tracking_number快递单号2=通知，3=营销
pick_up_code取件码2=通知，3=营销
other_number2其他号码（订单号/编码等）2=通知，3=营销
email_address邮箱地址2=通知，3=营销
others其他/普通文本2=通知，3=营销

提示：验证码模板的变量仅支持 numberCaptcha（数字验证码）与 characterWithNumber2（字母数字组合，如令牌）；通知/营销模板的变量支持其余属性。属性与模板类型不匹配时系统会忽略并自动回退为默认属性。

请求示例

POST https://vsjb.skvk.eu.cc/api/template_submit.php
Content-Type: application/json

{
    "api_key": "ak_xxxxxxxxxxxxxxxx",
    "api_secret": "sk_xxxxxxxxxxxxxxxx",
    "template_name": "注册验证码",
    "template_content": "您的注册验证码是${code}，5分钟内有效，请勿泄露。",
    "template_type": 1,
    "sign_name": "测试平台",
    "remark": "用于用户注册时发送短信验证码",
    "template_variables": [
        {"name": "code", "desc": "验证码", "type": "numberCaptcha"}
    ]
}

响应示例

{
    "code": 0,
    "msg": "模板已提交上游，等待上游审核（上游编码：TP_123）",
    "data": {
        "template_id": 123,
        "template_code": "123",
        "template_name": "注册验证码",
        "template_content": "您的注册验证码是${code}，5分钟内有效，请勿泄露。",
        "template_type": 1,
        "template_type_text": "验证码",
        "sign_name": "测试平台",
        "remark": "用于用户注册时发送短信验证码",
        "template_rule": "",
        "template_variables": [
            {"name": "code", "desc": "验证码", "type": "number"}
        ],
        "status": 1,
        "status_text": "已通过",
        "reject_reason": "",
        "review_mode": "auto",
        "upstream_status": 1,
        "upstream_status_text": "审核中",
        "upstream_template_code": "TP_123",
        "upstream_reject_reason": "",
        "submitted_at": "2026-08-09 12:00:00",
        "created_at": "2026-08-09 12:00:00",
        "updated_at": "2026-08-09 12:00:00"
    }
}
状态说明：
  • status（本地审核）：0 待审核、1 已通过、2 已驳回。人工审核模式下提交后为 0，需管理员在后台"模板管理"中操作；自动/AI 模式下提交后直接给出结果。
  • upstream_status（上游审核）：0 未提交、1 审核中、2 已通过、3 已驳回。本地通过且系统开启"自动提交上游"时返回 1。
  • 只有 status=1 且 upstream_status=2 的模板才能用于发送短信；本地驳回原因见 reject_reason，上游驳回原因见 upstream_reject_reason。
  • 同内容自动复用：返回的 msg 为"已复用已有模板"时，表示未新建模板，直接使用返回的 template_id 即可。
  • 变量属性：提交时若不传 template_variables，系统会自动识别模板内容中的 ${变量}，响应 msg 会提示"已自动识别变量"，建议按提示补充变量说明（desc）与类型（type），可加快上游审核；提交上游时变量属性（template_rule.variables）与申请说明（remark）会自动一并上传。

4. 查询模板状态/列表接口

查询已提交模板的审核状态，支持查询单个模板或分页查询模板列表。

请求地址

POST https://vsjb.skvk.eu.cc/api/template_list.php

请求参数

参数名类型必填说明
api_keystring是API Key
api_secretstring是API Secret
template_idint否模板 ID，指定时只返回该模板信息
statusint否本地状态筛选：0=待审核，1=已通过，2=已拒绝
upstream_statusint否上游状态筛选：0=未提交，1=审核中，2=已通过，3=已驳回
pageint否页码，默认 1
page_sizeint否每页条数，默认 20，最大 100

请求示例（查询单个模板）

POST https://vsjb.skvk.eu.cc/api/template_list.php
Content-Type: application/json

{
    "api_key": "ak_xxxxxxxxxxxxxxxx",
    "api_secret": "sk_xxxxxxxxxxxxxxxx",
    "template_id": 123
}

响应示例（单个）

{
    "code": 0,
    "msg": "",
    "data": {
        "list": [
            {
                "template_id": 123,
                "template_code": "123",
                "template_name": "注册验证码",
                "template_content": "您的注册验证码是${code}，5分钟内有效。",
                "template_type": 1,
                "template_type_text": "验证码",
                "sign_name": "短信平台",
                "remark": "用于用户注册时发送短信验证码",
                "template_rule": "",
                "template_variables": [
                    {"name": "code", "desc": "验证码", "type": "number"}
                ],
                "status": 1,
                "status_text": "已通过",
                "reject_reason": "",
                "review_mode": "auto",
                "upstream_status": 2,
                "upstream_status_text": "已通过",
                "upstream_template_code": "TP_123",
                "upstream_reject_reason": "",
                "submitted_at": "2026-08-09 12:00:00",
                "created_at": "2026-07-26 10:30:00",
                "updated_at": "2026-07-26 11:00:00"
            }
        ],
        "pagination": {
            "page": 1,
            "page_size": 20,
            "total": 1,
            "total_pages": 1
        }
    }
}

请求示例（查询所有模板）

{
    "api_key": "ak_xxxxxxxxxxxxxxxx",
    "api_secret": "sk_xxxxxxxxxxxxxxxx"
}

5. 送达状态查询（DLR）接口

查询短信送达状态（DLR 回执）。发送短信成功后返回的 log_id（或短信记录中的 biz_id）可用于查询。支持分页、多维度筛选，可选实时同步上游回执状态。

请求地址

POST https://vsjb.skvk.eu.cc/api/dlr_query.php

支持 POST（JSON 或表单）与 GET（参数拼 URL）两种方式。from_upstream=1 实时查询上游时，自动兼容上游返回的 records / list / logs / items 多种结构，并按下述五状态映射判定送达状态（上游 0=发送中 1=发送成功 2=发送失败 3=已送达 4=送达失败，与上游 DLR 回调推送、平台轮询脚本 cron/poll_dlr.php 保持一致）；未收到回执（dlr_status=0）的记录不会覆盖本地已有状态，且本地已是终态时仅当上游判定为失败才回写。

请求参数

参数名类型必填说明
api_keystring是API Key
api_secretstring是API Secret
log_idint否本地发送日志 ID（发送短信接口返回）
log_idsstring/array否批量日志 ID，逗号分隔或数组，如 "1001,1002"
phonestring否手机号
biz_idstring否上游回执 ID
send_datestring否发送日期，格式 YYYYMMDD，如 20260811
from_upstreamint否传 1 时实时查询上游送达状态并回写本地，默认 0（只查本地）
pageint否页码，默认 1
page_sizeint否每页条数，默认 20，最大 100

送达状态码（dlr_status）

状态码说明
0未收到回执（发送中）
1已送达
2发送失败
3未知

请求示例

POST https://vsjb.skvk.eu.cc/api/dlr_query.php
Content-Type: application/json

{
    "api_key": "ak_xxxxxxxxxxxxxxxx",
    "api_secret": "sk_xxxxxxxxxxxxxxxx",
    "phone": "13800138000",
    "send_date": "20260811",
    "page": 1,
    "page_size": 20
}

响应示例

{
    "code": 0,
    "msg": "",
    "data": {
        "list": [
            {
                "log_id": 1001,
                "phone": "13800138000",
                "template_code": "12",
                "content": "您的验证码为123456，5分钟内有效。",
                "send_status": 1,
                "send_status_text": "成功",
                "dlr_status": 1,
                "dlr_status_text": "送达成功",
                "provider_log_id": "880001",
                "biz_id": "887654321",
                "request_id": "xxx-xxx",
                "receive_time": "2026-08-11 12:00:03",
                "created_at": "2026-08-11 11:59:58"
            }
        ],
        "pagination": {
            "page": 1,
            "page_size": 20,
            "total": 1,
            "total_pages": 1
        },
        "upstream": []
    }
}

6. DLR 状态报告推送

在用户中心"个人中心 - API 接口信息"中配置 DLR 送达状态回调地址 后，短信产生送达回执时，系统会通过 cron/retry_dlr_push.php（建议 crontab 每分钟执行一次）向该地址发送 POST 请求（Content-Type: application/json）。回调地址留空则不推送。

推送数据结构

{
    "log_id": 101,
    "phone": "13800138000",
    "sign_name": "天津钢金科技",
    "template_code": "SMS_123456789",
    "send_status": 1,
    "dlr_status": 1,
    "dlr_status_text": "已送达",
    "dlr_err_code": "DELIVERED",
    "dlr_err_msg": "用户接收成功",
    "dlr_send_time": "2024-01-15 10:30:01",
    "dlr_report_time": "2024-01-15 10:30:05",
    "biz_id": "12345^67890",
    "created_at": "2024-01-15 10:30:00"
}

字段说明

字段类型说明
log_idint系统发送日志 ID
phonestring接收手机号
sign_namestring发信使用的签名
template_codestring模板编码
send_statusint发送状态：0=待发送 1=成功 2=失败
dlr_statusint送达状态：0=未收到 1=已送达 2=发送失败 3=未知
dlr_status_textstring送达状态中文说明
dlr_err_codestring回执错误码（如 DELIVERED），无则空
dlr_err_msgstring回执错误信息，无则空
dlr_send_timedatetime短信发送时间
dlr_report_timedatetime回执时间，无则空
biz_idstring上游回执 ID
created_atdatetime发送日志创建时间

错误码说明

所有接口统一使用以下错误码规范：

错误码说明处理建议
0成功-
1通用失败（详见 msg 字段）根据 msg 提示处理
401认证失败（API Key/Secret 错误）检查 api_key / api_secret 是否正确
403权限不足（账户禁用或 IP 受限）联系管理员处理
429请求频率过高请降低调用频率
500服务器内部错误请稍后重试或联系客服

代码示例

PHP 示例

<?php
// 发送短信示例
$apiUrl = 'https://vsjb.skvk.eu.cc/api/send.php';
$data = [
    'api_key'         => 'ak_xxxxxxxxxxxxxxxx',
    'api_secret'      => 'sk_xxxxxxxxxxxxxxxx',
    'phone'           => '13800138000',
    'template_code'   => 'SMS_001',
    'template_params' => ['code' => '1234'],
];

$ch = curl_init($apiUrl);
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_POSTFIELDS     => json_encode($data),
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT        => 30,
    CURLOPT_HTTPHEADER     => ['Content-Type: application/json'],
]);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
if ($result['code'] === 0) {
    echo '发送成功，成功条数：' . $result['data']['success_count'];
} else {
    echo '发送失败：' . $result['msg'];
}

Python 示例

import requests
import json

api_url = 'https://vsjb.skvk.eu.cc/api/send.php'
data = {
    'api_key': 'ak_xxxxxxxxxxxxxxxx',
    'api_secret': 'sk_xxxxxxxxxxxxxxxx',
    'phone': '13800138000',
    'template_code': 'SMS_001',
    'template_params': {'code': '1234'}
}

resp = requests.post(api_url, json=data, timeout=30)
result = resp.json()

if result['code'] == 0:
    print('发送成功，成功条数：', result['data']['success_count'])
else:
    print('发送失败：', result['msg'])

Node.js 示例

const axios = require('axios');

const apiUrl = 'https://vsjb.skvk.eu.cc/api/send.php';
const data = {
    api_key: 'ak_xxxxxxxxxxxxxxxx',
    api_secret: 'sk_xxxxxxxxxxxxxxxx',
    phone: '13800138000',
    template_code: 'SMS_001',
    template_params: { code: '1234' }
};

axios.post(apiUrl, data, { timeout: 30000 })
    .then(res => {
        const result = res.data;
        if (result.code === 0) {
            console.log('发送成功，成功条数：', result.data.success_count);
        } else {
            console.log('发送失败：', result.msg);
        }
    })
    .catch(err => console.error('请求异常：', err.message));

注意事项

安全提示：
  • 请妥善保管您的 API Key 和 API Secret，不要泄露给他人
  • 建议在服务端调用接口，避免在前端代码中暴露密钥
  • 如发现密钥泄露，请立即在个人中心重置密钥
使用建议：
  • 发送短信前建议先调用查询余额接口，确认额度充足
  • 批量发送时建议分批进行，每批不超过 500 个手机号
  • 遇到 429 错误码时，请适当降低调用频率
  • 所有接口超时时间建议设置为 30 秒