문서 이력 조회 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,
  },
}

주요 필드 설명

필드	타입	설명
`message`	string	이력에 대한 한국어 설명 메시지
`timestamp`	string	이력 발생 시간 (ISO 8601 형식)
`action`	string	액션 타입 (아래 탭에서 상세 확인)
`generator`	object	액션을 수행한 주체 정보
`target`	object	액션의 대상이 되는 참여자 정보 (해당하는 경우)
`details`	object	액션별 추가 상세 정보 (해당하는 경우)

액션별 이력 예시

서명 요청 시작

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`	열람 만료일 변

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