여러 개의 템플릿 또는 파일을 하나의 임시 템플릿으로 합치는 병합 API(POST /templates/merge)의 동작 규칙입니다. 병합된 임시 템플릿으로 곧바로 서명·열람 요청을 보낼 수 있어, 매번 새 템플릿을 만들지 않고도 여러 문서를 조합해 발송할 수 있습니다.

전체 흐름

소스를 준비해 병합 API로 보내면, 하나의 임시 템플릿이 만들어지고 그 ID로 서명·열람 요청을 보냅니다. 아래 흐름도에서 파랑은 서버·API 처리 단계, 민트는 사용자 화면·완료 단계를 의미합니다.

1. 소스 준비 — 병합할 템플릿 ID를 확인하거나, 파일을 파일 업로드 API로 올려 fileId·token을 받습니다. (2~12개)
2. POST /templates/merge — sources 배열에 소스를 순서대로 담아 병합을 요청합니다.
3. 임시 템플릿 생성 — 병합 규칙에 따라 하나의 임시 템플릿이 생성됩니다. (유효기간 2시간)
4. 서명/열람 요청 — 생성된 임시 템플릿 ID로 POST /documents/request-with-template를 호출해 요청을 보냅니다.

1. 병합 요청 방법

sources 배열에 병합할 소스를 순서대로 담아 요청합니다. 배열의 순서가 PDF 페이지 순서이자 설정 우선순위입니다.

curl -X POST 'https://api.modusign.co.kr/templates/merge' \
  -H 'Authorization: Basic {인코딩된 API-KEY}' \
  -H 'Content-Type: application/json' \
  -d '{
    "sources": [
      { "type": "TEMPLATE", "templateId": "TEMPLATE_ID_1" },
      { "type": "TEMPLATE", "templateId": "TEMPLATE_ID_2" }
    ]
  }'

소스 종류

소스는 type에 따라 두 가지입니다.

TEMPLATE 소스에는 선택 항목으로 identifier(최대 8자)를 넣을 수 있습니다. 각 소스의 하위 리소스를 구분하기 위해 dataLabel의 접미사로 사용되며, 미입력 시 templateId 앞 8자로 대체됩니다.

응답 예시

병합에 성공하면 생성된 임시 템플릿 정보가 반환됩니다. 반환된 id를 서명·열람 요청의 templateId로 사용하세요.

{
  "id": "MERGED_TEMPLATE_ID",
  "title": "가장 앞 소스의 제목",
  "createdAt": "2026-07-14T00:00:00.000Z",
  "updatedAt": "2026-07-14T00:00:00.000Z"
}

2. 핵심 규칙

병합 결과는 다음 규칙에 따라 결정됩니다.

앞 소스 우선 원칙

아래 항목들은 소스에 템플릿이 포함되어 있는지 여부에 따라 적용되는 값이 달라집니다.

서명자 병합

서로 다른 소스의 서명자가 동일 인물인지 판단하여, 동일하면 병합, 아니면 별도로 유지합니다. 서명자를 role → name → contact 순으로 비교해 3개 속성이 모두 일치하면 병합하며, 병합된 서명자의 설정은 앞 소스의 값을 따릅니다.

하나라도 불일치하면 분리합니다. 분리 시 앞 소스의 서명자는 원본 역할을 유지하고, 뒤 소스의 서명자부터 - 1, - 2 접미사가 붙습니다.

병합된 서명자의 설정 규칙은 다음과 같습니다.

병합되지 않은 서명자들 간에 역할명이 같으면, 첫 번째 서명자는 원본 역할을 유지하고 이후 중복되는 서명자부터 순서대로 역할에 - {숫자}가 붙습니다. (예: 근로자, 근로자 - 1, 근로자 - 2)

서명자 순서 결정 — 서명자를 가진 소스 중 가장 앞 소스가 순서 있는 서명(ordered signing)이면 소스 순서대로 서명 순서가 부여됩니다. (예: 템플릿 A(갑, 을, 병) + 템플릿 B(을, 무, 기) → 갑, 을, 병, 무, 기. "을"은 동일 인물로 병합) 가장 앞 소스가 순서 없는 서명(unordered signing)이면 서명 순서는 모두 1로 설정됩니다.

DataLabel 자동 변환

병합 전 템플릿의 데이터별 dataLabel을 시스템이 자동 변환하여 중복 가능성을 최소화합니다.

• 모든 소스의 dataLabel이 변환 대상입니다.
• 변환 형식: {기존_dataLabel}_{템플릿_제목}_{템플릿_ID_앞_8자리} (identifier를 지정하면 앞 8자리 대신 사용됩니다.)
• dataLabel 최대 길이: 100글자

각 구성 요소의 축약 규칙은 다음과 같습니다.

3. 상세 규칙

열람자 병합

열람자를 가진 소스 중 가장 앞에 있는 소스의 열람자를 사용합니다.

필드(Field) 처리

각 소스의 필드 위치(position.page)는 병합된 PDF의 페이지 오프셋에 맞게 자동 재계산됩니다. x, y 좌표(상대값 0~1)는 변경되지 않습니다.

서명자가 병합된 경우, 뒤 소스의 서명 필드는 다음과 같이 조정됩니다.

필드 그룹(Field Group) 처리

첨부파일(Attachment) 처리

인증수단(Verification) 처리

4. 주의사항

• 임시 템플릿 유효기간(TTL)은 2시간입니다. 만료된 템플릿으로 서명 요청 시 404 Not Found가 발생할 수 있습니다.
• 동일 임시 템플릿 ID로 유효기간 내 복수 서명 요청이 가능합니다. (각각 별개의 문서 생성)
• PDF 페이지 순서는 sources 배열 순서를 따릅니다.
• 소스는 최소 2개, 최대 12개까지 지정할 수 있습니다.
• 파일 소스는 파일 업로드 API로 올린 fileId·token을 사용하세요.

병합 실패 조건

아래 조건에 해당하면 병합이 실패합니다.

5. 자주 묻는 질문

FAQ

{
  "statusCode": 422,
  "message": "Validation failed"
}