授权验证 API 文档

第三方应用授权验证接口，支持多种验证方式

v1.0

基础信息

  • 接口地址 https://yisuifeng.com/auth-api/auth.php
  • 请求方式 GET / POST
  • 数据格式 JSON
  • 字符编码 UTF-8

通用响应格式

json 
{
    "code": 200,
    "message": "提示信息",
    "data": {}
}

响应状态码

200 请求成功
400 参数错误
403 权限不足
404 资源不存在
500 服务器错误

验证授权

通过授权内容（如IP、域名、MAC等）验证授权是否有效。系统会根据提供的授权字段自动匹配对应的授权记录。

注意：必须提供完整的授权字段内容，系统会匹配所有字段完全一致的授权记录。
  • 状态验证：检查授权状态是否为启用状态
  • 字段匹配：根据 verify_data 中的字段查找并匹配授权记录
  • 完整验证：用户提供的字段必须与授权绑定的所有字段完全一致
  • 次数扣减：次数型/组合型授权每次验证会扣减 1 次剩余验证次数

验证流程

步骤 说明
1 验证应用Token有效性
2 根据 verify_data 查找匹配的授权记录
3 检查授权状态是否正常（status=1）
4 检查授权是否在有效期内（expire_time）
5 检查剩余验证次数（remain_verify_count > 0）
6 扣减 1 次验证次数，返回成功
GET/POST /auth-api/auth.php?action=verify

请求参数

参数名 类型 必填 说明
action string 是 固定值：verify
app_token string 是 应用Token（管理后台获取），如：abc123def456
verify_data array 是 授权字段数据，用于匹配授权记录。格式：verify_data[字段名]=值，必须提供完整的授权字段

verify_data 参数说明

字段名 示例值 说明
verify_data[ip] 192.168.1.100 IP地址
verify_data[domain] www.example.com 绑定域名
verify_data[mac] 00:1A:2B:3C:4D:5E MAC地址
verify_data[phone] 13800138000 手机号
verify_data[custom_xxx] 自定义值 自定义字段，如 custom_VIP、custom_MM 等

请求示例

GET /auth-api/auth.php?action=verify&app_token=abc123def456&verify_data[ip]=192.168.1.100&verify_data[custom_VIP]=55

成功响应

json 
{
    "code": 200,
    "message": "授权验证通过",
    "data": {
        "license_id": 10086,
        "app_name": "超级工具箱",
        "status": 1,
        "remain_verify_count": 99
    }
}

响应参数说明

参数名 类型 说明
license_id int 授权记录ID
app_name string 应用名称
status int 授权状态：1=正常
remain_verify_count int 剩余验证次数（次数型/组合型授权返回，已扣减本次）

失败响应

json 
{
    "code": 403,
    "message": "授权验证失败",
    "data": null
}

{
    "code": 403,
    "message": "授权已禁用",
    "data": null
}

{
    "code": 403,
    "message": "授权已过期",
    "data": null
}

{
    "code": 403,
    "message": "验证次数已用完",
    "data": null
}

授权码激活

使用授权码激活，创建新授权或续费现有授权。

  • 激活逻辑：验证授权码有效性，查找相同授权记录
  • 无授权：创建新授权记录
  • 有授权：续费（延长到期时间）
  • 授权码状态：更新为已使用（每个授权码只能用一次）
POST /auth-api/auth.php?action=activate

请求参数

参数名 类型 必填 说明
action string 是 固定值：activate
app_token string 是 应用Token
card_code string 是 授权码
contact string 否 联系方式，用于找回授权
verify_data array 是 授权字段数据，用于匹配授权记录

请求示例

POST /auth-api/auth.php?action=activate
app_token=abc123def456&card_code=CARD-XXXX-XXXX&contact=user@qq.com&verify_data[ip]=192.168.1.100

成功响应（创建新授权）

json 
{
    "code": 200,
    "message": "激活成功",
    "data": {
        "license_id": 10001,
        "app_name": "超级工具箱",
        "card_days": 30,
        "expire_time": "2025-04-16 10:00:00",
        "is_renew": false
    }
}

成功响应（续费）

json 
{
    "code": 200,
    "message": "授权续费成功",
    "data": {
        "license_id": 10001,
        "app_name": "超级工具箱",
        "card_days": 30,
        "expire_time": "2025-04-19 10:00:00",
        "is_renew": true
    }
}

失败响应

json 
{
    "code": 403,
    "message": "该授权码已被使用",
    "data": null
}

{
    "code": 403,
    "message": "该授权已存在，永久授权不支持续费",
    "data": null
}

{
    "code": 404,
    "message": "授权不存在",
    "data": null
}

按次授权(授权码)

按次授权模式下，授权码用于验证授权并扣减使用次数。授权记录需已存在，授权码仅用于次数控制。

  • 适用场景：需要限制验证次数的授权
  • 授权码设置：card_count > 0, remain_count > 0
  • 验证行为：验证授权存在后扣减次数，次数不足则拒绝
  • 授权码状态：不改变status，仅扣减remain_count
POST /auth-api/auth.php?action=verify_card

请求参数

参数名 类型 必填 说明
action string 是 固定值：verify_card
app_token string 是 应用Token
card_code string 是 授权码
verify_data array 是 授权内容，格式：verify_data[字段名]=值

验证流程

步骤 说明
1 验证授权码有效性（应用匹配、未禁用、未过期）
2 根据verify_data查找授权记录
3 授权不存在则返回错误
4 检查remain_count > 0，不足则返回错误
5 扣减remain_count，返回剩余次数

请求示例

POST /auth-api/auth.php?action=verify_card
app_token=abc123def456&card_code=CARD-XXXX-XXXX&verify_data[ip]=192.168.1.100

成功响应

json 
{
    "code": 200,
    "message": "验证成功",
    "data": {
        "license_id": 123,
        "app_name": "示例应用",
        "remain_count": 9,
        "card_type": "count"
    }
}

失败响应

json 
{
    "code": 403,
    "message": "次数不足",
    "data": null
}

按天授权(授权码)

按天授权模式下，授权码用于验证授权是否在有效期内。从授权码使用时间开始计算天数。

  • 适用场景：需要按天计费的授权验证
  • 授权码设置：card_days > 0
  • 验证行为：检查当前时间是否在有效期内
  • 有效期计算：used_time + card_days 天
POST /auth-api/auth.php?action=verify_card

请求参数

参数名 类型 必填 说明
action string 是 固定值：verify_card
app_token string 是 应用Token
card_code string 是 授权码
verify_data array 是 授权内容，格式：verify_data[字段名]=值

验证流程

步骤 说明
1 验证授权码有效性（应用匹配、未禁用、未过期）
2 根据verify_data查找授权记录
3 授权不存在则返回错误
4 检查授权码是否有used_time（已激活）
5 计算到期时间 = used_time + card_days天
6 当前时间 <= 到期时间则成功，否则返回天数不足

请求示例

POST /auth-api/auth.php?action=verify_card
app_token=abc123def456&card_code=CARD-XXXX-XXXX&verify_data[ip]=192.168.1.100

成功响应

json 
{
    "code": 200,
    "message": "验证成功",
    "data": {
        "license_id": 123,
        "app_name": "示例应用",
        "remaining_days": 15,
        "expire_time": "2025-03-31 10:00:00",
        "card_type": "time"
    }
}

失败响应

json 
{
    "code": 403,
    "message": "天数不足",
    "data": null
}

组合授权(授权码)

组合授权模式下，同时验证天数和次数，两者都满足才能通过验证。

  • 适用场景：需要同时控制时间和次数的授权
  • 授权码设置：card_days > 0, card_count > 0
  • 验证行为：天数和次数都满足才扣减次数
  • 特点：天数不足时次数也无法使用
POST /auth-api/auth.php?action=verify_card

请求参数

参数名 类型 必填 说明
action string 是 固定值：verify_card
app_token string 是 应用Token
card_code string 是 授权码
verify_data array 是 授权内容，格式：verify_data[字段名]=值

验证流程

步骤 说明
1 验证授权码有效性
2 根据verify_data查找授权记录
3 检查次数 remain_count > 0
4 检查天数（当前时间 <= used_time + card_days）
5 两者都满足则扣减次数，返回成功

请求示例

POST /auth-api/auth.php?action=verify_card
app_token=abc123def456&card_code=CARD-XXXX-XXXX&verify_data[ip]=192.168.1.100

成功响应

json 
{
    "code": 200,
    "message": "验证成功",
    "data": {
        "license_id": 123,
        "app_name": "示例应用",
        "remain_count": 9,
        "remaining_days": 15,
        "expire_time": "2025-03-31 10:00:00",
        "card_type": "combo"
    }
}

失败响应

json 
{
    "code": 403,
    "message": "次数不足",
    "data": null
}
json 
{
    "code": 403,
    "message": "天数不足",
    "data": null
}

查询授权

通过授权内容（如IP、域名、MAC等）查询授权信息。系统会根据提供的授权字段自动匹配对应的授权记录。

注意：必须提供完整的授权字段内容，系统会匹配所有字段完全一致的授权记录。
GET /auth-api/auth.php?action=query

请求参数

参数名 类型 必填 说明
action string 是 固定值：query
app_token string 是 应用Token
verify_data array 是 授权字段数据，用于匹配授权记录。格式：verify_data[字段名]=值，必须提供完整的授权字段

verify_data 参数说明

字段名 示例值 说明
verify_data[ip] 192.168.1.100 IP地址
verify_data[domain] www.example.com 绑定域名
verify_data[mac] 00:1A:2B:3C:4D:5E MAC地址
verify_data[phone] 13800138000 手机号
verify_data[custom_xxx] 自定义值 自定义字段，如 custom_VIP、custom_MM 等

请求示例

GET /auth-api/auth.php?action=query&app_token=abc123def456&verify_data[ip]=192.168.1.100&verify_data[custom_VIP]=55

成功响应

json 
{
    "code": 200,
    "message": "查询成功",
    "data": {
        "id": 10086,
        "app_id": 1,
        "contact": "user@example.com",
        "username": "api_device123",
        "expire_time": "2025-12-31 23:59:59",
        "status": 1,
        "app_name": "超级工具箱",
        "fields": [
            {"field_type": "ip", "field_label": "IP地址", "field_value": "192.168.1.100"},
            {"field_type": "custom_VIP", "field_label": "VIP", "field_value": "55"}
        ],
        "remain_count": 95,
        "total_count": 100
    }
}

响应参数说明

参数名 类型 说明
id int 授权记录ID
app_id int 应用ID
contact string 联系方式
username string 用户名
expire_time string 授权过期时间
status int 状态：1=正常，0=禁用或过期
app_name string 应用名称
card_type string 授权码类型：time=按天, count=按次, combo=组合
fields array 授权字段列表
remain_count int 剩余次数（按次/组合型授权码返回）
total_count int 总次数（按次/组合型授权码返回）
card_days int 授权码天数（按天/组合型授权码返回）
remaining_days int 剩余天数（按天/组合型授权码返回）
card_expire_time string 授权码到期时间（按天/组合型授权码返回）

获取公告

获取系统公告或应用公告列表。

GET /auth-api/public_action.php?action=announcements

请求参数

参数名 类型 必填 说明
action string 是 固定值：announcements
type string 否 公告类型：system(系统公告)、app(应用公告)，默认system
page int 否 页码，默认1
page_size int 否 每页数量，默认5

成功响应

json 
{
    "success": true,
    "data": [
        {
            "id": 1,
            "title": "系统升级通知",
            "content": "系统将于2024年12月进行升级维护",
            "created_at": "2024-11-20 09:00:00"
        }
    ],
    "total": 10,
    "page": 1,
    "page_size": 5,
    "total_pages": 2,
    "has_more": true
}

获取应用信息

获取应用的基本信息和需要填写的授权字段。

GET /auth-api/auth.php?action=app_info

请求参数

参数名 类型 必填 说明
action string 是 固定值：app_info
app_token string 是 应用Token

成功响应

json 
{
    "code": 200,
    "message": "获取成功",
    "data": {
        "app_id": 1,
        "app_name": "超级工具箱",
        "description": "一款功能强大的工具软件",
        "status": 1,
        "fields": [
            {"type": "ip", "label": "IP地址", "required": true},
            {"type": "domain", "label": "绑定域名", "required": false}
        ]
    }
}

错误码说明

错误码 错误信息 说明
400 缺少xxx参数 必填参数未传递
400 缺少授权内容：xxx verify_data中缺少必填字段
403 授权验证失败 授权字段验证不匹配
403 授权已过期 授权已超过有效期
403 授权已失效 授权状态被禁用
403 验证次数已用完 次数型/组合型授权：remain_verify_count <= 0
403 该授权码已被使用 授权码status=1，已被激活
403 该授权码已被禁用 授权码status=2
403 该授权码已过期 授权码超过有效期
403 次数不足 按次/组合授权：remain_count <= 0
403 天数不足 按天/组合授权：超过有效期
403 授权码未激活 按天授权：授权码没有used_time
403 授权码天数无效 按天授权：card_days <= 0
403 应用已关闭授权 应用status != 1
404 应用不存在 app_token错误
404 授权不存在 未找到匹配的授权记录
404 授权码不存在 card_code错误
404 授权码不存在或与应用不匹配 授权码不属于该应用
500 服务器内部错误 请联系管理员