템플릿 병합 (Template Merge)

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

💡
병합 API로 생성된 임시 템플릿은 2시간 동안 유효합니다.
만료 전에 서명 요청을 발송해 주세요. 만료된 템플릿으로 요청 시 404 Not Found가 반환됩니다.

사용 흐름

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

적용 API

엔드포인트	메서드	설명
`/templates/merge`	POST	임시 템플릿 생성

단계	설명
소스 준비	`TEMPLATE` 소스: 템플릿 생성 API로 생성한 템플릿 ID를 사용합니다. `FILE` 소스: 파일 업로드 API로 `fileId`와 `token`을 발급받습니다.
병합	`POST /templates/merge`에 준비한 소스들을 전달합니다. 응답의 `id`가 임시 템플릿 ID이며, 생성 후 2시간 동안 유효합니다.
서명 요청	임시 템플릿 ID를 템플릿으로 서명 요청 API의 `templateId`에 전달합니다.

사용 방법

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

기존에 생성된 템플릿 ID를 소스로 사용합니다.

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

요청 파라미터

공통

파라미터	타입	필수	설명
`sources`	`array`	Y	병합할 소스 목록. 최소 2개, 최대 12개

TEMPLATE 소스

파라미터	타입	필수	설명
`type`	`"TEMPLATE"`	Y	소스 타입
`templateId`	`string`	Y	템플릿 ID

FILE 소스

파라미터	타입	필수	설명
`type`	`"FILE"`	Y	소스 타입
`fileId`	`string`	Y	파일 업로드 API로 얻은 파일 ID
`token`	`string`	Y	파일 업로드 API로 얻은 토큰
`participants`	`array`	N	`POST /templates`와 동일 구조. 기본값 `[]`
`requesterInputs`	`array`	N	`POST /templates`와 동일 구조. 기본값 `[]`
`requesterAttachments`	`array`	N	`POST /templates`와 동일 구조. 기본값 `[]`

응답 (201 Created)

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

필드	타입	설명
`id`	`string`	임시 템플릿 ID
`expiredAt`	`datetime`	만료 시각 (생성 후 2시간)
`title`	`string`	가장 앞 템플릿의 제목 (파일만인 경우 자동 생성)
`participants`	`array`	병합된 참여자 목록
`requesterInputs`	`array`	병합된 요청자 입력란
`requesterAttachments`	`array`	병합된 요청자 첨부파일
`file`	`object`	병합된 PDF (`downloadUrl` 포함)
`documentLabels`	`array`	가장 앞 템플릿의 라벨
`seal`	`object`	가장 앞 템플릿의 진본증명도장 설정

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

role — 역할이 동일하지만 병합되지 않은 서명자가 존재할 경우, 뒤 소스의 서명자부터 을 - 1, 을 - 2 형태로 접미사가 추가됩니다.

dataLabel — 소스 간 중복 시 {dataLabel}_{템플릿_제목}_{템플릿_ID_앞_8자리} 형식으로 자동 변환됩니다. (최대 100자)

병합 규칙

기준 소스 우선 적용

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

항목	소스에 템플릿이 있는 경우	소스에 템플릿이 없는 경우 (파일만)
제목	가장 앞 템플릿의 제목	`임시_템플릿_{날짜}`
문서 라벨	가장 앞 템플릿의 라벨	빈 배열
진본증명도장(seal)	가장 앞 템플릿의 설정	비활성화
외부 참조자(carbonCopies)	가장 앞 템플릿의 값	빈 배열
결재선	모든 소스가 동일해야 병합 가능	빈 값

서명자 병합

서로 다른 소스의 서명자를 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개를 초과하는 경우