문서 이력 조회

문서 이력 조회 API

문서의 이력은 "문서 이력 조회 API"를 통해 조회할 수 있습니다.

이력 데이터 구조

모든 문서 이력은 다음과 같은 공통 구조를 가집니다:

{
  // 메시지 (추상적으로 표현한 예시입니다. 실 메시지는 action마다 다릅니다)
  message: `
    ${generator.name}(${generator.contact})님이 
    ${target.name}(${target.contact})님에게
    ${additionalInfo} ${action} 하였습니다.
  `,

  // 언제
  timestamp: "2020-01-01T00:00:00.000Z",

  // 무엇을  
  action: 'ACTION_NAME',

  // 누가
  generator: {
    // 기본 정보
    type: 'PARTICIPANT || REQUESTER || SYSTEM',
    name: '박길동',
    contact: '[email protected]',

    // 환경 정보 (PARTICIPANT, REQUESTER일 때만)
    environment: {
      userIp: '255.255.255.0',
      userAgent: 'Mozilla/5.0 (Windows; U; Windows NT 5.1; de-CH)...',
    },
  },

  // 누구에게
  target: {
    // 기본 정보
    type: 'PARTICIPANT',
    name: '박참여',
    contact: '[email protected]'
  },

  // 어떻게 (선택적 정보)
  details: {
    // action이 VERIFICATION_FAILURE, VERIFICATION_EXCEEDED, VERIFICATION_COMPLETED일 때
    authType: 'PASSWORD || MOBILE',
    // action이 VERIFICATION_FAILURE일 때
    failureCount: 5,
  },
}

주요 필드 설명

필드타입설명
messagestring이력에 대한 한국어 설명 메시지
timestampstring이력 발생 시간 (ISO 8601 형식)
actionstring액션 타입 (아래 탭에서 상세 확인)
generatorobject액션을 수행한 주체 정보
targetobject액션의 대상이 되는 참여자 정보 (해당하는 경우)
detailsobject액션별 추가 상세 정보 (해당하는 경우)

액션별 이력 예시

서명 요청 시작

START_SIGNING_REQUEST

요청자가 새로운 서명 요청을 시작할 때 생성되는 이력입니다.

{
  message: '김요청([email protected])님이 서명 요청을 시작하였습니다.',
  timestamp: "2020-01-01T00:00:00.000Z",
  action: 'START_SIGNING_REQUEST',
  generator: {
    type: 'REQUESTER',
    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
}

서명 요청 전송

SIGNING_REQUEST

시스템이 참여자에게 서명 요청을 전송할 때 생성되는 이력입니다.

{
  message: '박참여([email protected])님에게 서명할 문서를 전송하였습니다.',
  timestamp: "2020-01-01T00:00:00.000Z",
  action: 'SIGNING_REQUEST',
  generator: {
    type: 'SYSTEM',
    name: null,
    contact: null,
    environment: null
  },
  target: {
    type: 'PARTICIPANT',
    name: '박참여',
    contact: '[email protected]'
  },
  details: null
}

서명 요청 취소

CANCEL_SIGNING_REQUEST

요청자가 진행 중인 서명 요청을 취소할 때 생성되는 이력입니다.

{
  message: '김요청([email protected])님이 서명 요청을 취소하였습니다.',
  timestamp: "2020-01-01T00:00:00.000Z",
  action: 'CANCEL_SIGNING_REQUEST',
  generator: {
    type: 'REQUESTER',
    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
}

서명 알림 재전송

REMIND_SIGNING

요청자가 참여자에게 서명 알림을 재전송할 때 생성되는 이력입니다.

{
  message: '김요청([email protected])님이 박참여([email protected])님에게 서명할 문서를 전송하였습니다.',
  timestamp: "2020-01-01T00:00:00.000Z",
  action: 'REMIND_SIGNING',
  generator: {
    type: 'REQUESTER',
    name: '김요청',
    contact: '[email protected]',
    environment: {
      userIp: '255.255.255.0',
      userAgent: 'Mozilla/5.0 (Windows; U; Windows NT 5.1; de-CH)...'
    }
  },
  target: {
    type: 'PARTICIPANT',
    name: '박참여',
    contact: '[email protected]'
  },
  details: null
}

서명 유효 기간 수정

CHANGE_SIGNING_EXPIRY_DATE

요청자가 참여자의 서명 유효 기간을 수정할 때 생성되는 이력입니다.

{
  message: '김요청([email protected])님이 박참여([email protected])님의 서명 유효기간 만료일을 변경하였습니다.',
  timestamp: "2020-01-01T00:00:00.000Z",
  action: 'CHANGE_SIGNING_EXPIRY_DATE',
  generator: {
    type: 'REQUESTER',
    name: '김요청',
    contact: '[email protected]',
    environment: {
      userIp: '255.255.255.0',
      userAgent: 'Mozilla/5.0 (Windows; U; Windows NT 5.1; de-CH)...'
    }
  },
  target: {
    type: 'PARTICIPANT',
    name: '박참여',
    contact: '[email protected]'
  },
  details: null
}

액션 타입 요약

카테고리액션 코드설명
서명 요청 관리START_SIGNING_REQUEST요청자가 서명 요청 시작
SIGNING_REQUEST시스템의 서명 요청 전송
CANCEL_SIGNING_REQUEST서명 요청 취소
REMIND_SIGNING서명 알림 재전송
CHANGE_SIGNING_EXPIRY_DATE서명 유효 기간 수정
참여자 서명 활동FIRST_READING_DOCUMENT_IN_SIGNING_TURN참여자의 첫 문서 조회
READING_DOCUMENT_IN_SIGNING_TURN참여자의 문서 조회 (재방문)
SIGNING_COMPLETED서명 입력
SIGNING_COMPLETED_ALL모든 서명 입력 완료
REJECT_SIGNING서명 거절
CANCEL_SIGNING서명 취소
CORRECT_SIGNING서명 수정
인증 관련VERIFICATION_FAILURE추가 인증 실패
VERIFICATION_EXCEEDED추가 인증 5회 실패
VERIFICATION_COMPLETED인증 성공
열람 요청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열람 만료일 변경

💡 활용 팁

각 액션별 이력을 활용하여 문서의 진행 상황을 추적하고, 사용자별 활동 로그를 분석할 수 있습니다. 특히 인증 실패 관련 이력은 보안 모니터링에 유용합니다.