DocsReferencesChangelogCommunity
Docs

문서 이력 조회하기

문서 이력 조회 API(GET /documents/{documentId}/histories)를 통해 문서 하나에서 일어난 모든 이력을 조회할 수 있습니다. 서명 요청, 참여자의 문서 조회·서명, 추가 인증 성공·실패, 문서 수정 등 누가 언제 무엇을 했는지 확인할 수 있습니다.

📘

시작하기 전에 꼭 이해하기

  • 이력은 문서 단위로 조회합니다. 문서 ID 하나를 지정하면 그 문서의 이력이 histories 배열로 응답됩니다.
  • 각 이력은 어떤 일이 일어났는지(action), 누가 했는지(generator), 누구에게 일어났는지(target)로 구성됩니다.
  • 이력을 활용하면 문서의 진행 상황을 추적하고 사용자별 활동 로그를 분석할 수 있습니다. 특히 인증 실패 관련 이력은 보안 모니터링에 유용합니다.

1. 이력 조회하기

조회할 문서의 ID를 경로에 넣어 호출합니다. 별도의 쿼리 파라미터는 없습니다.

curl --request GET \
  --url 'https://api.modusign.co.kr/documents/{documentId}/histories' \
  --header 'Accept: application/json' \
  --header 'Authorization: Basic {인코딩된 API-KEY}'

응답 예시

{
  "histories": [
    {
      "message": "박참여([email protected])님이 접근 암호 인증을 2회 실패하였습니다.",
      "timestamp": "2026-10-01T09:10:00.000Z",
      "action": "VERIFICATION_FAILURE",
      "generator": {
        "type": "PARTICIPANT",
        "name": "박참여",
        "contact": "[email protected]",
        "environment": {
          "userIp": "255.255.255.0",
          "userAgent": "Mozilla/5.0 (Windows; U; Windows NT 5.1; de-CH)"
        }
      },
      "target": null,
      "details": {
        "authType": "PASSWORD",
        "failureCount": 2
      }
    },
    {
      "message": "박참여([email protected])님이 문서에 서명하였습니다.",
      "timestamp": "2026-10-01T09:15:00.000Z",
      "action": "SIGNING_COMPLETED",
      "generator": {
        "type": "PARTICIPANT",
        "name": "박참여",
        "contact": "[email protected]",
        "environment": {
          "userIp": "255.255.255.0",
          "userAgent": "Mozilla/5.0 (Windows; U; Windows NT 5.1; de-CH)"
        }
      },
      "target": null,
      "details": null
    }
  ]
}

2. 이력 데이터 구조

모든 이력은 같은 구조를 가집니다.

필드타입설명
messagestring이력을 문장으로 요약한 메시지
timestampstring (date-time)이력이 발생한 시간 (ISO 8601)
actionstring이력의 종류 (아래 3. action 종류 참고)
generatorobject이력의 발생자
targetobject | null이력의 대상자
detailsobject | null이력의 자세한 정보

generator (발생자)

필드설명
type발생자의 종류: SYSTEM, PARTICIPANT, REQUESTER, ADMIN
name발생자의 이름
contact발생자의 연락처 (이메일 또는 전화번호)
environment.userIp발생자의 IP 주소
environment.userAgent발생자 브라우저의 user-agent

environment는 발생자가 참여자(PARTICIPANT) 또는 요청자(REQUESTER)일 때 값이 채워지며, 시스템(SYSTEM)이 발생시킨 이력에서는 null입니다. generator의 각 값은 null일 수 있습니다.

target (대상자)

이력의 대상이 되는 참여자 정보입니다. 대상자가 없는 이력에서는 null입니다.

필드설명
type대상자의 종류: PARTICIPANT
name대상자의 이름
contact대상자의 연락처 (이메일 또는 전화번호)

details (자세한 정보)

추가 인증 관련 이력에서 사용되며, 그 외 이력에서는 null입니다.

필드설명
authType인증 수단: PASSWORD, MOBILE, D_CERT (action이 VERIFICATION_FAILURE, VERIFICATION_EXCEEDED, VERIFICATION_COMPLETED일 때)
failureCount누적 실패 횟수 (action이 VERIFICATION_FAILURE일 때)

3. action 종류

서명 요청 관리

action설명
START_SIGNING_REQUEST서명 요청 시작 (요청자가 서명 요청 시작)
SIGNING_REQUEST서명 요청 됨 (시스템의 서명 요청 전송)
CANCEL_SIGNING_REQUEST서명 요청 취소
REMIND_SIGNING서명 알림 재전송
CHANGE_SIGNING_EXPIRY_DATE서명 유효 기간 수정

참여자 서명 활동

action설명
FIRST_READING_DOCUMENT_IN_SIGNING_TURN서명 차례에 첫 문서 조회
READING_DOCUMENT_IN_SIGNING_TURN서명 차례에 문서 조회 (재방문)
SIGNING_COMPLETED서명 입력
SIGNING_COMPLETED_ALL모든 서명 입력 완료
REJECT_SIGNING서명 거절
CANCEL_SIGNING서명 취소
CORRECT_SIGNING서명 수정

인증 관련

action설명
VERIFICATION_FAILURE추가 인증 실패 (details.failureCount에 누적 실패 횟수)
VERIFICATION_EXCEEDED추가 인증 5회 실패
VERIFICATION_COMPLETED인증 성공

열람 요청

action설명
START_VIEW_ONLY_REQUEST열람 요청 시작
VIEW_ONLY_REQUEST열람 요청
FIRST_READING_VIEW_ONLY_IN_OWN_TURN열람 요청자가 문서 처음 열람
READING_VIEW_ONLY_IN_OWN_TURN열람 요청자가 문서 열람 (재방문)
VIEW_ONLY_COMPLETED열람 완료
VIEW_ONLY_COMPLETED_ALL모든 열람 완료
CANCEL_VIEW_ONLY_REQUEST열람 요청 취소
REMIND_VIEW_ONLY열람 재요청
CHANGE_VIEWING_EXPIRY_DATE열람 만료일 변경

대면 서명

action설명
SIGNING_REQUEST_TO_HOST호스트에게 서명 요청
START_SESSION대면 서명 세션 시작

문서 내용 수정

action설명
MODIFICATION_STARTED수정 시작
MODIFICATION_COMPLETED수정 완료
MODIFICATION_CANCELED수정 되돌리기
SIGNER_INFO_CHANGED서명자 정보 변경
SIGNER_ADDED서명자 추가
SIGNER_REMOVED서명자 삭제
SIGNERS_CHANGED서명자 변경 (통합)
SIGNER_ORDER_CHANGED서명 순서 변경
SIGNER_ATTACHMENT_CHANGED서명자 첨부 변경
DOCUMENT_SETTINGS_CHANGED문서 설정 변경 (통합)
FIELD_MODIFIED입력란 변경
REQUESTER_FIELD_MODIFIED요청자 편집 필드 변경
FIELD_GROUP_CHANGED필드 그룹 변경
TITLE_CHANGED제목 변경
ATTACHMENT_CHANGED첨부 변경
VERIFICATION_CHANGED인증수단 변경
DOCUMENT_FILE_CHANGED원본 파일 변경
CARBON_COPY_CHANGED참조인 변경
PDF_PASSWORD_CHANGEDPDF 비밀번호 변경
SIGNING_PERIOD_CHANGED서명 기한 변경

참여자 대리

action설명
CHANGE_PARTICIPANT_DELEGATION_PERIOD참여자 대리 기간 변경
INTERRUPT_PARTICIPANT_DELEGATION참여자 대리 중단
🌟

안내사항

  • 기능이 추가되면 action 값도 늘어날 수 있습니다. 연동 로직에서는 모르는 action 값이 와도 오류 없이 처리되도록 구현하세요.
  • message는 사람이 읽기 위한 요약 문장입니다. 이력의 종류를 판별할 때는 message 대신 action 값을 사용하세요.

4. 활용 예시

추가 인증 실패 모니터링하기

action이 VERIFICATION_FAILURE인 이력에서 details.authType(인증 수단)과 details.failureCount(누적 실패 횟수)를 확인할 수 있습니다. 5회 실패하면 VERIFICATION_EXCEEDED 이력이 남습니다.

발생자의 IP와 브라우저 정보는 generator.environment에서 확인할 수 있습니다.

참여자별 진행 상황 확인하기

generator.type이 PARTICIPANT인 이력을 참여자(generator.contact)별로 모으면, 각 참여자가 문서를 처음 조회한 시점(FIRST_READING_DOCUMENT_IN_SIGNING_TURN)과 서명한 시점(SIGNING_COMPLETED)을 확인할 수 있습니다.

5. API 호출 시 주의사항

  • API KEY는 서버사이드에서만 사용하세요. 이력 응답에는 참여자의 연락처·IP 주소가 포함되므로, 클라이언트에 그대로 노출하지 않도록 주의하세요.
  • 조회 권한이 있는 문서만 조회할 수 있습니다. API KEY를 발급한 계정이 조회할 수 없는 문서(다른 계정의 문서, 공유받지 않은 문서, 삭제된 문서 등)의 ID로 호출하면 403 Forbidden이 응답됩니다.
  • 실시간 상태 변화는 Webhook으로 받으세요. 서명 완료 등을 확인하려고 이력 조회를 반복 호출(폴링)하지 말고, Webhook으로 이벤트를 받은 뒤 필요할 때 이력을 조회하세요.
  • 문서 이력 조회 API는 Standard API로 분당 300회, 초당 10회로 제한됩니다. 자세한 내용은 API Rate Limit 정책 안내를 참고하세요.

자주 발생하는 오류

응답에러 메시지원인해결 방법
401UnauthorizedAPI KEY 또는 인증 헤더 오류API KEY와 Authorization 헤더(Basic 또는 Bearer) 확인
403Forbidden조회 권한이 없는 문서 ID로 요청문서 ID가 올바른지, 문서를 요청한 계정의 API KEY로 호출했는지 확인
403Usage limit exceededAPI 사용량이 모두 소진됨사용량 한도 확인 또는 플랜 업그레이드
429-Rate Limit 초과 (HTTP 429 Too Many Requests)X-Retry-After(초)만큼 대기 후 재시도, 지수 백오프 권장

6. 자주 묻는 질문

이력 조회에서 403 오류가 발생합니다.

API KEY를 발급한 계정이 해당 문서를 조회할 권한이 없을 때 발생합니다.

응답 예시:

{
  "statusCode": 403,
  "message": "Forbidden",
  "error": "Forbidden"
}
  • 다른 계정·워크스페이스에서 요청된 문서인지, 공유받지 않은 문서인지, 삭제된 문서인지 확인하세요.
  • 같은 API KEY로 문서 상세 조회가 되는지 확인하세요.
generator.environment가 null로 옵니다.

environment는 발생자가 참여자(PARTICIPANT) 또는 요청자(REQUESTER)일 때 값이 채워지며, 시스템(SYSTEM)이 발생시킨 이력에서는 null입니다.

target은 언제 null인가요?

target은 이력의 대상이 되는 참여자 정보입니다. 대상자가 따로 없는 이력에서는 null입니다.

👍

더 자세한 API 내용은 API References에서 확인하세요!

문서 이력 조회, 문서 상세 조회 의 자세한 내용을 확인하세요.

🚧

유의사항

  • 이력의 종류는 message가 아니라 action 값으로 판별하고, 새로운 action 값이 추가되어도 오류가 나지 않도록 구현하세요.
  • 이력에는 참여자의 연락처·IP 주소 등 개인정보가 포함되므로 취급에 주의하세요.
  • 조회 권한이 없는 문서 ID로 호출하면 403 Forbidden이 응답됩니다.
  • 상태 변화 확인을 위한 반복 조회는 Webhook으로 대체하세요.

Updated 2 days ago

Did this page help you?