--- title: "템플릿/문서 병합" method: POST path: "/templates/merge" tags: ["USER API"] --- # 템플릿/문서 병합 `POST /templates/merge` 여러 개의 템플릿 또는 파일을 하나의 임시 템플릿으로 병합하는 API입니다. 생성된 템플릿의 pdf 페이지는 요청의 sources 순서대로 병합됩니다. sources 중 첫 번째 요소가 기준이 되어, 정해진 [병합 규칙](https://developers.modusign.co.kr/docs/%ED%85%9C%ED%94%8C%EB%A6%BF-%EB%B3%91%ED%95%A9-%EA%B7%9C%EC%B9%99)을 바탕으로 데이터들이 병합됩니다. **기타 정보:** - 유효기간: 2시간 ## Request body - MergeTemplatesRequestDto - `sources` union[], required — 병합 소스 목록 - union - TemplateSourceInMergeTemplatesRequestDto - `type` 'TEMPLATE', required — 소스 타입 - `templateId` string, required — 템플릿 ID - `identifier` string — 소스별 커스텀 식별자. 각 소스별 하위 리소스를 구분하기 위해 dataLabel의 postfix로 사용됩니다. 미입력 시, templateId 앞 8자로 대체됩니다. - FileSourceInMergeTemplatesRequestDto - `type` 'FILE', required — 소스 타입 - `fileId` string, required — 파일 업로드 API를 통해 얻은 파일 ID - `token` string, required — 파일 업로드 API를 통해 얻은 파일 토큰 - `participants` ParticipantInTemplateRequestDto[] — 문서의 참여자 정보 - `type` 'SIGNER' | 'VIEWER' — 참여자 타입 - `role` string, required — 참여자의 역할 - `name` string — 참여자 이름 (특수문자 /?<>\":*|₩ 이 포함된 이름은 사용할 수 없습니다) - `signingOrder` integer, required — 참여 순서. 순서 없이 참여하려면 모두 1로 설정하세요. - `signingMethod` SigningMethodInTemplateRequestDto - `type` '' | 'KAKAO' | 'EMAIL' | 'SECURE_LINK', required — 참여 수단 종류 - `value` string, required — 참여자의 참여 수단 (이메일 또는 휴대전화번호) - `attachmentRequests` AttachmentRequestInTemplateRequestDto[] — 첨부파일 요청 정보 - `dataLabel` string — 데이터 라벨 - `name` string, required — 첨부파일 이름 (특수문자 /?<>\":*|₩ 이 포함된 이름은 사용할 수 없습니다) - `message` string, nullable — 첨부파일에 대한 설명 - `required` boolean, required — 필수 여부 - `fields` union[] — 문서 필드 정보 - VIEWER 타입 참여자는 필드를 가질 수 없습니다 - 참여자의 필드 개수 총합은 최대 2000개까지 지원합니다 - union - … - `checkboxFieldGroups` CheckboxGroupInTemplateRequestDto[] — 체크박스 그룹 - `groupLabel` string, required — 그룹 라벨 - `minCheckRequired` 0 | 1, required — 최소 선택 개수. 현재는 0 또는 1만 지원합니다. - `maxCheckLimit` integer, nullable — 최대 선택 개수. 현재는 1또는 null만 지원합니다. null은 최대 개수까지 선택가능함을 뜻합니다. - `verification` VerificationInCreateTemplateRequestDto - `password` PasswordInCreateTemplateRequestDto, required - … - `mobileIdentification` MobileIdentificationInCreateTemplateRequestDto, required - … - `dCert` DCertInCreateTemplateRequestDto, required - … - `requesterInputs` union[] — 요청자의 입력 (이미지의 개수는 최대 7개) - union - TextRequesterInputInTemplateRequestDto - … - CheckboxRequesterInputInTemplateRequestDto - … - ImageRequesterInputInTemplateRequestDto - … - DropdownRequesterInputInTemplateRequestDto - … - NameRequesterInputInTemplateRequestDto - … - `requesterAttachments` RequesterAttachmentInCreateTemplateRequestDto[] — 요청자 첨부파일 정보. 서명자 첨부파일과 합산하여 최대 30개까지 첨부 가능 - `name` string, required — 첨부파일 이름 (특수문자 /?<>\":*|₩ 이 포함된 이름은 사용할 수 없습니다) - `file` FileInfoInCreateTemplateRequestDto, required - `fileId` string, required — 파일 업로드 API 를 통해 얻은 파일 ID - `token` string, required — 파일 업로드 API 를 통해 얻은 파일 토큰 - `name` string, required — 첨부파일명 (확장자 제외, 특수문자 /?<>\":*|₩ 이 포함된 이름은 사용할 수 없습니다) ## Response `201` - MergeTemplatesResponseDto - `id` string, required — 템플릿의 ID - `metadatas` MetadataInTemplateResponseDto[], required — 메타데이터 리스트 - `key` string, required — 메타데이터 키 - `value` string, required — 메타데이터 값 - `title` string, required — 템플릿 제목 - `createdAt` string, date-time, required — 템플릿 생성 시간 - `updatedAt` string, date-time, required — 템플릿 마지막 업데이트 시간 - `file` TemplateFileInTemplateResponseDto - `downloadUrl` string, required — 다운로드 링크(유효시간: 10분) - `requesterInputs` union[], required — 템플릿에 적용된 추가내용 입력 - union - TextRequesterInputInTemplateResponseDto - `dataLabel` string, required — 데이터 라벨 - `type` string, required — 요청자 입력 타입 (예시 값으로 고정되어 있습니다) - `position` PositionInTemplateResponseDto, required - `x` number, required — 입력란의 가로 좌표 - `y` number, required — 입력란의 세로 좌표 - `page` integer, required — 입력란이 위치할 페이지 - `size` SizeInTemplateResponseDto, required - `width` number, required — 입력란의 너비 - `height` number, required — 입력란의 높이 - `textStyle` TextStyleInTemplateResponseDto, required - `size` integer, required — 텍스트 크기 - `font` string, required — 텍스트 글자체 - `align` string, required — 텍스트 정렬 - `value` string, required — 텍스트 박스에 들어갈 내용 - CheckboxRequesterInputInTemplateResponseDto - `dataLabel` string, required — 추가내용 입력의 데이터 라벨 - `type` string, required — 요청자 입력 타입 (예시 값으로 고정되어 있습니다) - `position` PositionInTemplateResponseDto, required - `x` number, required — 입력란의 가로 좌표 - `y` number, required — 입력란의 세로 좌표 - `page` integer, required — 입력란이 위치할 페이지 - `size` SizeInTemplateResponseDto, required - `width` number, required — 입력란의 너비 - `height` number, required — 입력란의 높이 - `value` boolean, required — 체크 박스의 체크 여부 - ImageRequesterInputInTemplateResponseDto - `dataLabel` string, required — 데이터 라벨 - `type` string, required — 추가내용 입력 타입 (예시 값으로 고정되어 있습니다) - `position` PositionInTemplateResponseDto, required - `x` number, required — 입력란의 가로 좌표 - `y` number, required — 입력란의 세로 좌표 - `page` integer, required — 입력란이 위치할 페이지 - `size` SizeInTemplateResponseDto - `width` number, required — 입력란의 너비 - `height` number, required — 입력란의 높이 - `value` ImageInfoInTemplateResponseDto - `downloadUrl` string, required — 이미지 다운로드 링크 (10분간 유효) - DropdownRequesterInputInTemplateResponseDto - `dataLabel` string, required — 데이터 라벨 - `type` string, required — 추가내용 입력 타입 (예시 값으로 고정되어 있습니다) - `position` PositionInTemplateResponseDto, required - `x` number, required — 입력란의 가로 좌표 - `y` number, required — 입력란의 세로 좌표 - `page` integer, required — 입력란이 위치할 페이지 - `size` SizeInTemplateResponseDto - `width` number, required — 입력란의 너비 - `height` number, required — 입력란의 높이 - `textStyle` TextStyleInTemplateResponseDto, required - `size` integer, required — 텍스트 크기 - `font` string, required — 텍스트 글자체 - `align` string, required — 텍스트 정렬 - `options` DropdownOption[], required — 드롭다운 옵션 - `value` string, required — 드롭다운 옵션 값 - `value` string, required — 드롭다운 필드에 들어갈 내용 - NameRequesterInputInTemplateResponseDto - `dataLabel` string, required — 데이터 라벨 - `type` string, required — 추가내용 입력 타입 (예시 값으로 고정되어 있습니다) - `position` PositionInTemplateResponseDto, required - `x` number, required — 입력란의 가로 좌표 - `y` number, required — 입력란의 세로 좌표 - `page` integer, required — 입력란이 위치할 페이지 - `size` SizeInTemplateResponseDto - `width` number, required — 입력란의 너비 - `height` number, required — 입력란의 높이 - `textStyle` TextStyleInTemplateResponseDto, required - `size` integer, required — 텍스트 크기 - `font` string, required — 텍스트 글자체 - `align` string, required — 텍스트 정렬 - `value` string, required — 이름 필드에 들어갈 내용 - `requesterAttachments` RequesterAttachmentInTemplateResponseDto[], required — 설정된 요청자 첨부파일 정보 - `dataLabel` string, required — 요청자 첨부파일의 데이터 라벨 - `name` string, required — 첨부파일 종류 - `file` RequesterAttachmentFileInTemplateResponseDto, required - `name` string, required — 파일명 - `extension` string, required — 파일 확장자 - `size` number, required — 파일 크기 (Byte) - `downloadUrl` string, required — 다운로드 링크(유효시간: 10분) - `participants` union[], required — 설정된 참여자 정보 - union - SignerInParticipantTemplateResponseDto - `type` 'SIGNER', required — 참여자 타입 - `role` string, required — 참여자의 역할 - `signingOrder` integer, required — 참여자의 서명/열람 순서 - `name` string — 참여자의 이름 (공란일 수 있음) - `signingMethod` SigningMethodInTemplateResponseDto - `type` 'EMAIL' | 'KAKAO' | 'SECURE_LINK' | 'IN_PERSON', required — 참여 수단 종류 - `value` string, required — 참여자의 참여 수단 (이메일 또는 휴대전화번호) - `attachmentRequests` AttachmentRequestInTemplateResponseDto[], required — 첨부파일 요청 정보 - `name` string, required — 첨부파일 종류 - `message` string, nullable — 추가 안내 사항 - `required` boolean, required — 필수 여부 - `dataLabel` string, required — 첨부파일의 데이터 라벨 - `fields` union[], required — 참여자 입력란 - union - SignatureFieldInTemplateResponseDto - … - TextFieldInTemplateResponseDto - … - CheckboxFieldInTemplateResponseDto - … - DropdownFieldInTemplateResponseDto - … - NameFieldInTemplateResponseDto - … - CompanyNameFieldInTemplateResponseDto - … - AddressFieldInTemplateResponseDto - … - DateFieldInTemplateResponseDto - … - SigningDateFieldInTemplateResponseDto - … - ImageFieldInTemplateResponseDto - … - `fieldGroups` union[], required — 참여자 입력란 그룹 - union - CheckboxFieldGroupInTemplateResponseDto - … - AutofillFieldGroupInTemplateResponseDto - … - `checkboxFieldGroups` DeprecatedCheckboxFieldGroupInTemplateResponseDto[], required — 체크박스 그룹 (deprecated 되었으며 fieldGroups를 대신 활용해주세요) - `groupLabel` string, required — 체크박스 그룹 라벨 - `minCheckRequired` number, required — 최소 선택 개수. 현재는 0 또는 1만 지원합니다. - `maxCheckLimit` number, nullable, required — 최대 선택 개수. 현재는 1또는 null만 지원합니다. null은 최대 개수까지 선택가능함을 뜻합니다. - `verification` VerificationInTemplateResponseDto, required - `password` ParticipantPasswordInTemplateResponseDto - `enabled` boolean, required — 추가 인증 사용 여부 - `mobileIdentification` ParticipantMobileIdentificationInTemplateResponseDto - `enabled` boolean, required — 추가 인증 사용 여부 - `dCert` ParticipantDCertInTemplateResponseDto - `enabled` boolean, required — 추가 인증 사용 여부 - ViewerInParticipantTemplateResponseDto - `type` 'VIEWER', required — 참여자 타입 - `role` string, required — 참여자의 역할 - `signingOrder` integer, required — 참여자의 서명/열람 순서 - `name` string — 참여자의 이름 (공란일 수 있음) - `signingMethod` SigningMethodInTemplateResponseDto - `type` 'EMAIL' | 'KAKAO' | 'SECURE_LINK' | 'IN_PERSON', required — 참여 수단 종류 - `value` string, required — 참여자의 참여 수단 (이메일 또는 휴대전화번호) - `attachmentRequests` AttachmentRequestInTemplateResponseDto[], required — 첨부파일 요청 정보 - `name` string, required — 첨부파일 종류 - `message` string, nullable — 추가 안내 사항 - `required` boolean, required — 필수 여부 - `dataLabel` string, required — 첨부파일의 데이터 라벨 - `fields` union[], required — 참여자 입력란 - union - SignatureFieldInTemplateResponseDto - … - TextFieldInTemplateResponseDto - … - CheckboxFieldInTemplateResponseDto - … - DropdownFieldInTemplateResponseDto - … - NameFieldInTemplateResponseDto - … - CompanyNameFieldInTemplateResponseDto - … - AddressFieldInTemplateResponseDto - … - DateFieldInTemplateResponseDto - … - SigningDateFieldInTemplateResponseDto - … - ImageFieldInTemplateResponseDto - … - `fieldGroups` union[], required — 참여자 입력란 그룹 - union - CheckboxFieldGroupInTemplateResponseDto - … - AutofillFieldGroupInTemplateResponseDto - … - `checkboxFieldGroups` DeprecatedCheckboxFieldGroupInTemplateResponseDto[], required — 체크박스 그룹 (deprecated 되었으며 fieldGroups를 대신 활용해주세요) - `groupLabel` string, required — 체크박스 그룹 라벨 - `minCheckRequired` number, required — 최소 선택 개수. 현재는 0 또는 1만 지원합니다. - `maxCheckLimit` number, nullable, required — 최대 선택 개수. 현재는 1또는 null만 지원합니다. null은 최대 개수까지 선택가능함을 뜻합니다. - `verification` VerificationInTemplateResponseDto, required - `password` ParticipantPasswordInTemplateResponseDto - `enabled` boolean, required — 추가 인증 사용 여부 - `mobileIdentification` ParticipantMobileIdentificationInTemplateResponseDto - `enabled` boolean, required — 추가 인증 사용 여부 - `dCert` ParticipantDCertInTemplateResponseDto - `enabled` boolean, required — 추가 인증 사용 여부 - `manuallyViewing` boolean, required — 상세 열람 여부 - `documentLabels` DocumentLabelInTemplateResponseDto[], required — 해당 템플릿으로 참여 요청 시 자동으로 적용될 라벨 목록 - `id` string, required — 라벨 ID - `name` string, required — 라벨 이름 - `description` string, nullable, required — 라벨의 설명 - `requesterEditable` boolean, required — 템플릿으로 서명 요청 시 문서의 내용이 변경 가능한 여부 (false 인 경우 기본적인 발송 설정을 제외한, 서명자 필드와 같은 데이터를 수정하여 발송할 수 없습니다) - `carbonCopies` CarbonCopyInTemplateResponseDto[], required — 참조자 정보 - `contact` string, required — 참조자 연락처 - `locale` 'ko' | 'en' | 'zh-CN' | 'ja' | 'vi', required — 참조자 언어 - `seal` DocumentSealInTemplateResponseDto, required - `integritySeal` IntegritySealInTemplateResponseDto, required - `enabled` boolean, required — 진본 증명 도장 활성화 여부 - `position` 'TOP_LEFT' | 'TOP_RIGHT' | 'BOTTOM_LEFT' | 'BOTTOM_RIGHT', required — 진본 증명 도장 위치 - `expiredAt` string, date-time, required — 임시 Template 만료 시각 (생성 후 2시간) ## Other responses - `404` — 템플릿 또는 결재선을 찾을 수 없음 (TemplateNotFoundException, ApprovalProcessNotFoundException) - `422` — 병합 규칙 위반 — source 수 범위 초과, 설정고정 템플릿, 결재선 불일치, 병합 검증 실패 등 --- [API](https://skmtc.net/modusign/apis/modusign-api.md) · [All operations](https://skmtc.net/modusign/apis/modusign-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/modusign/modusign-api/versions/5772e872cbf9/schema)