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

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

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

적용 API

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

엔드포인트	메서드	설명
`/documents`	POST	서명 요청 문서 생성
`/documents/embedded`	POST	임베디드 초안 생성
`/documents/with-template`	POST	템플릿 기반 문서 생성
`/documents/embedded/with-template`	POST	템플릿 기반 임베디드 초안 생성
`/templates`	POST	템플릿 생성

신규 필드 타입

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

필드 타입	설명	비고
`DATE`	날짜 입력 필드	`displayFormat` 지정 필수
`DROPDOWN`	드롭다운 선택 필드	`options` 배열 필수
`NAME`	이름 입력 필드	—
`COMPANY_NAME`	회사명 입력 필드	—
`ADDRESS`	주소 입력 필드	—

지원 필드 타입 및 `prefilledValue` 형식

필드 타입	`prefilledValue` 타입	필수 여부	설명
`TEXT`	`string`	선택	텍스트 값
`CHECKBOX`	`boolean`	선택	체크 여부 (`true` / `false`)
`DATE`	`string` (ISO 8601)	선택	날짜 값 (예: `"2026-03-30"`)
`DROPDOWN`	`string`	선택	`options` 목록 중 하나의 값
`COMPANY_NAME`	`string`	선택	회사명
`ADDRESS`	`object`	선택	주소 객체 (상세 구조 보기)

⚠️
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" }
   }

전체 요청 본문 예시 보기

아래는 여러 필드 타입의 prefilledValue를 포함한 전체 POST /documents 요청 예시입니다.

{
  "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는 다음 속성을 가진 객체입니다.

파라미터	타입	필수 여부	설명
`address1`	`string`	필수	기본 주소 (최대 50자)
`address2`	`string` 또는 `null`	선택	상세 주소 (최대 75자)
`city`	`string` 또는 `null`	선택	시/군/구 (최대 30자)
`province`	`string`	필수	시/도 (최대 30자)
`zip`	`string`	필수	우편번호 (최대 10자)
`country`	`string`	필수	ISO 3166-1 alpha-2 국가 코드 (예: `KR`, `US`)

참여자 필드 조회 응답 개선

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

서명 완료 참여자

실제 입력한 값을 반환합니다.

미서명 참여자

설정된 기본값(prefilledValue)을 반환합니다.

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