API接口文档

本文档详细介绍 Yuan-ICP 系统提供的 API 接口，包括接口规范、使用方法、参数说明和示例代码。

📋 API概览

Yuan-ICP 系统提供 RESTful API 接口，支持：

号码获取：获取可用的备案号码
申请提交：提交备案申请
状态查询：查询申请状态
数据统计：获取系统统计数据

API基础信息

基础URL：/api/
协议：HTTP/HTTPS
数据格式：JSON
字符编码：UTF-8
认证方式：API Key（可选）

🔑 认证和授权

API Key认证

对于需要认证的接口，请在请求头中添加API Key：

http

Authorization: Bearer YOUR_API_KEY

获取API Key

登录后台管理系统
进入"系统设置" → "API管理"
生成新的API Key
设置API Key的权限和有效期

权限级别

权限级别	描述	可访问接口
public	公开接口	号码获取、申请查询
user	用户接口	申请提交、状态查询
admin	管理接口	数据统计、系统管理

📡 号码获取接口

获取可用号码

接口信息

URL：/api/get_numbers.php
方法：GET
描述：获取可用的备案号码列表

请求参数

参数名	类型	必填	默认值	说明
`mode`	string	否	`auto`	获取模式：`auto`(自动生成) 或 `pool`(号码池)
`count`	integer	否	`1`	获取数量，最大100
`premium_only`	boolean	否	`false`	是否只要靓号
`format`	string	否	系统默认	号码格式（仅自动生成模式）

请求示例

bash

# 获取1个自动生成的号码
curl "https://your-domain.com/api/get_numbers.php?mode=auto&count=1"

# 获取5个号码池中的号码
curl "https://your-domain.com/api/get_numbers.php?mode=pool&count=5"

# 获取靓号
curl "https://your-domain.com/api/get_numbers.php?premium_only=true&count=3"

响应格式

json

{
    "success": true,
    "data": {
        "numbers": [
            {
                "number": "YuanAB12345678",
                "is_premium": true,
                "mode": "auto"
            },
            {
                "number": "YuanCD87654321",
                "is_premium": false,
                "mode": "pool"
            }
        ],
        "total": 2,
        "mode": "auto"
    },
    "message": "成功获取号码",
    "timestamp": "2024-01-15T10:30:00Z"
}

响应字段说明

字段名	类型	说明
`success`	boolean	请求是否成功
`data.numbers`	array	号码列表
`data.numbers[].number`	string	备案号码
`data.numbers[].is_premium`	boolean	是否为靓号
`data.numbers[].mode`	string	号码来源模式
`data.total`	integer	返回的号码总数
`data.mode`	string	实际使用的获取模式
`message`	string	响应消息
`timestamp`	string	响应时间戳

错误响应

json

{
    "success": false,
    "error": {
        "code": "INVALID_PARAMETER",
        "message": "无效的参数值",
        "details": "count参数必须在1-100之间"
    },
    "timestamp": "2024-01-15T10:30:00Z"
}

错误代码说明

错误代码	HTTP状态码	说明
`INVALID_PARAMETER`	400	参数无效
`MODE_NOT_SUPPORTED`	400	不支持的获取模式
`NO_NUMBERS_AVAILABLE`	404	没有可用的号码
`RATE_LIMIT_EXCEEDED`	429	请求频率超限
`INTERNAL_ERROR`	500	服务器内部错误

📝 申请提交接口

提交备案申请

接口信息

URL：/api/submit_application.php
方法：POST
描述：提交新的备案申请

请求参数

参数名	类型	必填	说明
`website_name`	string	是	网站名称
`domain`	string	是	网站域名
`description`	string	否	网站描述
`owner_name`	string	是	申请人姓名
`owner_email`	string	是	申请人邮箱
`owner_phone`	string	否	申请人电话
`number`	string	否	指定备案号（可选）
`csrf_token`	string	是	CSRF令牌

请求示例

bash

curl -X POST "https://your-domain.com/api/submit_application.php" \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "website_name": "示例网站",
    "domain": "example.com",
    "description": "这是一个示例网站",
    "owner_name": "张三",
    "owner_email": "zhangsan@example.com",
    "owner_phone": "13800138000"
  }'

响应格式

json

{
    "success": true,
    "data": {
        "application_id": 123,
        "number": "YuanAB12345678",
        "status": "pending",
        "submitted_at": "2024-01-15T10:30:00Z"
    },
    "message": "申请提交成功",
    "timestamp": "2024-01-15T10:30:00Z"
}

响应字段说明

字段名	类型	说明
`data.application_id`	integer	申请ID
`data.number`	string	分配的备案号
`data.status`	string	申请状态
`data.submitted_at`	string	提交时间

🔍 状态查询接口

查询申请状态

接口信息

URL：/api/query_application.php
方法：GET
描述：查询备案申请的状态

请求参数

参数名	类型	必填	说明
`number`	string	否	备案号（与域名二选一）
`domain`	string	否	域名（与备案号二选一）
`email`	string	否	申请人邮箱（用于验证身份）

请求示例

bash

# 按备案号查询
curl "https://your-domain.com/api/query_application.php?number=YuanAB12345678"

# 按域名查询
curl "https://your-domain.com/api/query_application.php?domain=example.com"

# 按邮箱查询
curl "https://your-domain.com/api/query_application.php?email=zhangsan@example.com"

响应格式

json

{
    "success": true,
    "data": {
        "application": {
            "id": 123,
            "number": "YuanAB12345678",
            "website_name": "示例网站",
            "domain": "example.com",
            "description": "这是一个示例网站",
            "owner_name": "张三",
            "owner_email": "zhangsan@example.com",
            "owner_phone": "13800138000",
            "status": "approved",
            "created_at": "2024-01-15T10:30:00Z",
            "reviewed_at": "2024-01-15T14:20:00Z",
            "reviewer": "admin"
        }
    },
    "message": "查询成功",
    "timestamp": "2024-01-15T15:00:00Z"
}

响应字段说明

字段名	类型	说明
`data.application.id`	integer	申请ID
`data.application.number`	string	备案号
`data.application.website_name`	string	网站名称
`data.application.domain`	string	域名
`data.application.status`	string	申请状态
`data.application.created_at`	string	创建时间
`data.application.reviewed_at`	string	审核时间
`data.application.reviewer`	string	审核人

📊 统计接口

获取系统统计

接口信息

URL：/api/statistics.php
方法：GET
描述：获取系统统计数据
权限：需要admin权限

请求参数

参数名	类型	必填	说明
`type`	string	否	统计类型：`overview`(概览) 或 `detailed`(详细)
`period`	string	否	统计周期：`today`(今天) 或 `month`(本月)

请求示例

bash

curl -H "Authorization: Bearer ADMIN_API_KEY" \
  "https://your-domain.com/api/statistics.php?type=overview&period=month"

响应格式

json

{
    "success": true,
    "data": {
        "overview": {
            "total_applications": 156,
            "pending_applications": 15,
            "approved_applications": 128,
            "rejected_applications": 13,
            "total_numbers": 1000,
            "available_numbers": 844,
            "premium_numbers": 89
        },
        "period": "month",
        "generated_at": "2024-01-15T15:00:00Z"
    },
    "message": "统计数据获取成功",
    "timestamp": "2024-01-15T15:00:00Z"
}

🚨 错误处理

标准错误响应

所有API接口在发生错误时都会返回统一的错误格式：

json

{
    "success": false,
    "error": {
        "code": "ERROR_CODE",
        "message": "错误描述",
        "details": "详细错误信息"
    },
    "timestamp": "2024-01-15T15:00:00Z"
}

HTTP状态码

状态码	说明
200	请求成功
400	请求参数错误
401	未授权（需要API Key）
403	禁止访问（权限不足）
404	资源不存在
429	请求频率超限
500	服务器内部错误

常见错误处理

javascript

// JavaScript错误处理示例
async function callAPI(url, options = {}) {
    try {
        const response = await fetch(url, options);
        const data = await response.json();
        
        if (!data.success) {
            throw new Error(data.error.message);
        }
        
        return data;
    } catch (error) {
        console.error('API调用失败:', error.message);
        throw error;
    }
}

// 使用示例
try {
    const result = await callAPI('/api/get_numbers.php?count=5');
    console.log('获取到的号码:', result.data.numbers);
} catch (error) {
    console.error('获取号码失败:', error.message);
}

📱 客户端集成

JavaScript SDK

javascript

/**
 * Yuan-ICP API SDK
 */
class YuanICPSDK {
    constructor(baseURL, apiKey = null) {
        this.baseURL = baseURL;
        this.apiKey = apiKey;
    }
    
    // 设置请求头
    getHeaders() {
        const headers = {
            'Content-Type': 'application/json'
        };
        
        if (this.apiKey) {
            headers['Authorization'] = `Bearer ${this.apiKey}`;
        }
        
        return headers;
    }
    
    // 通用请求方法
    async request(endpoint, options = {}) {
        const url = `${this.baseURL}${endpoint}`;
        const config = {
            headers: this.getHeaders(),
            ...options
        };
        
        const response = await fetch(url, config);
        const data = await response.json();
        
        if (!data.success) {
            throw new Error(data.error.message);
        }
        
        return data;
    }
    
    // 获取号码
    async getNumbers(options = {}) {
        const params = new URLSearchParams(options);
        return this.request(`/api/get_numbers.php?${params}`);
    }
    
    // 提交申请
    async submitApplication(applicationData) {
        return this.request('/api/submit_application.php', {
            method: 'POST',
            body: JSON.stringify(applicationData)
        });
    }
    
    // 查询申请
    async queryApplication(query) {
        const params = new URLSearchParams(query);
        return this.request(`/api/query_application.php?${params}`);
    }
    
    // 获取统计
    async getStatistics(options = {}) {
        const params = new URLSearchParams(options);
        return this.request(`/api/statistics.php?${params}`);
    }
}

// 使用示例
const sdk = new YuanICPSDK('https://your-domain.com', 'YOUR_API_KEY');

// 获取号码
sdk.getNumbers({ count: 5, premium_only: true })
    .then(result => {
        console.log('获取到的号码:', result.data.numbers);
    })
    .catch(error => {
        console.error('获取号码失败:', error.message);
    });

// 提交申请
sdk.submitApplication({
    website_name: '示例网站',
    domain: 'example.com',
    owner_name: '张三',
    owner_email: 'zhangsan@example.com'
})
.then(result => {
    console.log('申请提交成功:', result.data);
})
.catch(error => {
    console.error('申请提交失败:', error.message);
});

PHP客户端

php

<?php
/**
 * Yuan-ICP API PHP客户端
 */
class YuanICPSDK {
    private $baseURL;
    private $apiKey;
    
    public function __construct($baseURL, $apiKey = null) {
        $this->baseURL = rtrim($baseURL, '/');
        $this->apiKey = $apiKey;
    }
    
    /**
     * 发送HTTP请求
     */
    private function request($endpoint, $method = 'GET', $data = null) {
        $url = $this->baseURL . $endpoint;
        
        $ch = curl_init();
        curl_setopt($ch, CURLOPT_URL, $url);
        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_TIMEOUT, 30);
        
        $headers = ['Content-Type: application/json'];
        if ($this->apiKey) {
            $headers[] = 'Authorization: Bearer ' . $this->apiKey;
        }
        curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
        
        if ($method === 'POST') {
            curl_setopt($ch, CURLOPT_POST, true);
            if ($data) {
                curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
            }
        }
        
        $response = curl_exec($ch);
        $httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
        curl_close($ch);
        
        if ($response === false) {
            throw new Exception('请求失败');
        }
        
        $result = json_decode($response, true);
        if (!$result) {
            throw new Exception('响应解析失败');
        }
        
        if (!$result['success']) {
            throw new Exception($result['error']['message']);
        }
        
        return $result;
    }
    
    /**
     * 获取号码
     */
    public function getNumbers($options = []) {
        $params = http_build_query($options);
        return $this->request('/api/get_numbers.php?' . $params);
    }
    
    /**
     * 提交申请
     */
    public function submitApplication($data) {
        return $this->request('/api/submit_application.php', 'POST', $data);
    }
    
    /**
     * 查询申请
     */
    public function queryApplication($query) {
        $params = http_build_query($query);
        return $this->request('/api/query_application.php?' . $params);
    }
    
    /**
     * 获取统计
     */
    public function getStatistics($options = []) {
        $params = http_build_query($options);
        return $this->request('/api/statistics.php?' . $params);
    }
}

// 使用示例
try {
    $sdk = new YuanICPSDK('https://your-domain.com', 'YOUR_API_KEY');
    
    // 获取号码
    $result = $sdk->getNumbers(['count' => 5, 'premium_only' => true]);
    echo "获取到的号码: " . json_encode($result['data']['numbers']) . "\n";
    
    // 提交申请
    $result = $sdk->submitApplication([
        'website_name' => '示例网站',
        'domain' => 'example.com',
        'owner_name' => '张三',
        'owner_email' => 'zhangsan@example.com'
    ]);
    echo "申请提交成功: " . $result['data']['number'] . "\n";
    
} catch (Exception $e) {
    echo "操作失败: " . $e->getMessage() . "\n";
}
?>

🔒 安全考虑

API安全最佳实践

使用HTTPS：所有API调用都应使用HTTPS协议
API Key管理：定期轮换API Key，设置合理的权限
请求频率限制：实施请求频率限制，防止滥用
输入验证：验证所有输入参数，防止注入攻击
日志记录：记录所有API调用，便于审计和监控

频率限制

系统实施以下频率限制：

公开接口：每分钟最多60次请求
用户接口：每分钟最多30次请求
管理接口：每分钟最多10次请求

超过限制时，系统返回429状态码和相应的错误信息。

📚 相关文档

项目结构 - 了解项目组织方式
核心函数 - 系统核心函数说明
数据库结构 - 数据库设计文档
安装指南 - 系统安装说明

🎯 总结

Yuan-ICP API提供了完整的接口服务：

号码管理：获取和管理备案号码
申请处理：提交和查询备案申请
数据统计：获取系统运行数据
安全可靠：完善的认证和授权机制

通过合理使用API接口，您可以：

集成到现有系统中
开发移动应用
自动化备案流程
构建第三方服务

如有问题或建议，欢迎：

在 GitHub Issues 中报告问题
提交 Pull Request 改进文档
在 Discussions 中讨论API设计

API接口文档 ​

📋 API概览 ​

API基础信息 ​

🔑 认证和授权 ​

API Key认证 ​

获取API Key ​

权限级别 ​

📡 号码获取接口 ​

获取可用号码 ​

接口信息 ​

请求参数 ​

请求示例 ​

响应格式 ​

响应字段说明 ​

错误响应 ​

错误代码说明 ​

📝 申请提交接口 ​

提交备案申请 ​

接口信息 ​

请求参数 ​

请求示例 ​

响应格式 ​

响应字段说明 ​

🔍 状态查询接口 ​

查询申请状态 ​

接口信息 ​

请求参数 ​

请求示例 ​

响应格式 ​

响应字段说明 ​

📊 统计接口 ​

获取系统统计 ​

接口信息 ​

请求参数 ​

请求示例 ​

响应格式 ​

🚨 错误处理 ​

标准错误响应 ​

HTTP状态码 ​

常见错误处理 ​

📱 客户端集成 ​

JavaScript SDK ​

PHP客户端 ​

🔒 安全考虑 ​

API安全最佳实践 ​

频率限制 ​

📚 相关文档 ​

🎯 总结 ​

API接口文档

📋 API概览

API基础信息

🔑 认证和授权

API Key认证

获取API Key

权限级别

📡 号码获取接口

获取可用号码

接口信息

请求参数

请求示例

响应格式

响应字段说明

错误响应

错误代码说明

📝 申请提交接口

提交备案申请

接口信息

请求参数

请求示例

响应格式

响应字段说明

🔍 状态查询接口

查询申请状态

接口信息

请求参数

请求示例

响应格式

响应字段说明

📊 统计接口

获取系统统计

接口信息

请求参数

请求示例

响应格式

🚨 错误处理

标准错误响应

HTTP状态码

常见错误处理

📱 客户端集成

JavaScript SDK

PHP客户端

🔒 安全考虑

API安全最佳实践

频率限制

📚 相关文档

🎯 总结