API 参考
工作流 API
除特别说明外，所有接口需登录会话（Cookie）。返回 JSON：{ ok: true, data } 或 { ok: false, error }。常见错误：400 校验失败、401 未登录、403 无权限、404 不存在、429 触发限流、502/503 上游异常。公开 /api/v1 接口使用 Authorization: Bearer pdflean_… 鉴权，且须发送 JSON 内容类型。
工作流
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/workflows | 列出工作流 |
| POST | /api/workflows | 创建工作流（草稿） |
| GET | /api/workflows/:id | 获取工作流 |
| PUT | /api/workflows/:id | 更新工作流（草稿，版本 +1） |
| DELETE | /api/workflows/:id | 删除工作流 |
| POST | /api/workflows/:id/publish | 发布版本 |
| GET | /api/workflows/:id/versions | 版本列表 |
| POST | /api/workflows/:id/versions/:version/restore | 回滚到版本 |
触发器与 Hook
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/workflows/triggers | 触发器列表 |
| POST | /api/workflows/triggers | 创建触发器（webhook/定时/邮件/云盘） |
| POST | /api/workflows/triggers/:id/run | 立即运行触发器 |
| DELETE | /api/workflows/triggers/:id | 删除触发器 |
| POST | /api/workflows/hook/:token | 入站 Webhook（令牌鉴权，无需会话；JSON 请求体） |
运行与复核
| 方法 | 路径 | 说明 |
|---|---|---|
| POST | /api/workflows/runs | 创建一次运行（入队执行） |
| GET | /api/workflows/runs | 运行列表 |
| GET | /api/workflows/runs/:id | 运行详情与步骤 |
| POST | /api/workflows/runs/:id/retry | 重试失败/排队的运行 |
| GET | /api/workflows/reviews | 待人工复核列表 |
| POST | /api/workflows/reviews/:id | 批准/驳回复核 |
云端桥接
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/workflows/cloud/status | 独立 VPS 桥接状态 |
| POST | /api/workflows/cloud/convert | Office → PDF（独立 VPS，LibreOffice） |
| POST | /api/workflows/cloud/ocr | OCR（独立 VPS，Tesseract） |
| POST | /api/workflows/cloud/extract | 从 PDF 抽取发票/通用字段（pdfjs + 规则） |
归档与保留
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/workflows/archive | 归档列表与哈希链完整性 |
| POST | /api/workflows/archive | 归档文件（base64，SHA-256 哈希链） |
| GET | /api/workflows/archive/:id/verify | 校验归档哈希链 |
| GET | /api/workflows/archive/export | 导出归档审计 CSV（含墓碑记录） |
| POST | /api/workflows/archive/:id/hold | 设置/解除法务保留 |
| POST | /api/workflows/archive/:id/compliance | 开启不可逆的 WORM 合规锁定 |
| DELETE | /api/workflows/archive/:id | 删除归档（法务保留中禁止） |
公开 API v1
| 方法 | 路径 | 说明 |
|---|---|---|
| GET | /api/v1/openapi.json | OpenAPI 3.1 规范（公开，无需鉴权） |
| GET | /api/v1/me | 当前 API Key 所属用户（Bearer 密钥） |
| GET | /api/v1/usage | 用量看板：余额、近 30 天聚合、最近调用 |
| GET | /api/v1/workflows | 工作流列表（scope workflow.read） |
| GET | /api/v1/workflows/:id | 获取工作流（scope workflow.read） |
| POST | /api/v1/workflows/:id/run | 排队运行（scope workflow.run） |
| GET | /api/v1/runs | 运行列表（scope workflow.read） |
| POST | /api/v1/pdf/merge | 合并 PDF（scope pdf.merge；2–10 个 base64 文件） |
| POST | /api/v1/pdf/split | 保留指定页（scope pdf.split；ranges 如 "1-3,5"） |
| POST | /api/v1/pdf/compress | 结构压缩 PDF（scope pdf.compress） |
| GET | /api/v1/jobs/:id | 任务状态（免费） |
| GET | /api/v1/jobs/:id/download | 下载任务结果（免费） |
| POST | /api/v1/convert/office | Office/ODF 文档互转（scope pdf.convert） |
| POST | /api/v1/convert/linearize | PDF 线性化，加速网页预览（scope pdf.convert） |
| POST | /api/v1/convert/typst | Typst/Markdown 源码编译为 PDF（scope pdf.convert） |
| POST | /api/v1/ocr | 扫描件 OCR 成可搜索 PDF（scope pdf.ocr） |
| POST | /api/v1/ocr/text | 单张图片 OCR 成文本（scope pdf.ocr） |
| POST | /api/v1/validate/pdfa | PDF/A 合规校验（scope pdf.validate） |
| POST | /api/v1/validate/pdfua | PDF/UA 无障碍校验（scope pdf.validate） |
| POST | /api/v1/validate/signature | 数字签名验证报告（scope pdf.validate） |
| POST | /api/v1/sign | PAdES 数字签名（scope pdf.sign；可自带 PEM 密钥对） |
| POST | /api/v1/redact | 真涂黑脱敏：按文本或区域删除（scope pdf.redact） |
| POST | /api/v1/extract | 文本与规则化字段提取（scope pdf.extract） |
| POST | /api/v1/docling | Docling 结构化版面解析（scope pdf.extract；异步：返回任务后轮询 /jobs/{id}，结果文本经 /jobs/{id}/download 下载） |
| POST | /api/v1/scan/pii | 文本个人信息扫描（scope pii.detect） |
额度消耗
每月获赠额度随订阅计费周期刷新（不结转），先用赠送后扣充值，额度单价 $0.001（后台可配）。
| Method | Endpoint | 额度 |
|---|---|---|
| GET | /jobs/:id | 0 /次 |
| GET | /jobs/:id/download | 0 /次 |
| GET | /me | 0 /次 |
| GET | /runs | 0 /次 |
| GET | /usage | 0 /次 |
| GET | /workflows | 0 /次 |
| GET | /workflows/:id | 0 /次 |
| POST | /ai/chat | 3 /次 |
| POST | /ai/extract | 5 /次 |
| POST | /ai/pii-detect | 4 /次 |
| POST | /ai/summarize | 3 /次 |
| POST | /ai/translate | 3 /次 |
| POST | /convert/linearize | 1 /次 |
| POST | /convert/office | 2 /次 |
| POST | /convert/typst | 1 /次 |
| POST | /docling | 3 /次 |
| POST | /extract | 2 /次 |
| POST | /ocr | 3 /页 |
| POST | /ocr/text | 1 /次 |
| POST | /pdf/compress | 1 /次 |
| POST | /pdf/merge | 1 /次 |
| POST | /pdf/split | 1 /次 |
| POST | /redact | 3 /次 |
| POST | /scan/pii | 2 /次 |
| POST | /sign | 5 /信封 |
| POST | /validate/pdfa | 2 /次 |
| POST | /validate/pdfua | 2 /次 |
| POST | /validate/signature | 2 /次 |
| POST | /workflows/:id/run | 1 /次 |
| ai.chat | 2 /次 | |
| convert.html_to_pdf | 4 /页 | |
| convert.office_to_pdf | 10 /页 | |
| convert.pdf_to_office | 12 /页 | |
| convert.pdfa | 8 /页 | |
| esign.envelope | 750 /信封 | |
| pdf.ocr | 3 /页 | |
| pdf.ocr.high | 8 /页 |