PacteryDevelopers

5분 만에 첫 서명 요청 보내기

테스트 키 하나면 5분 안에 첫 서명 요청을 보낼 수 있습니다.

AI·자동화는 한 번에 요청

문서 생성, 받는 분 서명란 배치, 서명자 지정, 이메일 발송을 한 번의 요청으로 처리할 수 있습니다.

curl https://api.pactery.com/v1/signature_requests \
  -H "Authorization: Bearer sk_test_..." \
  -H "Idempotency-Key: agent-task-20260901-001" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "합의서",
    "content": "<p><strong>합의서</strong></p><p>합의 내용을 적습니다.</p>",
    "content_format": "html",
    "recipient": { "email": "ksk@yeyul.com", "name": "김서명" }
  }'

sk_test_ 키는 문서와 서명 링크를 만들지만 실제 이메일은 보내지 않습니다. sk_live_ 키만 이메일을 발송합니다. 이 엔드포인트에서는 Idempotency-Key가 필수이며, 같은 키와 같은 내용을 재시도해도 문서와 이메일이 중복 생성되지 않습니다.

본문 끝에는 받는 분 서명란이 자동으로 추가됩니다. 더 세밀하게 필드와 여러 서명자를 제어할 때는 아래 단계별 API를 사용하세요.

시작 전 확인:

  • 베이스 URL은 https://api.pactery.com/v1 입니다. https://pactery.com/v1 경로도 호환됩니다.
  • API 키는 조직 관리자에게 요청하세요 — sk_test_ 는 개발용(사용량 차감·실발송 없음), sk_live_ 는 운영용입니다. 운영 키도 발송 시에는 차감되지 않고 상대방 서명 완료 시 사용량이 반영됩니다. 키는 Authorization: Bearer 헤더로 보냅니다.
  • 문서·서명자·필드 ID는 모두 UUID이고, 응답엔 object 필드가 함께 옵니다.
  • 아래 예제의 키와 문서 ID 자리만 본인 값으로 바꾸면 그대로 동작합니다.

1. 문서 생성

curl https://pactery.com/v1/documents \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "업무 위탁 계약서",
    "content": "<h1>업무 위탁 계약서</h1><p>본 계약은 ...</p>"
  }'

응답으로 doc_로 시작하는 문서 ID가 옵니다.

{ "id": "4859ccb5-1baf-41f6-...", "status": "draft", "title": "업무 위탁 계약서" }

2. 서명자 지정

curl https://pactery.com/v1/documents/4859ccb5-1baf-41f6-.../participants \
  -H "Authorization: Bearer sk_test_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "홍길동",
    "phone": "01012345678",
    "role": "signer",
    "auth": "sms_pin"
  }'

3. 발송

curl https://pactery.com/v1/documents/4859ccb5-1baf-41f6-.../send \
  -H "Authorization: Bearer sk_test_..." \
  -X POST

문서 상태가 sent로 바뀌고 서명자에게 링크가 전달됩니다.

4. 상태 확인

curl https://pactery.com/v1/documents/4859ccb5-1baf-41f6-... \
  -H "Authorization: Bearer sk_test_..."

participants[].status가 signed가 되고, 모두 끝나면 문서 status가 completed가 됩니다. 폴링 대신 웹훅을 쓰면 완료 시점에 즉시 통지받습니다.

흔한 함정

  • 발송(send) 후에는 문서 수정·서명자/필드 변경이 막힙니다(409). 모든 준비를 draft에서 끝내고 마지막에 send 하세요.
  • 필드 좌표 x/y/width/height 는 페이지 대비 0100(%) 값입니다(01 아님).
  • file 내려받기: 업로드/서명완료 PDF는 그대로, 콘텐츠(HTML) 문서는 제목+본문으로 PDF를 즉석 생성해 받습니다(한글 폰트 임베드).
  • 서명자에게 SMS가 자동 발송되는 건 phone 이 있는 경우입니다.
이전API 키와 인증다음요청·응답 형식