API 文档

完整的 RESTful API 参考文档

API 认证

所有 API 请求都需要通过 Bearer Token 进行认证。请在请求头中包含您的 API Token：

Authorization: Bearer <your-api-token>

您可以在 账户设置 中查看或重新生成您的 API Token。

API 基础地址

https://casp.hx12.top/api/v1/

响应格式

所有 API 响应都采用 JSON 格式。成功的响应格式如下： 

{
  "success": true,
  "message": "操作成功",
  "data": { ... }
}

错误的响应格式：

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "错误描述"
  }
}

错误代码

代码 描述
UNAUTHORIZED 未认证或 Token 无效
VALIDATION_ERROR 请求参数验证失败
NOT_FOUND 请求的资源不存在
RATE_LIMIT_EXCEEDED 请求频率超限
SERVER_ERROR 服务器内部错误

Authentication

POST /api/v1/auth.php?action=login

用户登录

请求参数：
参数 类型 必填 说明
email string 是 邮箱地址
password string 是 密码
响应示例： 
{
    "success": true,
    "data": {
        "user_id": 1,
        "email": "user@example.com"
    }
}
POST /api/v1/auth.php?action=register

用户注册

请求参数：
参数 类型 必填 说明
email string 是 邮箱地址
password string 是 密码（至少8位，含大小写和数字）
name string 否 昵称
响应示例： 
{
    "success": true,
    "data": {
        "user_id": 1,
        "verify_token": "..."
    }
}
POST /api/v1/auth.php?action=forgot-password

请求密码重置

请求参数：
参数 类型 必填 说明
email string 是 注册邮箱
响应示例： 
{
    "success": true,
    "message": "If the email exists, a reset link has been sent."
}

Certificates

GET /api/v1/certificates.php

获取证书列表

请求头：
Authorization: Bearer <token>
请求参数：
参数 类型 必填 说明
status string 否 过滤状态：issued, pending, expired
ca_provider string 否 CA提供商
page integer 否 页码
响应示例： 
null
GET /api/v1/certificates.php?id={id}

获取证书详情

请求头：
Authorization: Bearer <token>
响应示例： 
null
POST /api/v1/certificates.php

申请新证书

请求头：
Authorization: Bearer <token>
请求参数：
参数 类型 必填 说明
ca_provider string 是 CA：letsencrypt, zerossl, litessl, buypass, google, sslcom
domains array 是 域名数组，如 ["example.com", "www.example.com"]
challenge_type string 否 验证方式：dns-01（默认）或 http-01
响应示例： 
null
POST /api/v1/certificates.php?action=renew

续签证书

请求头：
Authorization: Bearer <token>
请求参数：
参数 类型 必填 说明
id integer 是 证书ID
响应示例： 
{
    "success": true,
    "data": {
        "expires_at": "2025-03-24"
    }
}
DELETE /api/v1/certificates.php?id={id}

删除证书

请求头：
Authorization: Bearer <token>
响应示例： 
{
    "success": true,
    "message": "Certificate deleted successfully"
}

Domains

GET /api/v1/domains.php

获取域名列表

请求头：
Authorization: Bearer <token>
响应示例： 
null
POST /api/v1/domains.php

添加域名

请求头：
Authorization: Bearer <token>
请求参数：
参数 类型 必填 说明
domain string 是 域名
verification_method string 否 dns-01 或 http-01
响应示例： 
{
    "success": true,
    "data": {
        "id": 1
    }
}

Renewal

GET /api/v1/renewal.php

获取续签统计

请求头：
Authorization: Bearer <token>
响应示例： 
{
    "success": true,
    "data": {
        "successful_renewals": 10,
        "pending_renewals": 2
    }
}

Notifications

GET /api/v1/notifications.php

获取通知列表

请求头：
Authorization: Bearer <token>
响应示例： 
null
POST /api/v1/notifications.php?action=mark-read

标记通知为已读

请求头：
Authorization: Bearer <token>
请求参数：
参数 类型 必填 说明
id integer 是 通知ID
响应示例： 
{
    "success": true
}

速率限制

API 请求频率限制为每分钟 100 次请求。超过限制将返回 429 Too Many Requests 响应。