sam-docs/features/esign

전자서명 (E-Sign)

상태: API 완전 구현 최종 갱신: 2026-02-27

---

1. 개요

PDF 문서에 대한 전자서명 계약 관리 시스템. 계약 생성 → 서명 필드 설정 → 발송 → OTP 인증 → 서명 → 완료의 전체 라이프사이클을 관리한다.

핵심 기능:

• PDF 계약서 업로드 및 서명 필드 배치
• 서명 순서 관리 (작성자 우선 / 상대방 우선)
• OTP 기반 본인인증 후 서명
• 서명 완료 시 PDF 합성 + 감사 페이지 추가
• 토큰 기반 외부 서명자 접근 (비인증)

---

2. 모델

모델	테이블	설명	Traits
EsignContract	esign_contracts	계약서 (상태, 파일, 만료일)	BelongsToTenant, Auditable, SoftDeletes
EsignSigner	esign_signers	서명자 (순서, OTP, 서명 이미지)	BelongsToTenant
EsignSignField	esign_sign_fields	서명 필드 (위치, 유형, 페이지)	BelongsToTenant
EsignAuditLog	esign_audit_logs	감사 로그 (IP, UA, 행위)	BelongsToTenant

계약 상태 흐름:

draft → pending → partially_signed → completed
                                   → expired
                → cancelled
                → rejected

서명 필드 유형: signature, stamp, text, date, checkbox

---

3. 서비스

서비스	주요 메서드
EsignContractService	list, create, show, cancel, send, remind, configureFields, stats
EsignSignService	getByToken, sendOtp, verifyOtp, submitSignature, reject
EsignAuditService	log, logPublic, getContractLogs
EsignPdfService	generateHash, verifyIntegrity, composeSigned, addAuditPage

---

4. API 엔드포인트

계약 관리 (인증 필요)

HTTP	URI	설명
GET	/v1/esign/contracts	계약 목록
POST	/v1/esign/contracts	계약 생성 (PDF 업로드)
GET	/v1/esign/contracts/stats	통계
GET	/v1/esign/contracts/{id}	계약 상세
POST	/v1/esign/contracts/{id}/cancel	계약 취소
POST	/v1/esign/contracts/{id}/fields	서명 필드 설정
POST	/v1/esign/contracts/{id}/send	계약 발송
POST	/v1/esign/contracts/{id}/remind	리마인드
GET	/v1/esign/contracts/{id}/download	PDF 다운로드
GET	/v1/esign/contracts/{id}/verify	무결성 검증

서명 처리 (토큰 기반, 외부 접근)

HTTP	URI	설명
GET	/v1/esign/sign/{token}	계약 정보 조회
POST	/v1/esign/sign/{token}/otp/send	OTP 발송
POST	/v1/esign/sign/{token}/otp/verify	OTP 검증
GET	/v1/esign/sign/{token}/document	문서 조회
POST	/v1/esign/sign/{token}/submit	서명 제출
POST	/v1/esign/sign/{token}/reject	서명 거절

---

5. FormRequest

Request	주요 검증
ContractStoreRequest	title (필수, max:200), file (필수, pdf, max:20MB), sign_order_type, 서명자 정보
FieldConfigureRequest	fields 배열 (page, position, size, type)
SignSubmitRequest	signature_image (파일), field_values (배열)
SignRejectRequest	reason (필수)

---

관련 문서

• DB 스키마 — 문서/전자서명
• Swagger: /api-docs → ESign 섹션

---

최종 업데이트: 2026-02-27