Macaaw PDF API
압축, 변환, 서명을 위한 PDF API
22개 PDF 도구와 전자 서명을 위한 하나의 REST API. 모든 작업은 런던의 서버에서 실행되며 파일은 2시간 이내에 삭제돼요.
- OpenAPI 3.1
- Postman 컬렉션
- 무료 샌드박스
- 서명된 웹훅
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로 문서를 만들고, 텍스트 태그로 필드를 배치하고, 보낸 뒤 서명된 사본을 다운로드하세요.
제품에 서명 기능 임베드
허용한 출처로 제한해 사이트 안에서 서명 세션을 여세요.
웹훅으로 일괄 실행
수백 개의 작업을 시작하고, 각 작업이 끝날 때마다 서명된 콜백을 받으세요.
범위가 지정된 키와 일괄 처리
범위와 교체를 지원하는 키, 일괄 작업, 실시간 진행 상황, 페이지 렌더링.
임베디드 편집기
PDF 편집기나 이미지 편집기를 임베디드 서명과 함께 내 앱 안에 넣으세요.
작동 방식
키에서 결과까지 호출 네 번
키 만들기
계정에서 샌드박스 키를 만드세요. 준비되면 라이브 키로 전환하세요.
계정 › 개발자작업 시작
멀티파트 요청 하나로 파일과 도구를 보내세요.
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}상태: queued, processing, completed, failed - GET
/tasks/{id}/download결과 파일 또는 ZIP - DELETE
/tasks/{id}지금 파일 삭제
문서 · 전자 서명
- POST
/documentsPDF와 받는 사람 및 필드, 또는 텍스트 태그 - POST
/documents/{id}/send이메일로 보내거나, 임베디드 서명용으로 조용히 보내기 - GET
/documents/{id}/details받는 사람, 필드, 전체 타임라인 - POST
/documents/{id}/session자체 페이지용 서명 링크 - GET
/documents/{id}/download인증서가 포함된 서명된 PDF
웹훅
- POST
/webhook-subscriptionstask_completed나 document_state_changed 같은 트리거 선택 - GET
/webhook-events전송 내역 및 재전송
보안
첫날부터 프로덕션용으로 설계
웹사이트와 같은 삭제 규칙과 영국 내 처리에, 엔지니어링 팀이 기대하는 제어 기능까지.
- 직접 관리하는 키라이브 및 샌드박스 키는 한 번만 표시되고 해시로 저장돼요. 계정에서 언제든 키를 폐기할 수 있어요.
- 서명된 웹훅각 전송에는 공유 키로 만든 본문의 HMAC-SHA256 값이 ?signature=로 포함돼요.
- 빠른 파일 삭제작업 파일은 무료 계정에서 1시간, Pro와 비즈니스에서 2시간 보관된 후 삭제돼요. DELETE를 쓰면 즉시 삭제돼요.
- 영국 내 처리모든 작업은 런던의 서버에서 실행돼요. 요청 로그에는 파일 내용이나 파일 이름이 저장되지 않아요.
- 공정한 속도 제한사용자당 분당 새 작업 120개, 모든 429 응답에 Retry-After 포함.
- 안전한 재시도Idempotency-Key를 보내면 반복된 요청은 24시간 동안 첫 결과를 반환해요.
질문
개발자 FAQ
API를 무료로 써 볼 방법이 있나요?
네. 로그인한 사용자는 누구나 샌드박스 키를 무료로 만들 수 있어요. 샌드박스 호출은 분당 10, 작업당 5페이지로 제한되고, 모든 출력에 “Sandbox”가 찍히며, 테스트 데이터는 7일 후 삭제돼요.
어떤 도구를 호출할 수 있나요?
압축과 OCR부터 Office 변환과 PDF/A까지 서버에서 실행되는 22개 도구와 전자 서명이에요. GET /tools에서 옵션과 함께 목록을 볼 수 있어요. 33개 브라우저 도구는 사용자의 브라우저에서 실행되므로 API v1에 포함되지 않아요.
API 사용 요금은 어떻게 부과되나요?
라이브 키는 Pro와 비즈니스에 포함돼요. 호출은 웹사이트와 같은 월간 사용량을 쓰며, 이를 넘으면 크레딧이 적용돼요. 크레딧 팩은 500크레딧에 £5부터이며 12개월 동안 유효해요.
SDK가 있나요?
문서에는 모든 엔드포인트에 대한 curl, Node, Python 복사·붙여넣기 예제와 OpenAPI 3.1 파일, Postman 컬렉션이 있어 어떤 언어로든 클라이언트를 생성할 수 있어요.
웹훅 엔드포인트가 다운되면 어떻게 되나요?
1분, 10분, 1시간 후 세 번 더 재시도한 뒤 전송 실패로 표시해요. 계정이나 API에서 다시 보낼 수 있어요.