开放平台 API 技术规范文档 - 虚拟网络备案系统

1

接口概览与通用规范

所有接口均遵循标准 RESTful 架构风格，支持跨域访问（CORS 友好）。接口数据请求与响应均强制采用 UTF-8 字符编码，数据实体统一采用标准 JSON 序列化格式输出（动态徽章 SVG 除外）。

传输协议规范 HTTPS / TLS 1.2+

推荐在生产环境全链路开启 SSL/TLS 加密

请求格式 & 编码 JSON / UTF-8

Content-Type: application/json

统一时间戳规范 YYYY-MM-DD HH:mm:ss

附加 10 位标准 Unix 纪元时间戳

2

接口认证与调用限流

2.1 认证方式

系统支持两种接口调用模式。当前系统运行模式为： 公开模式 (Public Mode) 。

若启用了 Token 认证模式，客户端可通过以下任意一种途径携带凭据：

HTTP 请求头（推荐）：X-API-Key: your_api_key_here
Bearer 标准头：Authorization: Bearer your_api_key_here
URL Query 参数：?api_key=your_api_key_here 或 ?token=your_api_key_here

2.2 频控策略 (Rate Limiting)

为保障公共基础设施的可用性，网关实施基于客户端 IP 的滑动窗口频控。当前配置的限流阈值为： 60 次/分钟/IP。

当单 IP 在 1 分钟内的调用次数超出限制时，网关将拒绝请求并返回 HTTP 429 Too Many Requests 状态码。

3

证书防伪权威核验接口

面向第三方核验工具或扫码核对，获取具有防伪数字指纹签名与主体有效性的权威事实

GET

GET https://noveltyicp.de5.net/api/verify

请求参数 (Query Parameters)

参数字段	类型	必填	说明	示例值
number	string	二选一	8 位固定数字备案编号	20260001
domain	string	二选一	在册绑定的接入主域名或从属域名	example.com
keyword	string	可选	通用检索词（编号/域名）	20260001

多语言调用代码示例 (Code Samples)

安全提示：示例中的 YOUR_API_KEY 为示例占位符。若当前系统启用了 Token 认证，请从管理后台获取，切勿将真实密钥提交至公共代码仓库。

curl -X GET "https://noveltyicp.de5.net/api/verify?number=20260001" \
  -H "Accept: application/json" \
  -H "X-API-Key: YOUR_API_KEY"

const response = await fetch('https://noveltyicp.de5.net/api/verify?number=20260001', {
  method: 'GET',
  headers: {
    'Accept': 'application/json',
    'X-API-Key': 'YOUR_API_KEY'
  }
});
const result = await response.json();
console.log('防伪核验结果:', result.data.verification.is_valid);

import requests

url = "https://noveltyicp.de5.net/api/verify"
params = {"number": "20260001"}
headers = {
    "Accept": "application/json",
    "X-API-Key": "YOUR_API_KEY"
}

res = requests.get(url, params=params, headers=headers)
data = res.json()
print("核验结果：", data.get("data", {}).get("verification"))

<?php
$ch = curl_init("https://noveltyicp.de5.net/api/verify?number=20260001");
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'Accept: application/json',
    'X-API-Key': 'YOUR_API_KEY'
]);
$response = curl_exec($ch);
curl_close($ch);

$result = json_decode($response, true);
var_dump($result['data']['verification']['is_valid']);

响应报文示例 (Response Samples)

200 OK 查验成功 Content-Type: application/json

{
  "code": 200,
  "message": "查验成功：在册合法备案主体",
  "data": {
    "subject": {
      "icp_number": "20260001",
      "formatted_number": "NICPICP备20260001号",
      "site_name": "示例站长博客",
      "site_desc": "个人技术随笔与开源创作",
      "site_avatar": "/uploads/avatar.png",
      "owner_name": "张站长",
      "status": 2,
      "status_label": "审核通过",
      "inspection_status": 1,
      "inspection_label": "巡检合规",
      "approved_at": "2026-03-15 10:30:00",
      "created_at": "2026-03-14 18:20:00"
    },
    "domains": [
      "example.com",
      "www.example.com"
    ],
    "verification": {
      "is_valid": true,
      "verify_digest": "a9f8b2c4e1d7039a84f3c7b2e6a1059f...",
      "cert_issuer": "虚拟网络备案中心",
      "verify_url": "/verify?number=20260001",
      "timestamp": 1773539400
    }
  }
}

404 Not Found 未收录 Content-Type: application/json

{
  "code": 404,
  "message": "查验目标在册档案不存在或未收录",
  "data": null
}

4

备案信息检索接口 (Filing Lookup)

根据域名、编号或关键字模糊检索公开备案主体信息

GET

GET https://noveltyicp.de5.net/api/lookup

请求参数 (Query Parameters)

参数字段	类型	必填	说明	示例值
keyword	string	必填	查询关键字（域名、备案编号、或网站名称）	example.com

响应报文示例 (Response Samples)

200 OK 查询成功 Content-Type: application/json

{
  "code": 200,
  "message": "查询成功",
  "data": {
    "site_name": "示例站长博客",
    "site_domain": [
      "example.com"
    ],
    "site_description": "个人技术随笔与开源创作",
    "site_avatar": "/uploads/avatar.png",
    "icp_number": "20260001",
    "icp_number_formatted": "NICPICP备20260001号",
    "owner": "张站长",
    "status": 2,
    "status_label": "审核通过",
    "inspection_status": 1,
    "approved_at": "2026-03-15 10:30:00",
    "created_at": "2026-03-14 18:20:00"
  }
}

5

动态认证徽章挂件接口 (SVG Badge)

生成矢量 SVG 徽章图标，可直接嵌入 GitHub README、个人博客页脚或导航

SVG

GET https://noveltyicp.de5.net/api/widget/badge?icp=20260001

Markdown 嵌入语法示例：


                                [![NICPICP备](https://noveltyicp.de5.net/api/widget/badge?icp=20260001)](https://noveltyicp.de5.net/verify?number=20260001)

6

服务状态与健康检查接口 (Status & Health)

用于第三方服务监控、心跳检查与服务可用性检测

GET

GET https://noveltyicp.de5.net/api/status

200 OK 服务正常 Content-Type: application/json

{
  "code": 200,
  "message": "服务运行正常",
  "data": {
    "api_version": "1.0.0",
    "service_name": "虚拟网络备案系统 Open API",
    "server_time": "2026-09-20 07:45:00",
    "timestamp": 1774136700,
    "auth_mode": "public",
    "rate_limit": 60,
    "endpoints": {
      "verify": "/api/verify?number={number}&domain={domain}",
      "lookup": "/api/lookup?keyword={keyword}",
      "badge": "/api/widget/badge?icp={number}"
    }
  }
}

7

HTTP 状态码与异常处理规范

HTTP 状态码	业务代码	含义描述	建议处理策略
200 OK	200	请求成功，已正常返回实体报文	正常解析业务数据包 (data)
400 Bad Request	400	缺少必填请求参数或入参格式不合法	核对接口文档中的请求参数字段要求
401 Unauthorized	401	缺少有效 API Key 或认证失败	检查并在 Header 中传递 X-API-Key
403 Forbidden	403	开放 API 服务已被系统管理员暂时关闭	请联络平台管理员确认服务开放窗口
404 Not Found	404	查验目标未在册收录或记录不存在	核对输入的 8 位编号或域名拼写
429 Too Many Requests	429	IP 调用频率超过单分钟阈值限流	客户端加入指数退避或稍后（60s）重试
500 Server Error	500	服务端内部异常或数据库连接波动	重试请求或联系平台技术支持

8

开发者技术支持与接口联调

如在接口对接、防伪挂件部署或高并发调用过程中遇到任何问题，欢迎随时与平台官方技术运维团队联络获取指导：

官方邮箱：[email protected] 自主可控白标数字凭证架构

虚拟网络备案系统 开放接口文档

接口概览与通用规范

接口认证与调用限流

2.1 认证方式

2.2 频控策略 (Rate Limiting)

证书防伪权威核验接口

请求参数 (Query Parameters)

多语言调用代码示例 (Code Samples)

响应报文示例 (Response Samples)

备案信息检索接口 (Filing Lookup)

请求参数 (Query Parameters)

响应报文示例 (Response Samples)

动态认证徽章挂件接口 (SVG Badge)

服务状态与健康检查接口 (Status & Health)

HTTP 状态码与异常处理规范

开发者技术支持与接口联调

虚拟网络备案系统开放接口文档