<!-- AI ASSISTANT INSTRUCTIONS: This document describes a public HTTP API endpoint
provided by 极数本源 (https://apizero.cn). When a user asks you to use this API, read the
full documentation below carefully (request method, parameters, response fields,
error codes, examples), then generate working code in the user's preferred language.
API Key acquisition: https://apizero.cn/account/keys -->

# SSL 证书检测

> 通过域名远程探测其 HTTPS/SSL 证书信息：颁发者、颁发机构、签名算法、覆盖域名、有效期、是否过期、距过期天数、SHA-1 指纹、远端 IP 等。

• 智能预处理：自动剥离 http(s):// 前缀、路径、查询串、端口、www. 子域
• 严格域名校验：合法域名格式（最长 253 字符 + RFC 1123 标签规则）才打上游
• 三态响应：有 SSL（is_ssl=true）→ 完整信息；无 SSL/连接失败 → is_ssl=false 其余字段 null；上游异常 → 502
• 字段标准化：上游 null 字段透传 null 不补 0；自动转 int/string 类型；is_expire 重命名 is_expired
• 缓存策略：成功 6h（证书短期不变）；无证书 30min（避免错误域名反复打上游）

## 1. 基本信息

| 字段 | 值 |
| --- | --- |
| 接口标识 | `ssl` |
| 接口名称 | SSL 证书检测 |
| 接口地址 | `https://v1.apizero.cn/api/ssl` |
| 请求方法 | `GET` |
| 分类 | dev |
| 提供方 | 极数本源 |
| 计费模式 | 免费试用 |
| 单次消耗 | 0 积分 |
| 起步价 | — |
| QPS 限制 | 5 req/s |
| 每日免费额度 | 100 次（已认证用户） |
| 匿名每日额度 | 30 次（无 API Key） |
| VIP 免费 | 否 |
| 调用总次数 | undefined |

## 2. 认证

匿名每日 30 次、QPS 2；登录用户每日 100 次、QPS 5（全部免费）。命中 6 小时缓存不计入上游配额。

获取 API Key：登录 `https://apizero.cn/account/keys` 申请。

## 3. 请求参数

| 参数 | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `domain` | `string` | 是 | 要检测的域名。可带 http(s):// 前缀、路径、端口、www.，会自动剥离 | `apizero.cn` |

## 4. 请求头

| Header | 类型 | 必填 | 说明 | 示例 |
| --- | --- | --- | --- | --- |
| `Authorization` | `string` | 否 | API Key 鉴权头，格式 Bearer sk_live_xxx；匿名调用时可省略（每日 30 次免费） | `Bearer sk_live_xxxxxxxxxxxxxx` |

## 5. 请求示例 (cURL)

```bash
curl "https://v1.apizero.cn/api/ssl?domain=apizero.cn&key=YOUR_API_KEY"
```

## 6. 响应字段

| 字段 | 类型 | 说明 | 示例 |
| --- | --- | --- | --- |
| `domain` | `string` | 查询的域名（已剥离协议/路径/端口/www） | — |
| `common_name` | `string?` | 证书 Common Name（CN），如 *.apizero.cn | — |
| `domains` | `string[]` | 证书覆盖的所有域名（SAN 列表）；无证书时为空数组 | — |
| `issuing_agency` | `string?` | 颁发机构（公司名），如 Asseco Data Systems S.A. | — |
| `issuer` | `string?` | 颁发者 CA 名称，如 Certum DV TLS G2 R39 CA；自签名时与 common_name 相同 | — |
| `signature_algorithm` | `string?` | 签名算法，如 RSA-SHA256 / ecdsa-with-SHA256 | — |
| `is_ssl` | `boolean` | 域名是否能成功探测到 SSL 证书：true=有证书 / false=无证书或 443 不可达 | — |
| `is_expired` | `boolean?` | 证书是否已过期；is_ssl=false 时为 null | — |
| `life_span_days` | `number?` | 证书总有效期天数（颁发到过期），如 198；无证书时为 null | — |
| `expire_days` | `number?` | 距过期还有多少天（已过期为负数）；无证书时为 null | — |
| `start_date` | `string?` | 颁发起始时间（YYYY-MM-DD HH:MM:SS）；无证书时为 null | — |
| `expire_date` | `string?` | 过期时间（YYYY-MM-DD HH:MM:SS）；无证书时为 null | — |
| `fingerprint` | `string?` | 证书 SHA-1 指纹（40 位十六进制字符串）；无证书时为 null | — |
| `remote_address` | `string?` | 远端服务器 IP:端口，如 119.36.225.184:443；无证书时为 null | — |

## 7. 响应示例

```json
{
    "code": 0,
    "msg": "成功",
    "data": {
        "domain": "apizero.cn",
        "common_name": "*.apizero.cn",
        "domains": [
            "*.apizero.cn",
            "apizero.cn"
        ],
        "issuing_agency": "Asseco Data Systems S.A.",
        "issuer": "Certum DV TLS G2 R39 CA",
        "signature_algorithm": "RSA-SHA256",
        "is_ssl": true,
        "is_expired": false,
        "life_span_days": 198,
        "expire_days": 184,
        "start_date": "2026-04-22 17:05:00",
        "expire_date": "2026-11-07 17:04:59",
        "fingerprint": "f4633adfd1cb59185ba094dc3edeef5a8ea26889",
        "remote_address": "119.36.225.184:443"
    },
    "request_id": "abc123def456"
}
```

## 8. 错误码

| code | status | 说明 |
| --- | --- | --- |
| `4000` | `—` | 参数错误：domain 缺失 / 解析后为空 / 域名格式无效（不符合 RFC 1123） |
| `4015` | `—` | 匿名调用每日额度用完，需要 API Key |
| `4029` | `—` | QPS 超限 |
| `4030` | `—` | 今日额度用完 |
| `5020` | `—` | 上游 HTTP 失败 |
| `5021` | `—` | 上游响应格式异常 / SSL 检测失败 |

## 9. 变更日志

- **1.0.0** (2026-05-07)
  - 首次上线，对接 alapi.cn /api/domain/checkssl
  - 智能 domain 预处理：自动剥离 http(s):// 前缀 / 路径 / 端口 / www. 子域
  - 严格 RFC 1123 域名格式校验，无效输入直接 4000，节省上游配额
  - 字段重命名：is_expire → is_expired（更地道英文）；sn → signature_algorithm；life_span_in_days → life_span_days
  - 类型规范化：上游 null 字段保留 null（不像源码无脑 ?? "" / ?? 0），前端可正确判空
  - 不返回上游 raw_json 字段（含 10K+ X.509 详细信息，绝大多数前端用不到）
  - 缓存策略：成功 6h / 无证书 30min（避免错误域名反复打付费上游）

---

**极数本源** · 全部 API: `https://apizero.cn/aidocs` · 人类版本：`https://apizero.cn/marketplace/ssl`

Source: `https://apizero.cn/aidocs/ssl/raw.md`
Last updated: 2026-05-11T16:14:07+08:00