DocsReferencesChangelogCommunity
Changelog
Back to All
Improved

1.42.0

12 days ago

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

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

💡

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

적용 API

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

엔드포인트메서드설명
/documentsPOST서명 요청 문서 생성
/documents/embeddedPOST임베디드 초안 생성
/documents/with-templatePOST템플릿 기반 문서 생성
/documents/embedded/with-templatePOST템플릿 기반 임베디드 초안 생성
/templatesPOST템플릿 생성

신규 필드 타입

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

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

지원 필드 타입 및 prefilledValue 형식

필드 타입prefilledValue 타입필수 여부설명
TEXTstring선택텍스트 값
CHECKBOXboolean선택체크 여부 (true / false)
DATEstring (ISO 8601)선택날짜 값 (예: "2026-03-30")
DROPDOWNstring선택options 목록 중 하나의 값
COMPANY_NAMEstring선택회사명
ADDRESSobject선택주소 객체 (상세 구조 보기)
⚠️

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

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

참여자 필드 조회 응답 개선

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

서명 완료 참여자

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

미서명 참여자

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

⚠️

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