Pactery API
개발자 문서
팩터리 전자서명을 코드로 연동하는 REST API 개발자 문서. 인증, 문서 생성·발송, 서명 상태 추적, 웹훅까지.
시작하기
팩터리 API의 큰 그림과 첫 연동.
핵심 개념
팩터리 전자서명의 자원 모델과 상태 흐름.
API 레퍼런스
엔드포인트별 요청·응답 명세.
웹훅
서명 이벤트를 실시간으로 받는 방법.
부록
레퍼런스 표와 예제.
팩터리 API는 전자서명 워크플로를 여러분의 서비스에 직접 심을 수 있게 해주는 REST 인터페이스입니다. 화면을 거치지 않고 코드로 문서를 만들고, 서명자를 지정하고, 발송하고, 진행 상태를 추적합니다.
AI 에이전트로 문서 작업하기
for AI 가이드와 AI용 원문을 먼저 읽으세요. API 연결이 없다면 설정 → API for AI에서 API 키를 발급하고 AI 도구의 보안 설정에 등록하도록 안내합니다. 이미 연결된 키는 다시 발급하지 않습니다.
문서 생성·조회·수정·복제·발송·취소 응답은 document_url을 반환합니다. AI는 작업 완료 후 이 주소를 클릭 가능한 바로가기로 사용자에게 전달해야 합니다. 이 주소는 로그인한 작성자·워크스페이스 권한자용이며, 수신자용 sign_url과 다릅니다. 문서 목록은 각 항목, 서명 요청은 최상위 및 document 안, 문서별 참여자·필드·감사추적·리마인더 응답은 최상위에 포함됩니다. 삭제된 문서는 null이며, PDF 파일은 Link 헤더(rel="related")로 제공합니다. 오류 응답에는 문서 링크가 없습니다.
문서 작성 요청은 초안 생성입니다. 발송을 별도로 허용하지 않았다면 서명 요청 이메일이나 문자를 보내지 않습니다.
수신자용 sign_url은 그대로 전달하세요. 실제 발송자가 확인된 라이브 발송은 https://pactery.com/s/{code} 형식의 짧은 주소를 반환하며, 서버에서 기존 서명 화면으로 이동합니다. 추천인 정보는 URL 쿼리가 아니라 내부 SignatureShareLink에 저장됩니다. 이 내부 연결은 공개 조회·수정 대상이 아니며 문서 권한을 확대하지 않습니다. 테스트 발송이나 발송자를 확인할 수 없는 기존 키는 원래 서명 주소를 사용할 수 있습니다. URL을 분해하거나 직접 조립하지 마세요. 이미 발송된 기존 주소도 계속 사용할 수 있습니다.
이 API로 할 수 있는 일
숍의 상품·협력사·주문(ShopProduct, ShopOption, ShopSupplier, ShopOrder)은 이 공개 API의 범위에 포함되지 않습니다. API 키로 협력사 주문이나 고객 연락처를 조회할 수 없습니다. 협력사 링크는 주문 한 건에 한정되며 만료·폐기할 수 있습니다.
문서 열람 권한 요청(DocumentAccessRequest)은 로그인한 계정의 문서함에서 관리하는 비공개 기능입니다. 승인받은 계정은 해당 문서의 현재 저장된 본문과 첨부 PDF를 읽을 수 있으며, 편집·발송·서명·워크스페이스 가입 또는 API 키 권한이 추가되지는 않습니다. 요청자의 이름·이메일·요청 사유와 승인 기록은 공개 API 문서 응답에 포함되지 않습니다.
받은 문서의 워크스페이스 보관(ReceivedDocumentSave)은 웹 전용 읽기 전용 기능입니다. 보관 기록은 공개 API로 노출하지 않으며, 보관만으로 문서 소유권·서명 권한이나 API 키의 조회 범위가 확대되지 않습니다.
수신자 인증 정책
문서 응답의 recipient_verification은 읽기 전용입니다. 국내 문서는 sms_pin, 해외 상대방 설정을 켠 문서는 email_otp가 기본이며 지원 국가의 sms_pin을 선택할 수 있습니다. 문서 설정에서 '서명만 받기'를 선택하면 signature_only로 표시되며, 이름·서명 이미지·동의를 받지만 휴대폰이나 이메일 본인 인증은 수행하지 않습니다. 이 설정은 /d 공유 링크의 서명 제출에 적용되며, 별도 참여자 토큰 API의 인증 정책을 변경하지 않습니다. 해외 설정은 문서 설정 화면에서 관리합니다. metadata.internationalSigning은 시스템 예약값으로 API에서 변경할 수 없습니다. 이메일 링크를 전달하는 것은 이메일 인증 완료가 아닙니다. OTP와 인증 증명 원문은 공개 API에 노출하지 않습니다.
해외 설정 문서의 /d 공유 링크에서 서버가 해외 SMS 발송 실패를 확인하면 수신자가 '인증 없이 서명만 하기'를 선택할 수 있습니다. 이 조건부 대체 경로는 기본 인증 방식이나 available_methods 목록을 바꾸지 않습니다. 서명 이미지·동의는 필수이며, 완료 기록은 signature_only(별도 본인 인증 없음)로 남고 감사기록에 해외 문자 실패 후 전환 사실을 기록합니다. 국내 문자 실패, PIN 오입력, 단순 네트워크 오류만으로 이 경로를 열 수 없습니다. English 버튼은 화면 언어만 바꾸고 발송자의 인증·요금 설정을 변경하지 않습니다.
블로그 게시글과 서명 이메일 인증 요청은 별도의 내부 데이터이며, 공개 API의 문서·참여자 ID와 혼용하지 않습니다.
- 본문(HTML)이나 PDF로 문서를 생성합니다.
- 문서 위에 서명·날인·텍스트 필드를 배치합니다.
- **서명자(수신자)**를 지정하고 본인인증(문자 PIN) 조건을 겁니다.
- 서명 요청을 발송하고, 각 서명자의 진행 상태를 실시간으로 추적합니다.
- 법인 계약을 위한 **법인 도장(날인)**을 적용합니다.
- 완료된 문서의 PDF와 감사추적 기록을 내려받습니다.
- 웹훅으로 서명·완료 이벤트를 즉시 통지받습니다.
설계 원칙
| 원칙 | 내용 |
|---|---|
| 예측 가능 | 자원 중심 URL, 표준 HTTP 메서드와 상태 코드 |
| JSON 기본 | 요청·응답 모두 application/json, UTF-8 |
| 조직 단위 | API 키는 하나의 조직(Organization)에 묶여 있고, 모든 자원은 그 조직 범위 안에서 동작 |
| 안전한 재시도 | 생성 요청은 Idempotency-Key로 중복 방지 |
기본 정보
- 베이스 URL:
https://pactery.com/v1 - 인증:
Authorization: Bearer {API_KEY} - 시간 형식: ISO 8601 (
2026-06-05T09:30:00+09:00) - 식별자: 자원별 접두사 (
doc_,par_,fld_,seal_,evt_)
이 문서의 엔드포인트는 현재 https://pactery.com/v1 에서 동작합니다. 인증·Rate Limit(RateLimit-* 헤더)·멱등성(Idempotency-Key)·웹훅까지 구현되어 있습니다.