Macaaw PDF API
用於壓縮、轉換和簽署的 PDF API
一套 REST API,涵蓋 22 個 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"}- 22個 PDF 工具,一個端點
- 1 次呼叫即可上傳並啟動任務
- < 2 h直到您的檔案被刪除
- £0沙盒免費
您可以構建什麼
您的產品不必自己承擔的 PDF 工作
儲存前先縮小上傳檔案
使用者上傳 PDF 的那一刻,就壓縮它們,或將其壓到確切大小。
將 Office 檔案轉換為 PDF
將 Word、Excel、PowerPoint、OpenDocument 和 HTML 轉換為 PDF,版式保持不變。
讓掃描檔可搜尋
支援 32 種語言的文字辨識、用於歸檔的 PDF/A,以及直接轉為 Excel 的表格。
從您自己的應用傳送協議
從 PDF 建立文件,用文字標籤放置欄位,傳送並下載已簽署的副本。
在您的產品中嵌入簽署
在您的網站內開啟簽署工作階段,僅限您允許的來源。
透過 Webhook 批次執行
啟動數百個任務,並在每個任務完成時收到帶簽名的回撥。
限定權限的金鑰與批次處理
具權限範圍與輪替的金鑰、批次工作、即時進度和頁面轉譯。
嵌入式編輯器
把 PDF 編輯器或圖片編輯器嵌入您自己的應用程式,與嵌入式簽署並用。
工作方式
從金鑰到結果,只需四次呼叫
建立金鑰
在帳戶中建立沙盒金鑰。準備好後再切換為正式金鑰。
帳戶 › 開發者啟動任務
在一次 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 天後刪除。
我可以呼叫哪些工具?
在我們伺服器上執行的 22 個工具,從壓縮和 OCR 到 Office 轉換和 PDF/A,再加上電子簽名。GET /tools 會列出它們及其選項。33 個瀏覽器工具在您的使用者的瀏覽器中執行,因此不在 API v1 中。
API 用量如何計費?
正式金鑰隨 Pro 和商務版提供。呼叫使用與網站相同的每月額度;超出部分使用點數。點數包 £5 起,含 500 點,有效期 12 個月。
你們有 SDK 嗎?
文件為每個端點提供了可直接複製貼上的 curl、Node 和 Python 示例,另有 OpenAPI 3.1 檔案和 Postman 集合,您可以用任何語言產生客戶端。
如果我的 Webhook 端點宕機會怎樣?
我們會再重試三次,分別在 1 分鐘、10 分鐘和 1 小時之後,然後將該次投遞標記為失敗。您可以在帳戶中或透過 API 重新傳送。