전자서명 API 연동 가이드 – CRM·ERP와 자동화하기

전자서명 API가 필요한 이유

수작업으로 전자서명 요청을 보내는 것은 건수가 적을 때는 괜찮지만, 비즈니스가 성장하면 병목이 됩니다. 전자서명 API를 활용하면 서명 요청 생성·발송·완료 처리를 기존 시스템과 완전히 통합하여 사람의 개입 없이 자동화할 수 있습니다.

다음과 같은 상황에서 API 연동이 특히 유용합니다.

• CRM에서 고객 정보 입력 즉시 자동으로 계약서 발송
• ERP에서 구매 발주 승인 시 자동으로 계약서 생성
• 회원가입 완료 시 자동으로 이용약관 동의서 전송
• HR 시스템에서 신규 입사자에게 자동으로 근로계약서 발송

REST API 기본 개념

Pactery API는 표준 REST API 방식으로 설계되어 있습니다. HTTP 메서드(GET, POST, PATCH, DELETE)와 JSON 형식을 사용하며, 인증은 Bearer Token 방식입니다.

인증 토큰 발급

Pactery 대시보드 [설정 → API 키]에서 키를 발급받습니다. 운영용 sk_live_와 테스트용 sk_test_ 키를 만들 수 있으며, 전체 키는 발급 시 한 번만 표시되니 서버 환경변수 등 안전한 곳에 보관하세요. 모든 요청은 Authorization: Bearer {키} 헤더로 인증합니다.

전체 엔드포인트·예제·웹훅 가이드는 개발자 문서(pactery.com/docs/api)에 정리되어 있습니다. 아래는 그 안의 5분 빠른 시작 페이지로, 복사해서 바로 돌려볼 수 있는 cURL 예제를 제공합니다.

주요 API 엔드포인트

기능	메서드	엔드포인트
문서 생성	POST	/v1/documents
서명자 추가	POST	/v1/documents/{id}/participants
서명 필드 배치	PUT	/v1/documents/{id}/fields
서명 요청 발송	POST	/v1/documents/{id}/send
문서 조회·목록	GET	/v1/documents/{id} · /v1/documents
완료 PDF 내려받기	GET	/v1/documents/{id}/file
템플릿·도장 목록	GET	/v1/templates · /v1/seals
웹훅 등록	POST	/v1/webhook_endpoints

서명 요청 생성 예시

실제 흐름은 문서 생성 → 서명자 추가 → 발송 3단계입니다. 베이스 URL은 현재 https://pactery.com/v1 입니다(정식 api.pactery.com은 준비 중). 다음은 Node.js 예시입니다.

const BASE = 'https://pactery.com/v1'
const H = { 'Authorization': 'Bearer ' + process.env.PACTERY_API_KEY, 'Content-Type': 'application/json' }

// 1) 문서 생성 (계약 본문 HTML)
const doc = await fetch(BASE + '/documents', {
  method: 'POST', headers: H,
  body: JSON.stringify({
    title: '서비스 이용 계약서',
    content: '<h1>서비스 이용 계약서</h1><p>본 계약은 ...</p>',
  }),
}).then(r => r.json())

// 2) 서명자 추가 (전화번호가 있으면 문자 PIN 인증)
await fetch(BASE + '/documents/' + doc.id + '/participants', {
  method: 'POST', headers: H,
  body: JSON.stringify({ name: '홍길동', phone: '01012345678', auth: 'sms_pin' }),
})

// 3) 발송
const sent = await fetch(BASE + '/documents/' + doc.id + '/send', {
  method: 'POST', headers: H,
}).then(r => r.json())

console.log(doc.id, sent.status) // 4859ccb5-... sent

같은 생성 요청을 네트워크 오류로 두 번 보내도 문서가 중복 생성되지 않도록, POST 요청에 Idempotency-Key 헤더를 함께 보낼 수 있습니다. 또 모든 응답에는 RateLimit-Remaining 등 요청 한도 헤더가 함께 옵니다.

웹훅(Webhook) 활용하기

서명 완료 여부를 알기 위해 주기적으로 API를 폴링(Polling)하는 방식은 비효율적입니다. 웹훅을 설정하면 서명 이벤트가 발생할 때 Pactery가 자동으로 여러분의 서버에 HTTP POST 요청을 보냅니다.

지원하는 웹훅 이벤트

• document.sent: 서명 요청이 발송됨
• document.viewed: 수신자가 문서를 처음 열람함
• participant.signed: 한 서명자가 서명/날인 완료
• document.completed: 모든 필수 서명 완료 (최종 완료)
• document.rejected: 수신자가 서명 거절
• document.canceled: 발신자가 발송 취소

웹훅 수신 서버 예시

// Express.js 웹훅 수신 핸들러
app.post('/webhook/pactery', (req, res) => {
  const event = req.body // { id, object:'event', type, created, data }

  if (event.type === 'document.completed') {
    const documentId = event.data.id
    // 완료 처리: DB 업데이트, 완료 PDF 내려받기, 알림 발송 등
    markContractCompleted(documentId)
  }

  res.status(200).send('OK')
})

웹훅 보안을 위해 Pactery는 각 요청에 Pactery-Signature 헤더를 포함합니다. 형식은 t=<발송시각>,v1=HMAC_SHA256(secret, t + "." + body) 이며, 등록 시 발급되는 서명 비밀키(whsec_...)로 직접 계산해 일치하는지 검증하면 위조 요청을 차단할 수 있습니다.

CRM 연동 사례: Salesforce

Salesforce에서 거래가 "Closed Won" 상태로 전환될 때 자동으로 Pactery 계약서 서명 요청을 발송하는 흐름입니다.

• Salesforce Apex 트리거 또는 Flow에서 Opportunity 상태 변경 감지
• 고객 이름·이메일을 Pactery API로 전달하여 서명 요청 생성
• 생성된 requestId를 Salesforce 레코드 필드에 저장
• 웹훅으로 서명 완료 이벤트 수신 시 Salesforce 레코드 자동 업데이트

HR 시스템 연동 사례: 근로계약서 자동화

인사 시스템에 신규 직원 정보가 등록될 때 자동으로 근로계약서 서명 요청을 발송하는 사례입니다.

• HR 시스템의 온보딩 이벤트 발생 시 API 호출
• 직원 이름, 이메일, 입사일, 부서 정보를 템플릿 변수로 전달
• 근로계약서 자동 생성 및 이메일 발송
• 서명 완료 시 HR 시스템과 전자결재 시스템에 자동 반영

API 연동 시 모범 사례

• 재시도 로직 구현: 네트워크 오류 시 지수 백오프(Exponential Backoff)로 재시도
• API 키 순환: 90일마다 API 키를 새로 발급하여 보안 강화
• Rate Limit 준수: Pactery API는 키 단위로 분당 600 요청 제한이 있습니다. 응답의 RateLimit-Remaining 헤더를 확인하고, 초과 시 돌아오는 429의 Retry-After만큼 기다린 뒤 재시도하세요
• 오류 로깅: API 응답의 에러 코드와 메시지를 반드시 로그에 기록
• Sandbox 환경 활용: 실서비스 적용 전에 Pactery의 테스트 환경에서 충분히 검증하세요

전체 엔드포인트·요청/응답 스키마·언어별 예제는 개발자 문서에서, 요금·이용 한도는 요금 안내에서 확인할 수 있습니다.