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否stringAPI 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" } }

各字段含义：

字段类型说明
codeint业务状态码，0成功
msgstring状态描述
request_idstring请求唯一ID，用于日志追踪
common_namestring证书通用名称，通常是通配符或域名
domainstring请求的域名（原始或处理后）
domainsarray证书覆盖的所有域名
expire_datestring证书到期时间（UTC+8）
expire_daysint距离到期天数，从检测时刻起算
fingerprintstringSHA-1指纹，用于唯一标识证书
is_expiredbool是否已过期
is_sslbool是否成功获取证书信息
issuerstring证书颁发者名称
issuing_agencystring证书颁发机构
life_span_daysint证书总有效天数
remote_addressstring服务器IP:端口
signature_algorithmstring签名算法
start_datestring证书生效时间

当is_ssl为false时，data中除domain和is_ssl外均为null。

常见错误与处理

HTTP状态码说明典型原因
400Bad Request缺少domain参数或域名格式非法
401UnauthorizedAuthorization头缺失或API Key无效
429Too Many Requests超出QPS限制（5次/秒）
502Bad 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文档