템플릿 병합 시 앵커 텍스트 기반 입력란 배치

템플릿 병합 API의 파일 소스에서도 앵커 텍스트를 이용해 입력란을 배치할 수 있습니다. 파일 내 특정 텍스트를 기준으로 서명 또는 텍스트 입력란이 생성되므로, 문서마다 위치 좌표를 직접 지정하지 않아도 됩니다.

적용 API

POST /templates/merge

사용 방법

FILE 타입 소스의 participants[].fields[]에서 기존 좌표(x, y, page) 대신 position.anchor를 지정합니다. TEXT, SIGNATURE 타입을 지원합니다.

다음은 파일 소스에 지정하는 서명 필드 예시입니다.

{
  "type": "SIGNATURE",
  "dataLabel": "서명",
  "position": {
    "anchor": {
      "text": "서명 위치",
      "offset": {
        "x": 0.01,
        "y": 0
      }
    }
  },
  "size": {
    "width": 0.15,
    "height": 0.08
  }
}

• text: 파일에서 찾을 기준 텍스트입니다.
• offset: 기준 텍스트에서 입력란 위치를 조정하는 선택 항목입니다.
• size: 배치할 입력란의 너비와 높이입니다.

참고 사항

• 기존 좌표 기반 배치도 계속 사용할 수 있습니다.
• 하나의 필드에서 좌표와 anchor를 동시에 지정할 수 없습니다.
• 해당 파일에서 앵커 텍스트를 찾지 못하면 400 Bad Request가 반환됩니다. 응답의 data.errors[].sourceIndex와 data.errors[].position.anchor.text로 문제가 발생한 소스와 텍스트를 확인할 수 있습니다. sourceIndex는 0부터 시작합니다.

텍스트 입력란 가이드 지원

API로 서명 요청할 때 텍스트 입력란에 안내 문구를 설정할 수 있습니다. 서명자가 입력해야 할 내용이나 작성 방법을 안내하는 데 사용할 수 있습니다.

적용 API

POST /documents

사용 방법

participants[].fields[]의 TEXT 타입 필드에 valueDescription을 지정합니다.

다음은 텍스트 필드 설정의 일부를 발췌한 예시입니다.

{
  "type": "TEXT",
  "dataLabel": "은행 계좌번호",
  "valueDescription": "하이픈(-) 없이 숫자만 입력해 주세요."
}

참고 사항

• 안내 문구는 1~40자로 지정할 수 있습니다.
• 선택 항목이며, 생략하거나 null로 지정하면 별도 안내 문구를 설정하지 않습니다.
• 안내 문구는 입력값이나 입력 형식 검증을 대신하지 않습니다.