API로 서명 요청을 생성하는 코드 예시 | Pactery 가이드
API로 서명 요청을 만들 때는 보통 한 번의 요청으로 끝내지 않고, 문서를 만든 뒤 서명자와 서명 위치를 준비하고 마지막에 발송합니다. 현재 API 문서 기준 베이스 URL은 `https://pactery.com/v1`이며, 정식 서브도메인 `https://api.pactery.com/v1`은 별도 매핑 전제로 안내됩니다.
아래 예시는 최소 흐름을 보여주기 위한 형태입니다. 실제 운영에서는 API 키를 서버 환경변수에 두고, 문서 ID와 참여자 ID를 저장해 이후 상태 조회나 재발송에 사용하세요.
## 1. 문서 생성
먼저 `POST /documents`로 문서를 만듭니다. 본문을 HTML 또는 TipTap JSON으로 넘기거나, PDF를 먼저 업로드한 뒤 받은 `file_url`을 사용할 수 있습니다.
```bash
curl https://pactery.com/v1/documents \
-H "Authorization: Bearer $PACTERY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"title": "위임계약서",
"content": "
위임인은 수임인에게 아래 업무를 위임합니다.
", "author_name": "계약 담당자" }' ``` 응답의 `id`가 이후 호출에서 쓰는 문서 ID입니다. PDF 원본을 쓰는 경우에는 `POST /files`로 PDF를 업로드하고, 반환된 URL을 문서 생성 요청의 `file_url`에 넣는 방식으로 준비합니다. ## 2. 서명자와 서명 위치 준비 문서를 만든 뒤 `POST /documents/{id}/participants` 또는 `POST /documents/{id}/participants/batch`로 서명자를 추가합니다. 여러 명이 순서대로 서명해야 한다면 `signing_order`를 함께 관리하는 편이 좋습니다. ```bash curl https://pactery.com/v1/documents/4859ccb5-1baf-41f6-9f2d-.../participants \ -H "Authorization: Bearer $PACTERY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "홍길동", "email": "hong@example.com", "phone": "01012345678", "role": "signer", "signing_order": 1 }' ``` PDF의 특정 위치에 서명을 받아야 한다면 `PUT /documents/{id}/fields`로 필드를 지정합니다. 좌표는 문서 페이지 안에서 0~100 비율 기준으로 다루는 구조라, 실제 화면에서 위치를 확인한 뒤 저장하는 방식이 가장 안전합니다. ## 3. 발송 준비가 끝나면 `POST /documents/{id}/send`를 호출합니다. 발송 후에는 문서 상태가 `sent`가 되고, 응답에 서명 링크가 포함됩니다. 발송된 문서는 중간에 서명자나 필드를 바꾸기보다, 필요한 경우 취소 후 새 요청으로 정리하는 것이 안전합니다. ```bash curl https://pactery.com/v1/documents/4859ccb5-1baf-41f6-9f2d-.../send \ -X POST \ -H "Authorization: Bearer $PACTERY_API_KEY" \ -H "Content-Type: application/json" \ -d '{}' ``` ## Node.js에서 호출할 때 서버 코드에서는 공통 호출 함수를 하나 두면 오류 처리가 쉬워집니다. ```js const API = 'https://pactery.com/v1' async function pactery(path, options = {}) { const res = await fetch(`${API}${path}`, { ...options, headers: { Authorization: `Bearer ${process.env.PACTERY_API_KEY}`, 'Content-Type': 'application/json', ...(options.headers || {}), }, }) if (!res.ok) { const text = await res.text() throw new Error(`Pactery API ${res.status}: ${text}`) } return res.json() } const doc = await pactery('/documents', { method: 'POST', body: JSON.stringify({ title: '위임계약서', content: '위임 내용을 입력합니다.
', }), }) await pactery(`/documents/${doc.id}/participants`, { method: 'POST', body: JSON.stringify({ name: '홍길동', email: 'hong@example.com', phone: '01012345678', role: 'signer', }), }) const sent = await pactery(`/documents/${doc.id}/send`, { method: 'POST', body: '{}', }) ```