사전 입력(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 형식| 필드 타입 | 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 구조
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)된 서명은 서명 완료로 간주하지 않습니다. 만료된 참여자의 필드는 기본값을 반환합니다.
