Metadata-Version: 2.4
Name: fastssl
Version: 0.2.0
Summary: FastSSL - 信SSL (xinssl.com) 开放 API SDK，支持申请、验证、获取 SSL 证书
Author: FastSSL Team
Author-email: 15001904@qq.com
License-Expression: MIT
Project-URL: Homepage, https://xinssl.com
Project-URL: Documentation, https://xinssl.apifox.cn
Project-URL: Repository, https://github.com/xiaroustar/fastssl
Keywords: ssl,certificate,ssl-certificate,xinssl,letsencrypt,zerossl,google
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.31.0

# FastSSL

FastSSL 是一个用于管理 SSL 证书的 Python SDK，对接 **信SSL (xinssl.com)** 开放 API，支持申请、验证、获取、查询、取消、删除 SSL 证书。

签发密钥获取渠道：[xinssl.com](https://xinssl.com)（控制台「API 密钥」中创建 SecretKey）

完整交互式文档：[xinssl.apifox.cn](https://xinssl.apifox.cn)

开发者：沈阳明心科技有限公司

## 联系方式
EMail：15001904@qq.com

## 安装

```bash
pip install fastssl
```

## 鉴权

调用时在请求头携带 SecretKey，SDK 已自动处理，初始化时传入即可：

```python
from fastssl import FastSSLClient

client = FastSSLClient(api_key="你的 SecretKey")
```

## 快速开始

```python
from fastssl import FastSSLClient

client = FastSSLClient(api_key="xssl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx")
domain = "example.com"

# 1. 查看可用品牌 / 验证方式 / 固定天数
meta = client.get_meta()

# 2. 申请证书（创建订单）
order = client.create_certificate(
    certificate_domain=domain,
    channel_type="letsencrypt",   # letsencrypt / google / zerossl
    validation_method="dns",      # dns / file
    days=90,
)
order_id = order["data"]["order_id"]

# 3. 获取验证值（DNS TXT 记录 或 文件验证信息）
challenge = client.get_challenge(order_id)

# >>> 去配置 DNS TXT 记录或上传验证文件 <<<

# 4. 触发验证
verify = client.verify_certificate(order_id)

# 5. 验证通过后获取证书
if verify["data"]["verified"]:
    cert = client.get_certificate(order_id)
    print(cert["data"]["certificate"])
    # 或下载 ZIP：client.download_certificate(order_id, f"{domain}.zip")
```

## 一键申请并轮询验证

```python
result = client.create_and_verify(
    certificate_domain=domain,
    channel_type="letsencrypt",
    validation_method="dns",
    max_retries=10,        # 最多重试 10 次
    retry_interval=5,      # 每次间隔 5 秒
)
print(result["success"], result["order_id"])
```

## API 文档

### `FastSSLClient(api_key, base_url=None)`

初始化客户端。`base_url` 可选，默认 `https://xinssl.com/api/open/v1`。

### 元信息

- `get_meta()` — GET `/meta`：可用品牌、验证方式、固定天数

### 证书申请与验证

- `create_certificate(certificate_domain, channel_type="letsencrypt", validation_method="dns", days=90)` — POST `/ssl/orders`
  - `channel_type`：`letsencrypt` / `google` / `zerossl`
  - `validation_method`：`dns` / `file`
  - `days`：必须等于 meta 中的 `fixed_days`（当前 90）
  - 通配符域名以 `*.` 开头自动识别
- `get_challenge(order_id)` — GET `/ssl/orders/{order_id}/challenge`
- `verify_certificate(order_id)` — POST `/ssl/orders/{order_id}/verify`

### 获取 / 下载

- `get_certificate(order_id)` — GET `/ssl/orders/{order_id}/certificate`，返回 PEM / Bundle / 私钥
- `download_certificate(order_id, save_path)` — GET `/ssl/orders/{order_id}/download`，ZIP 流下载到本地

### 查询 / 取消 / 删除

- `list_orders(page=1, page_size=20)` — GET `/ssl/orders`
- `get_order(order_id)` — GET `/ssl/orders/{order_id}`
- `cancel_order(order_id)` — POST `/ssl/orders/{order_id}/cancel`（退积分）
- `delete_order(order_id)` — DELETE `/ssl/orders/{order_id}`（不退积分）

### 便捷方法

- `create_and_verify(...)` — 一键申请并轮询验证，直到 `verified=True` 或达到最大重试次数

### 返回结构

所有接口返回统一结构，并附加 `success` 字段便于判断：

```python
{"code": 0, "message": "ok", "data": {...}, "success": True}
```

`code == 0` 表示成功，非 0 表示失败。

### 状态说明

- `creating` — 创建中
- `pending_validation` — 待完成域名验证
- `issued` — 已签发
- `failed` / `expired` / `cancelled` — 失败 / 过期 / 已取消

## 许可证

MIT License

## 支持

如有问题或建议，请提交 Issue。
