SSL证书检测API接口能力边界解析：参数、响应与工程实践
适用场景
在运维、安全审计和自动化部署流程中，证书过期或配置错误是常见故障原因。本接口适用于以下场景：
- 证书过期监控：定时检测域名证书剩余天数，当
expire_days小于阈值时触发告警。 - 域名迁移验证：迁移前后对比
fingerprint确保证书一致。 - 批量域名巡检：结合Cron任务对列表中的域名逐个请求，生成SSL状态报告。
- 安全合规检查：验证颁发机构、签名算法是否符合企业安全策略。
接口能力边界
本接口的核心能力是远程探测域名当前部署的HTTPS/SSL证书信息，而非提供证书链解析或私钥检查。其边界如下：
- 三态响应模型：
is_ssl=true：证书存在，返回完整字段。is_ssl=false：域名无SSL证书或连接失败，其余字段为null。- HTTP 502：上游服务器异常，无法完成检测。
- 域名预处理：自动剥离
http://、https://、路径、端口、www.前缀，开发者无需额外清洗。 - 严格校验：仅接受合法域名（最长253字符，符合RFC 1123标签规则），非法域名返回错误。
- 缓存策略：
- 成功响应缓存6小时（证书短期不变）。
- 无证书响应缓存30分钟（避免对无效域名重复请求上游）。
- QPS限制：5次/秒，超限返回429。
请求参数与鉴权
接口地址：https://v1.apizero.cn/api/ssl
请求方法：GET
Query参数
| 参数名 | 必填 | 类型 | 说明 | 示例 |
|---|---|---|---|---|
domain | 是 | string | 要检测的域名，可含协议、路径、端口、www.，自动剥离 | apizero.cn |
Header参数
| 参数名 | 必填 | 类型 | 说明 | 示例 |
|---|---|---|---|---|
Authorization | 否 | string | API Key鉴权，格式Bearer sk_live_xxx；匿名调用有限额 | Bearer sk_live_xxxxxxxxxxxxxx |
注意：虽然部分早期文档使用
X-API-Key头，但当前标准为Authorization: Bearer <key>，建议统一使用此格式。
代码接入（curl示例）
以下示例使用curl发起GET请求，替换YOUR_API_KEY为实际密钥（匿名调用可省略该Header）。
curl -sS \ -X GET \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ "https://v1.apizero.cn/api/ssl?domain=apizero.cn"若希望查看更详细的HTTP状态码，可添加-w "\nHTTP_CODE:%{http_code}"。
Python示例
使用requests库：
import requests url = "https://v1.apizero.cn/api/ssl" params = {"domain": "apizero.cn"} headers = {"Authorization": "Bearer sk_live_YOUR_API_KEY"} resp = requests.get(url, params=params, headers=headers) data = resp.json() print(data)Node.js示例（axios）
const axios = require('axios'); const url = 'https://v1.apizero.cn/api/ssl'; const params = { domain: 'apizero.cn' }; const headers = { Authorization: 'Bearer sk_live_YOUR_API_KEY' }; axios.get(url, { params, headers }) .then(response => console.log(response.data)) .catch(error => console.error(error));返回字段解读
成功响应HTTP 200，JSON结构如下：
{ "code": 0, "msg": "成功", "request_id": "abc123def456", "data": { "common_name": "*.apizero.cn", "domain": "apizero.cn", "domains": ["*.apizero.cn", "apizero.cn"], "expire_date": "2026-11-07 17:04:59", "expire_days": 184, "fingerprint": "f4633adfd1cb59185ba094dc3edeef5a8ea26889", "is_expired": false, "is_ssl": true, "issuer": "Certum DV TLS G2 R39 CA", "issuing_agency": "Asseco Data Systems S.A.", "life_span_days": 198, "remote_address": "119.36.225.184:443", "signature_algorithm": "RSA-SHA256", "start_date": "2026-04-22 17:05:00" } }各字段含义：
| 字段 | 类型 | 说明 |
|---|---|---|
code | int | 业务状态码，0成功 |
msg | string | 状态描述 |
request_id | string | 请求唯一ID，用于日志追踪 |
common_name | string | 证书通用名称，通常是通配符或域名 |
domain | string | 请求的域名（原始或处理后） |
domains | array | 证书覆盖的所有域名 |
expire_date | string | 证书到期时间（UTC+8） |
expire_days | int | 距离到期天数，从检测时刻起算 |
fingerprint | string | SHA-1指纹，用于唯一标识证书 |
is_expired | bool | 是否已过期 |
is_ssl | bool | 是否成功获取证书信息 |
issuer | string | 证书颁发者名称 |
issuing_agency | string | 证书颁发机构 |
life_span_days | int | 证书总有效天数 |
remote_address | string | 服务器IP:端口 |
signature_algorithm | string | 签名算法 |
start_date | string | 证书生效时间 |
当is_ssl为false时，data中除domain和is_ssl外均为null。
常见错误与处理
| HTTP状态码 | 说明 | 典型原因 |
|---|---|---|
| 400 | Bad Request | 缺少domain参数或域名格式非法 |
| 401 | Unauthorized | Authorization头缺失或API Key无效 |
| 429 | Too Many Requests | 超出QPS限制（5次/秒） |
| 502 | Bad Gateway | 上游检测服务异常，可重试 |
200但code!=0 | 业务错误 | 查看msg字段具体描述 |
错误排查建议
- 502错误：通常是上游临时故障，使用指数退避重试（如等待1秒、2秒、4秒）。
- 401错误：检查API Key是否有效且未过期。
- 400错误：确保域名不包含多余字符，长度≤253。
- 所有响应：记录
request_id便于技术支持时提供。
工程化注意事项
1. 缓存策略利用
同一域名证书在6小时内几乎不变，建议在应用层也缓存成功响应，减少API调用次数。对于is_ssl=false的响应，可缓存30分钟，避免重复请求。
2. 并发控制
单线程QPS为5，若需批量检测，应控制并发数或加入延时。例如使用asyncio或Promise.all时，每次请求间隔200ms以上。
3. 域名预处理
虽然接口自动剥离前缀和路径，但建议在发送前进行基本校验，减少无效请求。例如使用正则过滤非法字符。
4. 错误重试策略
对于502和429（超限），采用退避重试。429时需等待至少1秒，并考虑降低频率。
5. 日志与监控
记录每次请求的request_id、domain、is_ssl、expire_days，建立监控看板，当证书即将过期或检测失败时告警。
6. 安全性
API Key应存储在环境变量或密钥管理服务中，勿硬编码。匿名调用有限额，生产环境建议使用正式密钥。
参考文档
- SSL证书检测API官方文档
- 原始Markdown文档