"간편인증(통합인증) 기능 추가"

서명 요청 및 임베디드 초안 생성 시 다양한 모바일 인증 수단을 선택적으로 제공할 수 있는 기능이 추가되었습니다.

📘

새로운 파라미터 추가: verification.mobileIdentification.allowOptions

이 파라미터를 통해 서명자에게 제공할 인증 수단을 직접 제어할 수 있습니다. 기존 API 요청은 수정 없이 계속 사용 가능하며, allowOptions를 별도로 설정하지 않으면 자동으로 ["SMS_OR_PASS"]가 기본값으로 적용됩니다.

주요 변경사항

기존에는 인증 수단이 고정되어 있었으나, 이제 allowOptions 파라미터를 통해 제공할 인증 방식을 선택할 수 있습니다.

요청 형식

{
  "verification": {
    "mobileIdentification": {
      "name": "김모두",
      "phoneNumber": "01012345678",
      "allowOptions": ["SIMPLE_AUTH", "SMS_OR_PASS"]
    }
  }
}

파라미터 상세

verification.mobileIdentification

allowOptions 설정 값

"allowOptions": ["SIMPLE_AUTH"]

적용 가능한 API

이 기능은 다음 엔드포인트에서 사용할 수 있습니다:

브랜드 옵션 추가: 서명 요청 및 임베디드 초안 생성

서명 요청 및 임베디드 초안 생성 API에서 브랜드 선택 옵션을 지원합니다. 이제 API 호출 시 brandId 파라미터를 통해 특정 브랜드를 지정할 수 있습니다.

주요 변경 사항

요청 본문(Request Body)에 brandId 필드를 추가하여 원하는 브랜드를 지정할 수 있습니다.

{
  "brandId": "brandId_sample"
   ...,
}

브랜드 ID 획득 경로

앱 서비스 맞춤 브랜딩에 각 브랜드별 상세 페이지에서 ID를 확인할 수 있습니다.

1. 앱 서비스 접속
2. 설정 > 맞춤 브랜딩 메뉴 선택
3. 각 브랜드 상세 페이지에서 ID 확인

🚧

현재 OpenAPI로 브랜드 목록을 제공하고 있지는 않습니다.

적용 API 목록

이번 업데이트는 다음 4개의 API 엔드포인트에 적용됩니다:

POST /documents
Content-Type: application/json

{
    "file": {
      "fileId": "fileId",
      "token": "token"
  },
  "participants": [...],
  "brandId": "e157d5a2-2364-4e61-bb49-55434e4d235a"
}

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

임베디드 서명 요청 시 파일 병합 후 서명 요청 할 수 있도록 프로세스가 개선 되었습니다. 이와 관련 해 기존 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 정책 등을 준비해주세요.