Macaaw PDF API
用于压缩、转换和签署的 PDF API
一套 REST API,涵盖 20 个 PDF 工具和电子签名。每个任务都在我们位于伦敦的服务器上运行,文件在 2 小时内删除。
- OpenAPI 3.1
- Postman 集合
- 免费沙盒
- 带签名的 Webhook
curl https://macaaw.com/public/v1/tasks \
-H "Authorization: API-Key $MACAAW_API_KEY" \
-F "files[]=@lease.pdf" \
-F 'data={"tool":"compress-pdf","options":{"level":"recommended"}}'
# 201 Created
{ "id": "…", "tool": "compress-pdf", "status": "task.queued" }// Node 18+ (fetch, FormData and Blob are built in)
import { readFile } from "node:fs/promises";
const form = new FormData();
form.append("files[]", new Blob([await readFile("lease.pdf")]), "lease.pdf");
form.append("data", JSON.stringify({ tool: "compress-pdf", options: { level: "recommended" } }));
const res = await fetch("https://macaaw.com/public/v1/tasks", {
method: "POST",
headers: { Authorization: `API-Key ${process.env.MACAAW_API_KEY}` },
body: form,
});
const task = await res.json(); // { id, tool, status: "task.queued" }# Python 3 with requests
import json, os, requests
res = requests.post(
"https://macaaw.com/public/v1/tasks",
headers={"Authorization": f"API-Key {os.environ['MACAAW_API_KEY']}"},
files={"files[]": open("lease.pdf", "rb")},
data={"data": json.dumps({"tool": "compress-pdf", "options": {"level": "recommended"}})},
)
task = res.json() # {"id": ..., "status": "task.queued"}- 20个 PDF 工具,一个端点
- 1 次调用即可上传并启动任务
- < 2 h直到您的文件被删除
- £0沙盒免费
您可以构建什么
您的产品不必自己承担的 PDF 工作
存储前先缩小上传文件
用户上传 PDF 的那一刻,就压缩它们,或将其压到确切大小。
将 Office 文件转换为 PDF
将 Word、Excel、PowerPoint、OpenDocument 和 HTML 转换为 PDF,版式保持不变。
让扫描件可搜索
支持 27 种语言的文字识别、用于归档的 PDF/A,以及直接转为 Excel 的表格。
从您自己的应用发送协议
从 PDF 创建文档,用文本标签放置字段,发送并下载已签署的副本。
在您的产品中嵌入签署
在您的网站内开启签署会话,仅限您允许的来源。
通过 Webhook 批量运行
启动数百个任务,并在每个任务完成时收到带签名的回调。
工作方式
从密钥到结果,只需四次调用
创建密钥
在账户中创建沙盒密钥。准备好后再切换为正式密钥。
账户 › 开发者启动任务
在一次 multipart 请求中发送文件和工具。
POST /public/v1/tasks完成时收到通知
订阅 task_completed,或轮询任务。
webhook: task_completed下载
获取结果,然后删除它或等待其过期。
GET /tasks/{id}/download
端点
小巧、可预期的 API
基础 URL https://macaaw.com/public/v1 · 使用 snake_case 键名的 JSON · Authorization: API-Key …
任务 · PDF 工具
- GET
/tools所有可调用的工具及其选项 - POST
/tasks一次调用即可上传文件并启动工具 - GET
/tasks/{id}状态:排队中、处理中、已完成或失败 - GET
/tasks/{id}/download结果文件,或 ZIP 压缩包 - DELETE
/tasks/{id}立即删除文件
文档 · 电子签名
- POST
/documents一份 PDF 加收件人和字段,或文本标签 - POST
/documents/{id}/send通过邮件发送,或为嵌入式签署静默发送 - GET
/documents/{id}/details收件人、字段和完整时间线 - POST
/documents/{id}/session用于您自己页面的签署链接 - GET
/documents/{id}/download附带证书的已签署 PDF
Webhook
- POST
/webhook-subscriptions选择触发器,例如 task_completed 或 document_state_changed - GET
/webhook-events投递历史,可重新发送
安全
从第一天起就为生产环境而构建
与网站相同的删除规则和英国本地处理,外加工程团队期望的各项控制。
- 由您掌控的密钥正式密钥和沙盒密钥只显示一次,并以哈希形式存储。可在账户中撤销任何密钥。
- 带签名的 Webhook每次投递都带有 ?signature=,即使用您的共享密钥对请求正文生成的 HMAC-SHA256。
- 文件快速删除任务文件在免费账户上保留 1 小时,在 Pro 和商务版上保留 2 小时,之后即消失。DELETE 会立即删除它们。
- 英国本地处理每个任务都在我们位于伦敦的服务器上运行。请求日志绝不存储文件内容或文件名。
- 合理的速率限制每位用户每分钟 120 个新任务,每个 429 响应都带有 Retry-After。
- 安全重试发送 Idempotency-Key 后,24 小时内重复的请求会返回第一次的结果。
常见问题
开发者常问
有免费试用 API 的方式吗?
有。任何已登录的用户都可以免费创建沙盒密钥。沙盒调用限制为每分钟 10 次、每个任务 5 页,所有输出都会加盖“Sandbox”标记,测试数据在 7 天后删除。
我可以调用哪些工具?
在我们服务器上运行的 20 个工具,从压缩和 OCR 到 Office 转换和 PDF/A,再加上电子签名。GET /tools 会列出它们及其选项。20 个浏览器工具在您的用户的浏览器中运行,因此不在 API v1 中。
API 用量如何计费?
正式密钥随 Pro 和商务版提供。调用使用与网站相同的每月额度;超出部分使用点数。点数包 £5 起,含 500 点,有效期 12 个月。
你们有 SDK 吗?
文档为每个端点提供了可直接复制粘贴的 curl、Node 和 Python 示例,另有 OpenAPI 3.1 文件和 Postman 集合,您可以用任何语言生成客户端。
如果我的 Webhook 端点宕机会怎样?
我们会再重试三次,分别在 1 分钟、10 分钟和 1 小时之后,然后将该次投递标记为失败。您可以在账户中或通过 API 重新发送。