✨ 템플릿 및 서명 요청 시 참조자(Carbon Copy) 필드 지원
이번 업데이트에서는 템플릿 생성 시 참조자(Carbon Copy)를 사전 등록하고, 서명 요청 시 참조자 정보를 템플릿과 병합하여 전송할 수 있도록 개선되었습니다.
1. 템플릿 생성 API (POST /templates
)
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
)
⚠️ 제한 사항
- carbonCopies 병합 후 총 인원이 30명을 초과할 경우 오류
- locale을 생략하면 기본값으로 “ko” (한국어) 가 적용됨
📝 템플릿으로 서명 요청 시 서명자의 일부 필드 제거 기능 추가
템플릿으로 서명 요청 API와 템플릿으로 임베디드 초안 생성 API에서 서명 요청 시 서명자의 일부 필드를 제거하여 전송할 수 있도록 participantMappings
하위에 fieldMappings
를 설정할 수 있도록 제공됩니다.
fieldMappings
에 데이터 라벨, 제외 여부를 설정하실 수 있으며, 만약 데이터라벨을 그룹의 데이터라벨로 지정할 경우, 그룹에 속한 모든 필드가 제거되니 주의하여 사용해주십시오.
필드를 제거하여 요청할 수 없는 경우는 아래와 같습니다.
- 템플릿이 설정 고정 템플릿인 경우
- 설정한 데이터라벨이 자동 완성 필드의 그룹 ID인 경우
- 설정한 데이터라벨이 체크박스 그룹의 하위 체크박스인 경우
📌 설정 고정 템플릿 정보 추가
수정불가 템플릿은 템플릿의 설정을 요청자가 임의로 수정하여 서명 요청을 보낼 수 없도록 설정된 템플릿입니다.
모두싸인 웹사이트, 임베디드 템플릿 생성 및 임베디드 템플릿 수정 기능에서 템플릿을 설정 고정 상태로 지정할 수 있습니다.
이에 맞추어 템플릿을 활용하여 서명 요청을 진행하는 아래 엔드포인트들에 대하여, 설정 고정 상태의 템플릿이라면 템플릿에 설정된 정보를 제외하거나 변경하여 서명 요청할 수 없도록 제한이 추가됩니다.
위 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 상태를 나타내는 헤더 정보가 포함됩니다. 이를 통해 현재 사용 가능한 요청 횟수와 제한 관련 정보를 확인할 수 있습니다.
응답 헤더 | 설명 | 예시 값 |
---|---|---|
X-RateLimit-Limit | 해당 엔드포인트의 최대 허용 요청 수 | 600 |
X-RateLimit-Remaining | 현재 남은 요청 가능 횟수 | 400 |
X-RateLimit-Reset | Rate Limit이 초기화되는 시간(Unix 타임스탬프) | 1620235582 |
X-Retry-After | 요청을 다시 시도하기 전에 기다려야 하는 시간(초) 형식 | 35 |
대부분의 API는 분당 600회의 요청 제한이 적용되지만, 다음 API 목록은 분당 300회의 요청 제한이 적용됩니다. 제한 횟수를 초과하면 HTTP 429 (Too Many Requests) 오류가 발생하니 유의하시기 바랍니다.
요청 제한 초과 시 HTTP 429(Too Many Requests) 상태 코드와 함께 X-Retry-After 헤더가 반환됩니다.
[API Rate Limit 정책 안내] 를 참고하여 요청 제어 및 Retry 정책 등을 준비해주세요.
API | Method | Endpoint |
---|---|---|
문서 리스트 조회 | GET | /documents |
서명 요청 | POST | /documents |
템플릿으로 서명 요청 | POST | /documents/request-with-template |
템플릿으로 임베디드 초안 생성 | POST | /embedded-drafts/create-with-template |
템플릿 생성 | POST | /templates |
파일 업로드 | POST | /files |
📃 열람 요청 기능 추가
열람 요청 주의사항 안내
- 열람 문서는 계약의 효력을 가지지 않습니다. 계약의 효력과 무관한 통지서, 고지서, 확인서, 내역서와 같은 단순 열람 문서를 전송하시는데에 활용하실 수 있습니다.
- 열람용 템플릿의 역할은 일반 템플릿과 다르게 "열람자" 로 고정되어 설정됩니다.
문서 발송 시 참고 부탁드립니다.- 열람 문서는 기본 설정값으로, 열람자가 문서에 접근할 경우 열람 완료 상태로 자동으로 전환됩니다.
- 이를 원치 않으신다면, 열람용 템플릿의 "상세 열람 후 완료 클릭" 설정을 활성화하여 열람자가 문서 내용을 모두 확인 후 수동으로 열람 완료로 전환되도록 설정할 수 있습니다.
열람 문서와 서명 요청과의 서로 다른 차이점, 제한 사항들은 고객센터 > 문서 열람 요청 방법에서 자세히 확인하실 수 있습니다.
📤 열람 요청 문서 전송 기능 추가
아래 API들에 대하여 열람 요청 템플릿을 통해 열람 문서를 전송할 수 있습니다.
자세한 내용은 템플릿으로 열람 요청하기를 참고 부탁드립니다.
👀 열람자에 대한 참여자 응답값 추가
문서 상세 조회와 같이 참여자의 정보를 반환하는 API에 대하여 열람자 (type = VIEWER
)에 대한 응답값이 추가됩니다.
{
"type": "VIEWER",
...
"manuallyViewing": true // 상세 열람 여부, 열람자인 경우에만 반환됩니다.
}
이용하시는 API Reference를 참고 부탁드립니다.
🌐 Webhook 이벤트 변경사항
열람 문서의 이벤트도 기존 이벤트와 같이 통합되어 발송됩니다.
상세한 내용은 Webhook event 를 참고 부탁드립니다.
🏷️ 라벨 수정 / 삭제 API 추가
서명 요청 시 문서 분류를 위해 적용하는 라벨을 수정하고 삭제할 수 있도록
라벨 수정 API 와 라벨 삭제 API 가 추가되었습니다
기존 폴더 기능이 라벨로 대체기존에 사용하던 폴더 기능이 라벨로 대체 되며 폴더 관련 속성들은 일정 기간이 지난 후 제거 됩니다.
라벨 기능이 궁금하시면 "라벨을 만들어 분류하기" 를 참고해주세요
🔖 문서에 라벨 추가 / 문서에서 라벨 제거 API 추가
문서에 설정된 라벨을 제거하거나, 다른 라벨을 추가할 수 있도록 문서에 라벨 추가 API와 문서에서 라벨 제거 API 가 업데이트되었습니다.
지금까지 서명 요청 시 라벨을 설정할 수 있지만, 서명 요청 후 설정된 라벨을 제거하거나 추가할 수 있는 API가 없어 라벨을 통한 문서 관리에 어려움이 있었습니다.
추가되는 API를 활용해 문서에 라벨을 설정 및 관리할 수 있도록 개선하여 효율적인 문서 관리가 될 수 있도록 기대합니다 🙏
한 문서 당 적용할 수 있는 라벨의 개수는 최대 30개로 제한됩니다.
📂 문서 리스트 조회시 작성 중 상태, 문서 요청일 필터링 추가
- 문서 리스트 조회 API 필터의
status
에DRAFT
로 작성 중 상태인 문서만 검색할 수 있습니다. - 문서 리스트 조회 API 필터의
startedAt
을 통해 문서 요청일 기준으로 조건에 해당하는 문서를 검색할 수 있습니다.
filter로 검색하기filter로 검색하기가 어떤 기능인지 궁금하신 분은 filter로 검색하기를 확인해 보세요.
🏷️ 라벨 생성 / 목록 조회 API 추가
서명 요청 시 문서를 분류하기 위해 적용하는 라벨을 생성하고 라벨의 목록을 조회할 수 있도록
라벨 생성 API 와 라벨 목록 조회 API 가 추가되었습니다
기존 폴더 기능이 라벨로 대체기존에 사용하던 폴더 기능이 라벨로 대체 되며 폴더 관련 속성들은 일정 기간이 지난 후 제거 됩니다.
라벨 기능이 궁금하시면 "라벨을 만들어 분류하기" 를 참고해주세요
✅ 보안 링크 서명자의 "서명 내용 수정 요청" 기능 지원 및 참조자 인원수 증가
1. 보안 링크 서명자의 "서명 내용 수정 요청" 기능 지원
v1.26.0 에 추가된 서명 내용 수정 요청 API는 보안 링크 서명자를 지원하지 않았는데 이를 개선합니다. 기존에 "Secure link signing method is not supported" 에러 메세지로 422 응답이 반환됐던 부분이 제거됐습니다.
2. 참조자 최대 인원수 30명으로 증가
기존에 최대 10명까지 지원했던 참조자 최대 인원수가 30명까지 지원하도록 개선됐습니다.
아래는 영향을 받는 API 목록입니다.