✅ [서명자] 서명한 날짜 필드 추가

서명한 날짜 필드(SIGNING_DATE) 추가

서명한 날짜 필드는 서명자가 서명한 날짜가 자동으로 기입되는 필드입니다.

다음의 API에서 서명한 날짜 필드가 추가되었습니다.

템플릿 정보 가져오기 API 응답 필드 타입 추가

템플릿 조회API 응답에 날짜, 서명한 날짜 필드 타입이 추가되었습니다.


type FieldType = {  
  TEXT = "TEXT",  
  CHECKBOX = "CHECKBOX",  
  SIGNATURE = "SIGNATURE",  
  IMAGE = "IMAGE",  
  DROPDOWN = "DROPDOWN",  
  NAME = "NAME",  
  COMPANY_NAME = "COMPANY_NAME",  
  ADDRESS = "ADDRESS",  
  DATE = "DATE", // 신규 추가  
  SIGNING_DATE = "SIGNING_DATE" // 신규 추가  
}

class DateFieldInTemplateResponseDto {  
  type: FieldType.DATE;  
  required: boolean;  
  size: {  
    width: number;  
    heigth: number;  
  };  
  position: {  
  	  x: number;  
	  y: number;  
	  page: number;  
	};  
  textStyle: {  
    size: number;  
    font: string;  
  };  
  dataLabel: string;  
  displayFormat: string;  
}

class SigningDateFieldInTemplateResponseDto {  
  type: FieldType.SIGNING_DATE;  
  required: boolean;  
  size: {  
    width: number;  
    heigth: number;  
  };  
  position: {  
  	  x: number;  
	  y: number;  
	  page: number;  
	};  
  textStyle: {  
    size: number;  
    font: string;  
  };  
  dataLabel: string;  
  displayFormat: string;  
}

✅ [서명자/서명 필드] 도장 이미지 업로드만 허용 속성

서명자 서명 필드에 도장 이미지 업로드만 허용하는 속성(allowedGenerationMethods)이 추가되었습니다.

해당 속성이 추가된 API는 아래와 같습니다.

템플릿 정보 가져오기 API를 통해 서명자 서명 필드 도장 이미지 업로드만 허용 속성을 조회할 수 있습니다.

템플릿 생성 시 설정한 서명자 서명 필드 도장 이미지 업로드만 허용 속성(allowedGenerationMethods)을 템플릿 정보 가져오기 API에서 확인할 수 있습니다.
응답 유형은 아래와 같습니다.

"fields": [  
  {  
    "type": "SIGNATURE",  
    "required": true,  
    "signatureTypes": [  
      "STAMP"  
    ],  
    // 신규 추가
    "allowedGenerationMethods": ["STAMP_IMAGE"],  
    "position": {  
      "x": 0.5,  
      "y": 0.5,  
      "page": 1  
    },  
    "dataLabel": "signature_dataLabel"  
  }  
]

✅ [서명자/텍스트 필드] 형식 추가

서명자 텍스트 필드에서 유효성을 검증할 수 있는 형식 속성(format)이 추가되었습니다.

해당 속성이 추가된 API는 아래와 같습니다.

템플릿 정보 가져오기 API를 통해 서명자 텍스트 필드 형식 속성을 조회할 수 있습니다.

템플릿 생성 시 설정한 서명자 텍스트 필드 형식 속성(format)을 템플릿 정보 가져오기 API에서 확인할 수 있습니다.
응답 유형은 아래와 같습니다.

"fields": [  
  { 
    "type": "TEXT",  
    "required": true,  
    "size": {
      "width": 0.3,
      "height": 0.3,
    }
    "position": {  
      "x": 0.5,  
      "y": 0.5,  
      "page": 1  
    },
  	"textStyle": {
  		"size": 12,
  		"font": "NOTO_SANS",
  		"align": "LEFT"
    },
    "dataLabel": "text_dataLabel",
    // 신규 추가
    "format": {
      "type": "PHONE_NUMBER" | "BANK_ACCOUNT_NUMBER" | "BIZ_NUMBER"
    }
  }  
]

✅ [날짜/ 서명한 날짜] 서명자 입력란 조회 API 필드 반환 설명 변경

날짜, 서명한 날짜 필드 반환값의 설명을 아래와 같이 추가하였습니다.

'서명자의 입력값\n ' +
  // 추가
'* 날짜, 서명한 날짜라면 ISO Date string (UTC Timezone)\n' +
'* 날짜, 서명한 날짜는 계약서 PDF에는 KST로 입력됨\n' +
  //
'* 입력항목이 텍스트, 드롭다운, 이름, 회사명 string\n' +
'* 입력항목이 사인/도장 또는 체크박스라면 true, false\n' +
'* 입력항목이 주소라면 AddressInputValue',

🧑‍💻 Webhook 재시도에 대한 정책 변경

기존 정책에서는 Webhook 응답 상태 코드가 200번대 아니거나, 응답에 10초 이상 소요되는 경우 실패로 판단하고 총 5회의 재시도 했습니다. 모니터링 결과 재시도 했을 때 성공 전환율 낮거나, 의도하지 않은 중복 작업을 발생시킬 가능성이 있으므로 일부 상황에 대해 재시도 하지 않도록 변경하고자 합니다. 자세한 내용은 Webhook event를 참고해 주세요.

🚧

Webhook 재시도 정책 변경

[AS-IS]

  • 응답이 2xx 가 아니거나 10초이상 소요되는 모든 요청에 대해 최대 5회 재시도

[TO-BE]

  • 401, 404, 10초 이상의 소요되는 요청(Timeout)을 제외한 응답에 대해 최대 5회 재시도

📂 사용자 입력란 조회 API 응답 필드 타입 추가

사용자 입력란 조회 API 응답에 드롭다운, 계약자 이름, 회사이름, 주소 필드 타입이 추가되었습니다.

participantFields: {
  ...
  type: FieldType
  value: AddressInputValueModel | string | null
}

type FieldType = {
    TEXT = "TEXT",
    CHECKBOX = "CHECKBOX",
    SIGNATURE = "SIGNATURE",
    IMAGE = "IMAGE",
    DROPDOWN = "DROPDOWN", // 신규 추가
    NAME = "NAME", // 신규 추가
    COMPANY_NAME = "COMPANY_NAME", // 신규 추가
    ADDRESS = "ADDRESS", // 신규 추가
}

// 신규 추가 (type 이 ADDRESS 일 경우 해당 value 를 반환)
type AddressInputValueModel = { 
    address1: string;
    address2: string;
    city: string;
    province: string;
    zip: string;
    country: AddressCountryCode;
}
🚧

추가 된 신규 필드유형은 API 서명 요청 시 아직 이용 할 수 없습니다.

추가 된 문서의 신규 필드(드롭다운 , 계약자 이름, 회사이름, 주소)는 모두싸인 플랫폼에서 요청한 문서에 대한 응답 호환성을 유지하기 위해 추가 된 것으로 API를 이용한 서명 요청시에는 아직 사용할 수 없습니다. API를 통한 서명 요청 시 해당 필드들에 대한 지원 여부는 내부 검토중에 있으니 해당 기능 필요 시 모두싸인 플랫폼을 활용 바랍니다.

📂 템플릿 조회 API 응답 필드 타입 추가

템플릿 정보 가져오기 API 응답의 fields에 드롭다운, 계약자 이름, 회사이름, 주소 필드 타입이 추가되었습니다

각 필드 타입은 아래 코드에서 자세히 확인하실 수 있습니다.

class DropdownFieldInTemplateResponseDto {
  type: 'DROPDOWN';
  required: boolean
  size: {
    width: number;
    heigth: number;
  };
  position: {
  	x: number;
	  y: number;
	  page: number;
	};
  textStyle: {
    size: number;
    font: string;
  };
  dataLabel: string;
}
  
class NameFieldInTemplateResponseDto {
  type: 'NAME';
  required: boolean
  size: {
    width: number;
    heigth: number;
  };
  position: {
  	x: number;
	  y: number;
	  page: number;
	};
  textStyle: {
    size: number;
    font: string;
  };
  dataLabel: string;
}

class CompanyNameFieldInTemplateResponseDto {
  type: 'COMPANY_NAME';
  required: boolean
  size: {
    width: number;
    heigth: number;
  };
  position: {
  	x: number;
	  y: number;
	  page: number;
	};
  textStyle: {
    size: number;
    font: string;
  };
  dataLabel: string;
}

class AddressFieldInTemplateResponseDto {
  type: 'ADDRESS';
  required: boolean
  size: {
    width: number;
    heigth: number;
  };
  position: {
  	x: number;
	  y: number;
	  page: number;
	};
  textStyle: {
    size: number;
    font: string;
  };
  dataLabel: string;
}

✅ 문서 리스트 / 문서 상세 조회 API 응답 속성 추가

문서 리스트 / 문서 상세 조회 API를 통해 라벨 정보를 조회할 수 있습니다.

기존에는 서명 요청 시, 혹은 서명 요청 후 모두싸인 홈페이지에서 설정한 라벨 정보를 API를 통해 확인할 수 있는 방법이 없었습니다.

이번 업데이트로 문서 리스트 조회 및 문서 상세 조회 API에 해당 속성이 추가되어 라벨 정보를 확인할 수 있도록 제공됩니다.

앞으로는 API 서명요청에서도 라벨을 통해 문서를 더욱 쉽게 분류하실 수 있습니다!

⚠️ 라벨 정보는 순서를 보장하지 않으니, 필요하신 경우 별도로 정렬이 필요합니다.

📘

기존 폴더 기능이 라벨로 대체

기존에 사용하던 폴더 기능이 라벨로 대체 되며 폴더 관련 속성들은 일정 기간이 지난 후 제거 됩니다.
라벨 기능이 궁금하시면 "라벨을 만들어 분류하기" 를 참고해주세요

📂 문서 리스트 조회 시 필터 조건 추가

문서 리스트 조회 API 필터에 마지막 활동일(updatedAt) 조건이 추가되었습니다.

📘

필터로 검색하기가 어떤 기능인지 궁금하신 분은 filter로 검색하기를 확인해 보세요.

📂 문서 리스트 조회 시 정렬 기능 추가

문서 리스트를 API를 통해 조회 시 정렬 기능이 추가되었습니다.

📌 정렬 기능은 orderBy 속성을 통해 이용하실 수 있습니다.

📌 정렬 가능 필드는 문서 제목, 문서 생성일, 마지막 활동일이 제공됩니다.

📌 정렬 기준은 오름차순, 내림차순이 제공됩니다.

📘

정렬 기능이 궁금하신 분은 orderBy로 정렬하기를 확인해 보세요.

✅ 문서 상세 조회 API 응답 속성 추가

문서 상세 조회 API 를 통해 참조자 리스트를 조회 할 수 있습니다.

서명 요청 시 설정한 참조자 정보를 설정 한 후 해당 정보를 API 를 통해 확인할 수 있는 부분이 없었지만, 문서 상세 조회에 해당 속성이 추가 되어 확인할 수 있도록 제공 됩니다. ( carbonCopies)

응답 유형은 아래와 같으며, contact 항목이 제공 됩니다.

{
  "carbonCopies": [
    {
      "contact": "01000000000"
    },
    {
      "contact": "[email protected]"
    }
  ]
}

🗂️ 서명 요청 시 라벨 아이디 속성 추가

서명 요청, 템플릿으로 서명 요청 시 복수개(최대 5개)의 라벨을 설정할 수 있습니다.

📘

기존 폴더 기능이 라벨로 대체

기존에 사용하던 폴더 기능이 라벨로 대체 되며 폴더 관련 속성들은 일정 기간이 지난 후 제거 됩니다.
라벨 기능이 궁금하시면 "라벨을 만들어 분류하기" 를 참고해주세요

📌 서명요청, 템플릿으로 서명요청 시 사용하던 folderId는 이제 labelIds으로 대체 됩니다.

📌 folderId는 하나의 폴더를 지정했지만, labelIds는 복수개(최대 5개)의 라벨 설정이 가능 합니다.

📢 기존에 folderId를 사용하고 계셨다면 labelIds속성을 사용할 수 있도록 변경을 권장드리며, 신규로 라벨 기능을 사용하시려면 labelIds속성을 활용해주세요!


📋 "전송 예약 중" 문서 상태 추가

모두싸인 플랫폼에서 예약 전송 기능이 추가됨에 따라 플랫폼에서 설정한 예약문서에 대해 상태(Status) 속성으로 SCHEDULED가 추가 되었습니다.

📘

예약전송 이란?

원하는 시간에 서명 요청이 전송되도록 예약할 수 있는 기능이며 모두싸인 플랫폼에서 이용 가능합니다. 예약 전송 기능이 궁금하시면 "예약 전송 기능 소개"를 참고해주세요

📌 모두싸인 플랫폼 기능과 API 기능을 함께 사용할 경우, 플랫폼에서 예약 전송 등록 시 API 에서는 해당 문서가 SCHEDULED 상태로 조회 됩니다.

✅ 문서 상세 조회 API 응답 속성 추가

문서 상세 조회 API 를 통해 서명자 추가인증 정보를 조회 할 수 있습니다.

서명 요청 시 설정한 서명자의 추가 인증 정보를 설정 한 후 해당 정보를 API 를 통해 확인할 수 있는 부분이 없었지만, 문서 상세 조회에 해당 속성이 추가 되어 확인할 수 있도록 제공 됩니다. ( participants -> verification)

응답 유형은 아래와 같으며, password, mobileIdentification, dCert 중 설정 된 항목만 제공 됩니다.
⚠️ 패스워드의 경우 보안상의 이유로 설정값은 제공하지 않으며 힌트만 제공합니다.

"verification": {
  "password": {
    "hint": "대한민국 1등 전자계약 서비스는?"
  }
  "mobileIdentification": {
    "name": "김모두",
    "phoneNumber": "01000000000"
  },}
  "dCert": {
    "name": "모두싸인",
    "bizNumber": "1234567890"
  }
}

🥳 웹훅(Webhook) API 추가

API 로 웹훅 관리가 가능합니다!

웹훅을 통해 모두싸인에서 발생하는 이벤트를 사용자가 지정한 특정 URL로 POST 요청받을 수 있습니다.

🚧

이럴때 사용하세요!

서명요청 시작부터 서명완료 과정에서 문서의 상태 변경 발생 시 고객사에서 운영중인 시스템의 특정 작업이 수행되어야 할 때(관리하고 있는 데이터의 상태 변경, 알림 전송 등), 모두싸인에서 발송하는 웹훅 이벤트를 받아 처리할 수 있습니다.

웹훅 기능에 대해 궁금하시면 Webhook 설정을 확인해 보세요

웹훅은 그동안 모두싸인 플랫폼 내에서 설정이 가능하며 많이 이용하고 계시는 기능 중 하나 입니다. API 로 제공되는 웹훅은 아래와 같은 상황에서 활용하기 더욱 좋습니다.

  • 내부 정책상 모두싸인 플랫폼에 접속이 불가능 한 경우 웹훅 API 를 이용해 관리 프로그램을 직접 구현하여 이용 가능 합니다.
  • OAuth 연동을 통해 관리하고 있는 고객사의 고객 워크스페이스에 웹훅을 등록하여, 해당 워크스페이스에서 요청한 문서 상태 변경에 대한 이벤트를 받아 활용할 수 있습니다.
📘

아래와 같은 상황에서 Webhook은 호출 실패로 판단하고 재시도(총 5회)를 시도 하도록 합니다.

200번대 응답이 아닐 경우
10초 이내에 응답이 오지 않을 경우

Webhook event 수신 후 내부적으로 어떤 로직을 수행하는데 있어 10초 이상 지연 될 수 있다면, timeout 으로 인해 재전송 될 수 있으니, Webhook event 수신 시 응답을(200번대 응답) 먼저 회신 후 내부 작업을 진행해주시는 것을 권장 드립니다.

구독할 수 있는 웹훅 이벤트 종류는 아래와 같습니다.

  • document_started (서명 요청)
  • document_signed (서명 입력)
  • document_all_signed (모든 서명 완료)
  • document_rejected (거절)
  • document_request_canceled (요청 취소)
  • document_signing_canceled (서명 취소)

전달되는 이벤트 인터페이스 아래와 같습니다.

{
  "event": {
    "type": "{EVENT_TYPE}"
  },
  "document": {
    "id": "{DOCUMENT_ID}",
    "requester": {
      "email": "{REQUESTER_EMAIL}"
    }
  }
}

🥳 서명 요청시 파일첨부 기능 추가

계약서 발송 시 관련 서류를 첨부하여 보낼 수 있습니다!

계약서를 발송할 때, 관련 서류를 업로드할 수 있는 ‘서명 요청 시 파일 첨부’ 기능이 업데이트 되었습니다. 계약을 뒷받침해주거나 서명(계약 체결) 시 고지 또는 안내가 필요한 서류를, 서명 요청 단계에서 즉시 첨부하여 계약서와 함께 발송할 수 있게 되었습니다.

🚧

이럴때 사용하세요!

고정 된 형식의 첨부파일의 경우 템플릿에 미리 설정해두고 서명 요청을 할 수 있습니다.
요청자 첨부파일 API는 서명 요청 마다 첨부해야 할 파일이 변경되어야 할 경우에 활용을 권장 합니다.

서명 요청시 파일첨부 기능에 대해 궁금하시면 서명 요청시 파일첨부 업데이트를 확인해 보세요

파일 첨부 방법

파일을 첨부하기 위해서는 아래와 같이 파일 정보(fileId, token, name) 가 필요 합니다.

해당 파일 정보는 이번에 같이 추가 된 파일 업로드 API 를 통해 획득 가능 합니다.

파일 업로드는 다른 API 와 달리 Contents-Type 이 "multipart/form-data" 으로 요청이 필요하며 binary 형식의 파일을 Stream 을 통해 업로드 후 해당 파일에 대한 정보를 반환 합니다. 파일 개당 10MB 까지 업로드 가능하며 토큰의 유효시간은 2시간 입니다. 서명 요청 시 첨부하려는 파일을 파일 업로드 API 를 통해 업로드 후 받은 정보들을 이용해 이어서 서명 요청을 진행하는 방식으로 이용할 수 있습니다.

해당 기능이 적용 된 API 는 아래와 같습니다.