🥳 임베디드 서명 요청 시 파일 병합 지원

임베디드 서명 요청 시 파일 병합 후 서명 요청 할 수 있도록 프로세스가 개선 되었습니다. 이와 관련 해 기존 2개의 API가 수정 되고 하나의 신규 API가 추가 되었습니다.

[수정] 파일 업로드 API 의 type 속성에 document 추가 지원

해당 수정으로 병합 할 파일을 미리 업로드 할 수 있습니다. (유효기간 2시간) PDF 파일은 최대 10MB, 그 외 확장자는 최대 5MB 까지 지원 합니다.

📘

업로드 시 PDF 파일을 권장합니다. (그 외 파일은 내부적으로 PDF 변환 시 시간이 오래 걸립니다.)

[신규] 문서 파일 병합 API 추가

파일 업로드 API 를 통해 업로드 한 파일 정보(fileId, token)를 기반으로 PDF 파일을 병합 합니다. 최소 2개, 최대 10개 까지 병합할 수 있으며, 병합 된 파일의 총 용량은 10MB 를 초과할 수 없습니다. 병합 후 병합 된 파일의 정보(fileId, token)를 응답 합니다.

[수정] 임베디드 초안 생성 API 의 file 속성에 FILE_REF 방식 추가 제공

기존에는 BASE64 방식만 지원 했으나, FILE_REF 방식을 추가로 지원 합니다. FILE_REF방식은 아래 두 프로세스를 통해 업로드한 파일로 임베디드 초안이 생성 가능 합니다.

1. 파일 업로드 API 를 통해 업로드 한 문서 타입 파일 정보
2. 문서 파일 병합 API 를 통해 업로드 된 파일 정보

감사 추적 인증서 언어 옵션 제공

서명 요청 및 임베디드 초안 생성 시, 감사 추적 인증서(Audit Trail) 의 언어를 선택할 수 있습니다. 설정하지 않으면 기본값은 한국어(ko) 로 적용됩니다.

🧩 옵션 개요

감사 추적 인증서(auditTrail) 객체 내에 locales 속성을 추가하여 출력 언어를 지정합니다.

{
	...,
	"auditTrail" : {
		"locales": ["ko", "en"]
	}
}

🌐 지원 언어 옵션

아래의 언어를 제공하며, locales 에 값을 입력하시면 됩니다. 미 설정 시, 한국어를 기본 값으로 제공합니다.

• 한국어 : [”ko”]
• 영어 : [”en”]
• 한국어 + 영어 합본 : [”ko”, "en”]

적용 API 목록

• 서명 요청 (POST /documents)
• 템플릿으로 서명 요청 (POST /documents/request-with-template)
• 임베디드 초안 생성 (POST /embedded-drafts)
• 템플릿으로 임베디드 초안 생성 (POST /embedded-drafts/create-with-template)

🚧

auditTrail.locales 설정은 문서 생성 시점에만 지정할 수 있습니다. 문서가 생성된 이후에는 변경이 불가능하므로 주의하여 설정해주세요.

➕ 템플릿 생성 시 드롭다운 필드 등 일부 필드 지원 추가

템플릿 생성하기 API에서 드롭다운 필드 등 일부 필드를 지정하실 수 있도록 기능이 추가됩니다.

추가된 필드 타입

서명자 입력란, 서명자 입력란 구분에 따라 추가된 타입이 다릅니다. 아래를 클릭하여 각 구분별로 추가된 타입을 확인하실 수 있습니다.

적용 API

• 템플릿 생성하기 (POST /templates)

📚 문서 업로드 시 HWPX 확장자 지원

서명 요청 시 HWPX 확장자의 파일을 업로드 하실 수 있도록 지원됩니다.

✍️ 사인 그리기만 허용 설정 추가

• 서명 필드에 allowedGenerationMethods 속성에서 SIGN_DRAWING 값을 지정하면, 사인 입력 시 ‘그리기만’ 허용하는 방식으로 설정할 수 있습니다.

• 이 설정은 사인 전용 필드뿐 아니라 사인/도장 겸용 필드에서도 아래와 같이 활용할 수 있습니다.

  • 필드 유형	사용 가능 allowedGenerationMethods
    사인	SIGN_DRAWING
    도장	STAMP_IMAGE
    사인/도장	SIGN_DRAWING , STAMP_IMAGE 모두 지원

    
    

영향 대상 API 엔드포인트

• 서명 요청
• 임베디드 초안 생성
• 템플릿 생성
• 템플릿 정보 가져오기

✨ 템플릿 및 서명 요청 시 참조자(Carbon Copy) 필드 지원

이번 업데이트에서는 템플릿 생성 시 참조자(Carbon Copy)를 사전 등록하고, 서명 요청 시 참조자 정보를 템플릿과 병합하여 전송할 수 있도록 개선되었습니다.

1. 템플릿 생성 API (POST /templates)

• carbonCopies 필드 신규 추가
• 템플릿 생성 시 참조자(contact, locale) 정보를 사전 등록 가능
• 응답에도 carbonCopies 정보 포함됨

{
  "carbonCopies": [
    {
      "contact": "[email protected]",
      "locale": "ko"
    }
  ]

2. 템플릿 기반 요청 및 서명 요청 API

• 기존 API에 하위 호환 방식으로 locale 필드가 optional로 추가됨
• API 요청 시 전달된 carbonCopies와 템플릿에 등록된 carbonCopies를 병합하여 사용

적용 API 목록

• 템플릿으로 서명 요청 (POST /documents/request-with-template)
• 템플릿으로 임베디드 초안 생성 (POST /embedded-drafts/create-with-template)
• 서명 요청 (POST /documents)

⚠️ 제한 사항

1. carbonCopies 병합 후 총 인원이 30명을 초과할 경우 오류
2. locale을 생략하면 기본값으로 “ko” (한국어) 가 적용됨

📝 템플릿으로 서명 요청 시 서명자의 일부 필드 제거 기능 추가

템플릿으로 서명 요청 API와 템플릿으로 임베디드 초안 생성 API에서 서명 요청 시 서명자의 일부 필드를 제거하여 전송할 수 있도록 participantMappings 하위에 fieldMappings 를 설정할 수 있도록 제공됩니다.

fieldMappings에 데이터 라벨, 제외 여부를 설정하실 수 있으며, 만약 데이터라벨을 그룹의 데이터라벨로 지정할 경우, 그룹에 속한 모든 필드가 제거되니 주의하여 사용해주십시오.

필드를 제거하여 요청할 수 없는 경우는 아래와 같습니다.

1. 템플릿이 설정 고정 템플릿인 경우
2. 설정한 데이터라벨이 자동 완성 필드의 그룹 ID인 경우
3. 설정한 데이터라벨이 체크박스 그룹의 하위 체크박스인 경우

📌 설정 고정 템플릿 정보 추가

🚧

수정불가 템플릿은 템플릿의 설정을 요청자가 임의로 수정하여 서명 요청을 보낼 수 없도록 설정된 템플릿입니다.

모두싸인 웹사이트, 임베디드 템플릿 생성 및 임베디드 템플릿 수정 기능에서 템플릿을 설정 고정 상태로 지정할 수 있습니다.

이에 맞추어 템플릿을 활용하여 서명 요청을 진행하는 아래 엔드포인트들에 대하여, 설정 고정 상태의 템플릿이라면 템플릿에 설정된 정보를 제외하거나 변경하여 서명 요청할 수 없도록 제한이 추가됩니다.

• 템플릿으로 서명 요청
• 템플릿으로 임베디드 초안 생성

위 API들에 대해 설정 고정 상태의 템플릿에 설정된 정보를 일부 변경 (특정 참여자 제외, 템플릿에 설정된 필수 인증 수단 미설정 등) 하여 서명요청을 전송하려 하는 경우, 422 (UnprocessableEntityException) 오류를 반환합니다.

따라서, 위 API를 활용하시는 경우 템플릿 정보 가져오기 에서 반환된 설정 고정 여부를 확인하시어 예외 처리를 진행하시는 것을 권장합니다.

{
  "id": "{templateId}",
  ...
  "requesterEditable": false // 설정이 고정된 템플릿
}

🚫 API Rate Limit 적용

안정적인 서비스 이용을 위해 Rate Limit 정책이 단계적으로 시행됩니다.

유예 기간 (2025년 3월 1일 시작): 해당 기간은 변경될 정책에 적응하고 API 사용량을 조절할 수 있도록 마련되었습니다. > 확정된 Rate Limit 규칙이 공지되며, 응답 헤더를 통해 예상 결과를 미리 확인하실 수 있습니다. 실제 요청 차단은 유예 기간 동안 적용되지 않습니다.

활성 (2025년 9월 1일 시작): Rate Limit 규칙이 완전히 적용되어, 제한 초과 요청은 HTTP 429 오류와 함께 거부됩니다.

📘

현재는 유예 기간 입니다.

API Rate Limit 규칙

API 요청에 대한 응답에는 현재 Rate Limit 상태를 나타내는 헤더 정보가 포함됩니다. 이를 통해 현재 사용 가능한 요청 횟수와 제한 관련 정보를 확인할 수 있습니다.

대부분의 API는 분당 600회의 요청 제한이 적용되지만, 다음 API 목록은 분당 300회의 요청 제한이 적용됩니다. 제한 횟수를 초과하면 HTTP 429 (Too Many Requests) 오류가 발생하니 유의하시기 바랍니다.

❗️

요청 제한 초과 시 HTTP 429(Too Many Requests) 상태 코드와 함께 X-Retry-After 헤더가 반환됩니다.
[API Rate Limit 정책 안내] 를 참고하여 요청 제어 및 Retry 정책 등을 준비해주세요.

📃 열람 요청 기능 추가

❗️

열람 요청 주의사항 안내

1. 열람 문서는 계약의 효력을 가지지 않습니다. 계약의 효력과 무관한 통지서, 고지서, 확인서, 내역서와 같은 단순 열람 문서를 전송하시는데에 활용하실 수 있습니다.
2. 열람용 템플릿의 역할은 일반 템플릿과 다르게 "열람자" 로 고정되어 설정됩니다.
   문서 발송 시 참고 부탁드립니다.
3. 열람 문서는 기본 설정값으로, 열람자가 문서에 접근할 경우 열람 완료 상태로 자동으로 전환됩니다.
   1. 이를 원치 않으신다면, 열람용 템플릿의 "상세 열람 후 완료 클릭" 설정을 활성화하여 열람자가 문서 내용을 모두 확인 후 수동으로 열람 완료로 전환되도록 설정할 수 있습니다.

열람 문서와 서명 요청과의 서로 다른 차이점, 제한 사항들은 고객센터 > 문서 열람 요청 방법에서 자세히 확인하실 수 있습니다.

📤 열람 요청 문서 전송 기능 추가

아래 API들에 대하여 열람 요청 템플릿을 통해 열람 문서를 전송할 수 있습니다.

• 템플릿으로 서명 요청
• 템플릿으로 임베디드 초안 생성

자세한 내용은 템플릿으로 열람 요청하기를 참고 부탁드립니다.

👀 열람자에 대한 참여자 응답값 추가

문서 상세 조회와 같이 참여자의 정보를 반환하는 API에 대하여 열람자 (type = VIEWER)에 대한 응답값이 추가됩니다.

{
  "type": "VIEWER",
  ...
  "manuallyViewing": true // 상세 열람 여부, 열람자인 경우에만 반환됩니다.
}

이용하시는 API Reference를 참고 부탁드립니다.

🌐 Webhook 이벤트 변경사항

열람 문서의 이벤트도 기존 이벤트와 같이 통합되어 발송됩니다.
상세한 내용은 Webhook event 를 참고 부탁드립니다.

🏷️ 라벨 수정 / 삭제 API 추가

서명 요청 시 문서 분류를 위해 적용하는 라벨을 수정하고 삭제할 수 있도록

라벨 수정 API 와 라벨 삭제 API 가 추가되었습니다

📘

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

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

🔖 문서에 라벨 추가 / 문서에서 라벨 제거 API 추가

문서에 설정된 라벨을 제거하거나, 다른 라벨을 추가할 수 있도록 문서에 라벨 추가 API와 문서에서 라벨 제거 API 가 업데이트되었습니다.

지금까지 서명 요청 시 라벨을 설정할 수 있지만, 서명 요청 후 설정된 라벨을 제거하거나 추가할 수 있는 API가 없어 라벨을 통한 문서 관리에 어려움이 있었습니다.

추가되는 API를 활용해 문서에 라벨을 설정 및 관리할 수 있도록 개선하여 효율적인 문서 관리가 될 수 있도록 기대합니다 🙏

한 문서 당 적용할 수 있는 라벨의 개수는 최대 30개로 제한됩니다.