템플릿 병합 (Template Merge)

여러 개의 템플릿 또는 파일을 하나의 임시 템플릿으로 병합하며, 병합된 임시 템플릿으로 서명 요청을 발송할 수 있습니다.

💡

병합 API로 생성된 임시 템플릿은 2시간 동안 유효합니다.

만료 전에 서명 요청을 발송해 주세요. 만료된 템플릿으로 요청 시 404 Not Found가 반환됩니다.

사용 흐름

템플릿 병합 API는 소스 준비 → 병합 → 서명 요청 흐름의 병합 단계를 담당합니다.

적용 API

사용 방법

sources 배열에 병합할 소스를 순서대로 전달합니다. 최소 2개, 최대 12개까지 지정할 수 있습니다.

{
  "sources": [
    { "type": "TEMPLATE", "templateId": "templateId-1" },
    { "type": "TEMPLATE", "templateId": "templateId-2" }
  ]
}

요청 파라미터

공통

TEMPLATE 소스

FILE 소스

응답 (201 Created)

GET /templates/{id} 응답과 동일한 구조에 expiredAt 필드가 추가됩니다.

⚠️

병합 과정에서 role과 dataLabel이 원본과 달라질 수 있습니다. 서명 요청 시 반드시 병합 응답의 값을 사용하세요.

• role — 역할이 동일하지만 병합되지 않은 서명자가 존재할 경우, 뒤 소스의 서명자부터 을 - 1, 을 - 2 형태로 접미사가 추가됩니다.
• dataLabel — 소스 간 중복 시 {dataLabel}_{템플릿_제목}_{템플릿_ID_앞_8자리} 형식으로 자동 변환됩니다. (최대 100자)

병합 규칙

기준 소스 우선 적용

가장 앞에 위치한 템플릿의 설정값이 최종 템플릿에 적용됩니다.

서명자 병합

서로 다른 소스의 서명자를 role → name → contact 순으로 비교하여 3가지 속성이 모두 일치하면 병합, 하나라도 불일치하면 분리합니다. 분리 시 뒤 소스의 서명자부터 - 1, - 2 접미사가 추가됩니다.

DataLabel 자동 변환

소스 간 중복된 dataLabel이 존재하면 {dataLabel}_{템플릿_제목}_{템플릿_ID_앞_8자리} 형식으로 자동 변환됩니다.

자세한 병합 규칙은 템플릿 병합 규칙을 참조하세요.

주의사항

• 임시 템플릿 TTL: 2시간. 만료된 템플릿으로 서명 요청 시 404 Not Found가 발생할 수 있습니다.
• 동일 임시 템플릿 ID로 유효기간 내 복수 서명 요청 가능합니다. (각각 별개 문서 생성)
• PDF 페이지 순서는 sources 배열 순서를 따릅니다.

병합 제한

⚠️

병합 실패 조건

설정 관련

• 설정 고정 템플릿을 병합하는 경우
• 서명용 템플릿과 열람용 템플릿을 병합하는 경우
• 모든 소스의 결재선이 동일하지 않은 경우

파일 크기

• 병합된 문서 파일의 크기가 10MB를 초과하는 경우

필드 및 참여자 수

• 서명자 수가 30명을 초과하는 경우
• 전체 입력란이 2,000개를 초과하는 경우
• 서명 필드가 100개를 초과하는 경우
• 이미지 필드가 7개를 초과하는 경우
• 드롭다운 필드가 100개를 초과하는 경우
• 첨부파일이 30개를 초과하는 경우

사전 입력(Prefilled Value) 기능 및 신규 필드 타입

문서 생성, 임베디드 초안 생성, 템플릿 생성 시 필드에 사전 입력값(prefilledValue)을 설정할 수 있습니다. 서명 참여자가 서명 화면에 진입했을 때, 미리 입력된 값이 해당 필드에 표시됩니다.

💡

사전 입력값은 참여자가 서명 시 직접 수정할 수 있습니다. 초기값을 자동으로 채워주는 용도로 활용하세요.

적용 API

다음 엔드포인트에서 prefilledValue 파라미터를 사용할 수 있습니다.

신규 필드 타입

POST /documents 및 POST /documents/embedded API에서 다음 필드 타입을 새로 지원합니다.

지원 필드 타입 및 prefilledValue 형식

⚠️

NAME, SIGNING_DATE, SIGNATURE, IMAGE 필드 타입은 사전 입력(prefilledValue)을 지원하지 않습니다.

사용 방법

문서 생성 시 사전 입력값 설정

POST /documents 요청의 participants[].fields[] 객체에 prefilledValue를 추가합니다.

{
  "type": "TEXT",
  "dataLabel": "text-field-1",
  "prefilledValue": "가나다라마",
  "size": { "width": 0.2, "height": 0.05 },
  "position": { "x": 0.1, "y": 0.3, "page": 1 },
  "textStyle": { "fontSize": 14, "fontType": "NOTO_SANS_KR", "align": "LEFT" }
}

{
  "participants": [
    {
      "role": "SIGNER",
      "fields": [
        {
          "type": "TEXT",
          "dataLabel": "text-field-1",
          "prefilledValue": "가나다라마",
          "size": { "width": 0.2, "height": 0.05 },
          "position": { "x": 0.1, "y": 0.3, "page": 1 },
          "textStyle": { "fontSize": 14, "fontType": "NOTO_SANS_KR", "align": "LEFT" }
        },
        {
          "type": "CHECKBOX",
          "dataLabel": "agree-terms",
          "prefilledValue": true,
          "size": { "width": 0.03, "height": 0.03 },
          "position": { "x": 0.1, "y": 0.4, "page": 1 }
        },
        {
          "type": "DATE",
          "dataLabel": "contract-date",
          "prefilledValue": "2026-03-30",
          "displayFormat": "YYYY-MM-DD",
          "size": { "width": 0.15, "height": 0.05 },
          "position": { "x": 0.1, "y": 0.5, "page": 1 },
          "textStyle": { "fontSize": 14, "fontType": "NOTO_SANS_KR", "align": "LEFT" }
        },
        {
          "type": "DROPDOWN",
          "dataLabel": "department",
          "prefilledValue": "영업팀",
          "options": [
            { "value": "영업팀" },
            { "value": "개발팀" },
            { "value": "인사팀" }
          ],
          "size": { "width": 0.15, "height": 0.05 },
          "position": { "x": 0.1, "y": 0.6, "page": 1 },
          "textStyle": { "fontSize": 14, "fontType": "NOTO_SANS_KR", "align": "LEFT" }
        },
        {
          "type": "ADDRESS",
          "dataLabel": "home-address",
          "prefilledValue": {
            "address1": "서울특별시 강남구 테헤란로 123",
            "address2": "4층",
            "city": "강남구",
            "province": "서울특별시",
            "zip": "06234",
            "country": "KR"
          },
          "size": { "width": 0.3, "height": 0.05 },
          "position": { "x": 0.1, "y": 0.7, "page": 1 },
          "textStyle": { "fontSize": 14, "fontType": "NOTO_SANS_KR", "align": "LEFT" }
        }
      ]
    }
  ]
}

템플릿 기반 문서 생성 시 사전 입력값 오버라이드

POST /documents/with-template 요청 시 participantFieldMappings[].prefilledValue를 사용하면, 템플릿에 미리 설정된 사전 입력값을 문서 생성 시점에 덮어쓸 수 있습니다.

{
  "templateId": "template-uuid",
  "participantMappings": [
    {
      "role": "SIGNER",
      "participantFieldMappings": [
        {
          "dataLabel": "text-field-1",
          "excluded": false,
          "prefilledValue": "하나둘셋넷"
        }
      ]
    }
  ]
}

📘

dataLabel은 템플릿에 정의된 필드의 라벨과 정확히 일치해야 합니다. excluded를 true로 설정하면 해당 필드가 문서에서 제외됩니다.

ADDRESS 필드의 prefilledValue 구조

ADDRESS 타입의 prefilledValue는 다음 속성을 가진 객체입니다.

참여자 필드 조회 응답 개선

GET /documents/{documentId}/participant-fields 응답 동작이 다음과 같이 개선되었습니다.

⚠️

만료(expiredAt)된 서명은 서명 완료로 간주하지 않습니다. 만료된 참여자의 필드는 기본값을 반환합니다.

Anchor 기반 필드 자동 배치

API 연동을 통해 가변 문서에 대해서도 수동 좌표 설정 없이 간편하게 서명 준비를 할 수 있게 되었습니다. PDF 등의 문서 내 특정 텍스트를 앵커로 지정하면, 서명/텍스트 입력란이 해당 위치에 자동으로 생성됩니다.

적용 API

사용 방법

필드 생성 시 기존 position의 좌표(x, y, page) 대신 position.anchor 속성을 사용하여 텍스트 기반 위치를 지정합니다.

{
  "type": "TEXT",
  "position": {
    "anchor": {
      "text": "이름",
      "offset": {
        "x": 0.01,
        "y": 0.005
      }
    }
  },
  "size": {
    "width": 0.2,
    "height": 0.05
  }
}

Anchor 파라미터

position.anchor 객체의 구조는 다음과 같습니다.

필드 크기는 기존과 동일하게 size 객체로 지정합니다.

지원 필드 타입

⚠️

주의사항

• position에 좌표(x, y, page)와 anchor를 동시에 지정할 수 없습니다. 둘 중 하나만 사용하세요.
• 둘 다 지정하면 유효성 검사 오류가 발생합니다.
• 문서 내에 지정한 텍스트가 없으면 AnchorTextNotFoundException (404) 오류가 발생합니다.

진본증명도장 (Integrity Seal)

완료된 문서에 진본증명도장을 삽입하여 문서의 무결성을 보장할 수 있습니다. Seal > IntegritySeal 설정을 통해 도장 삽입 여부와 위치를 지정합니다.

사전 설정 안내

❗️

워크스페이스 설정 필수

진본증명도장을 사용하려면 워크스페이스 최고관리자가 먼저 기능을 활성화해야 합니다.

설정 경로: 모두싸인 로그인 → 설정 > 문서 → 진본증명도장 활성화

활성화하지 않은 상태에서 API 호출 시, 지정한 옵션이 무시되고 비활성화 상태로 발송됩니다.

도장 삽입 시점

🚧

진본증명도장의 삽입 시점을 주의해주세요

진본증명도장은 문서가 완료(status = COMPLETED)된 시점에 삽입됩니다.

요청 예시

{
  "document": {
    "title": "계약서",
    "file": "base64_encoded_file"
  },
  "seal": {
    "integritySeal": {
      "enabled": true,
      "position": "TOP_LEFT"
    }
  }
}

지원 API

진본확인도장은 다음 API에서 사용할 수 있습니다.

• 서명 요청 API
• 템플릿으로 서명 요청 API
• 임베디드 초안 생성 API
• 템플릿으로 임베디드 초안 생성 API
• 문서 상세 조회 API
• 템플릿 정보 가져오기 API

주의 사항

🚧

PDF 1페이지에만 삽입됩니다

진본확인도장은 완료된 문서 PDF의 1페이지에 지정한 위치(좌상단, 우상단, 좌하단, 우하단)에 삽입됩니다. 삽입 위치에 따라 문서 본문 일부가 가려질 수 있으므로, 문서 레이아웃을 미리 확인하시기 바랍니다.

🚧

디지털 서명 형태로 삽입됩니다

진본확인도장은 PDF에 디지털 서명 형태로 삽입됩니다. 디지털 서명을 올바르게 처리하지 않는 일부 PDF 뷰어나 라이브러리에서는 도장이 정상적으로 표시되지 않을 수 있습니다. 사용 환경에 맞는 호환성을 사전에 확인하시기 바랍니다.

FAQ

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

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

📘

새로운 파라미터 추가: 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": "01KAAJ7MYW5V0P724K9E6MM7FJAE"
}

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

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

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