완료된 서명 문서 API 다운로드 방법 | Pactery 가이드
완료된 서명 문서는 GET /documents/{id}로 상태를 확인한 뒤, GET /documents/{id}/file로 PDF를 내려받습니다. 현재 API 문서 기준 베이스 URL은 https://pactery.com/v1입니다.
다운로드 API는 문서가 업로드 PDF나 서명 완료 PDF를 가지고 있으면 해당 파일을 내려주고, 콘텐츠 기반 문서라면 저장된 본문 또는 최신 리비전 기준으로 PDF를 생성해 반환합니다. 응답은 JSON이 아니라 application/pdf 파일입니다.
1. 완료 상태 확인
먼저 문서 상태를 확인합니다. 공개 API 응답의 상태는 draft, sent, completed, canceled 중 하나로 다룹니다. 파일 다운로드 자체는 문서에 접근 권한이 있으면 가능하지만, 자동 보관이나 외부 시스템 저장은 보통 completed 상태를 확인한 뒤 실행하는 편이 안전합니다.
curl https://pactery.com/v1/documents/4859ccb5-1baf-41f6-9f2d-... \
-H "Authorization: Bearer $PACTERY_API_KEY"
응답에서 status가 completed인지 확인하고, 필요하면 completed_at도 함께 저장하세요. 발송 직후에는 아직 sent일 수 있으므로 주기적으로 조회하거나 웹훅 이벤트와 함께 처리하는 방식이 좋습니다.
2. PDF 다운로드
PDF는 GET /documents/{id}/file로 내려받습니다. 브라우저에서 보는 링크가 아니라 서버 간 호출로 파일을 저장하는 경우, 응답을 텍스트가 아닌 바이너리로 처리해야 합니다.
curl https://pactery.com/v1/documents/4859ccb5-1baf-41f6-9f2d-.../file \
-H "Authorization: Bearer $PACTERY_API_KEY" \
--output signed-document.pdf
Node.js에서는 arrayBuffer()로 받은 뒤 파일이나 스토리지에 저장할 수 있습니다.
import { writeFile } from 'node:fs/promises'
const API = 'https://pactery.com/v1'
const documentId = '4859ccb5-1baf-41f6-9f2d-...'
const statusRes = await fetch(`${API}/documents/${documentId}`, {
headers: { Authorization: `Bearer ${process.env.PACTERY_API_KEY}` },
})
const doc = await statusRes.json()
if (doc.status !== 'completed') {
throw new Error(`아직 완료된 문서가 아닙니다: ${doc.status}`)
}
const fileRes = await fetch(`${API}/documents/${documentId}/file`, {
headers: { Authorization: `Bearer ${process.env.PACTERY_API_KEY}` },
})
if (!fileRes.ok) {
throw new Error(`PDF 다운로드 실패: ${fileRes.status}`)
}
const bytes = Buffer.from(await fileRes.arrayBuffer())
await writeFile('signed-document.pdf', bytes)
3. 보관할 때 주의할 점
외부 시스템에 저장할 때는 문서 ID, 완료 시각, 파일 저장 위치를 함께 남겨두면 나중에 다시 찾기 쉽습니다. 다운로드 실패가 일시적인 네트워크 문제인지, 문서 권한이나 삭제 상태 때문인지 구분할 수 있도록 상태 조회 결과와 오류 응답도 로그에 남겨두세요.
감사추적이 필요한 경우에는 GET /documents/{id}/audit로 서명 과정의 이벤트를 별도로 조회할 수 있습니다. PDF 파일과 감사 이벤트를 함께 보관하면 내부 검토나 고객 문의 대응에 더 안정적입니다.