서명자 추가

매개변수 이름

유형

필수 여부

설명

envelopeId

string

true

봉투 ID

signerInfos

array

true

서명자 정보 집합

businessId

string

false

개발자가 정의한 비즈니스 번호, 길이 500

roleTypes

array

false

서명자 작업 방식, 기본값은 ["sign", "fill"]

fill-작성

sign-서명

string

false

userEmail

string

false

서명자 이메일 주소

documentVisibility

object

false

파일 가시성 설정으로, 기본값은 전체 공개입니다.

documentViewType

string

false

공개 정책으로, 기본값은 all입니다. all은 봉투 내 모든 서명 파일을 조회할 수 있음을 의미하며, limited는 본인 서명 파일과 추가 공개 파일만 조회할 수 있음을 의미합니다.

viewableFileKeys

array

false

서명자가 추가로 조회할 수 있는 fileKey 목록을 지정합니다. documentViewType=limited일 때만 전달 가능하며 적용됩니다.

phoneNumber

object

false

SMS 알림이 필요한 경우 필수 항목이며, countryCode와 number 모두 입력해야 합니다. 기본값은 비어 있습니다.

countryCode

string

false

국가/지역의 국제 전화 코드이며, '+' 기호는 포함하지 않습니다.

number

string

false

형식 검사를 수행하지 않으며, 최대 길이는 13자리입니다.

customizeSettings

object

false

사용자 정의 설정

notificationSettings

object

false

알림 관련 사용자 정의 설정

customizeMessage

string

false

전용 메시지 알림, 문자 제한 200자

notificationLanguage

string

false

알림 언어로, 기본값은 '기본 알림 언어' 설정에서 가져옵니다.

en-US 영어

zh-CN 간체 중국어

zh-Hant 번체 중국어

ja-JP 일본어

es-MX 스페인어

pt-PT 포르투갈어
th-TH 태국어
id-ID 인도네시아어
vi-VN 베트남어
ms-MY 말레이어
fil-PH 필리핀어
de-DE 독일어
fr-FR 프랑스어
ru-RU 러시아어
it-IT 이탈리아어
ko-KR 한국어

userName

string

true

서명자 이름: 서명 페이지 및 프로세스에서 외부에 표시되는 서명자의 이름을 지정합니다.

[주의] 다음 9개의 특수 문자를 포함할 수 없습니다: / \ : * " < > | ? 그리고 모든 이모티콘

signOrder

int

true

서명자 서명 순서: 최소값은 1입니다. 비순차적 서명의 경우 동일한 순서 값을 지정할 수 있습니다.

signTaskSuspend

boolean

false

해당 서명 위치 앞에 프로세스 차단 노드를 설정할지 여부, 기본값은 false입니다. true-차단 노드 설정; false-차단 노드 미설정. 동일한 signOrder의 또는 그룹 내에서는 차단 구성이 일관되어야 합니다.

suspensionKey

string

false

차단 노드 식별자, 최대 500자까지 가능하며, 동일한 봉투 내에서 고유해야 합니다. signTaskSuspend=true일 때 필수 입력 항목이며, signTaskSuspend=false이거나 전달되지 않은 경우 입력해서는 안 됩니다.

suspendReason

string

false

차단 사유, 전달 시 비워둘 수 없으며 최대 50자까지 가능합니다. signTaskSuspend=true인 경우에만 전달 가능하며, 전달하지 않으면 외부 시스템 처리를 기다려야 한다는 기본 의미가 있습니다. signTaskSuspend=false이거나 전달되지 않은 경우 입력해서는 안 됩니다.

anySigner

boolean

false

누구나 서명할 수 있는지 여부, 기본값은 false입니다.

true-동일한 signOrder에서는 한 명만 서명하면 됩니다.

false-동일한 signOrder에서는 모든 사람이 서명해야 합니다.

authModes

string

false

신원 인증 방식, 기본값은 noAuth입니다.

열거형 유형:

authConfig

object

false

인증 방식 설정

accessCode

object

false

서명 비밀번호 설정, authModes=일 때 필수accessCode필수 항목

accessCode

string

false

비밀문 내용, 대소문자 구분 없음, 영숫자 포함 가능, 길이 45

promptInfo

string

false

액세스 비밀번호 안내 메시지, 액세스 비밀번호를 포함할 수 없으며, 길이 제한 30, authModes=일 때 필수accessCode필수입니다.

sms

object

false

SMS OTP 인증, authModes=일 때 필수sms필수 항목

countryCode

string

false

국가/지역의 국제 코드, '+' 기호 불필요

number

string

false

형식 검증 안 함, 최대 길이 13자리

idVerification

object

false

신분증 인증 설정, authModes=일 때 필수idVerification필수 항목

name

string

false

서명인의 신분증에 기재된 성명 전체, 최대 길이 100자

emailAuth

object

false

이메일 OTP 검증, authModes=일 때 필수emailAuth필수 항목

authEmail

string

false

서명자 신원 확인 이메일 주소

digitalId

array

false

전자 신원 확인, authModes=digitalId일 때 필수 입력

authApp

string

false

전자 신원 확인에 사용되는 앱

singpass- Singpass를 사용한 신원 인증

iamsmart- MyInfo를 사용한 신원 인증

idNumber

string

false

서명자가 확인할 신분증 번호

authApp=singpass일 경우, 전달 규칙은: 대문자 + 7자리 또는 8자리 숫자 + 대문자

authApp=iamsmart일 경우, 전달 규칙은:

1. 시퀀스의 시작 부분으로 하나의 대문자(A-Z) 또는 두 개의 대문자(AA-ZZ);

2. 그 다음 6자리 숫자;

3. 마지막으로 체크 디지트(숫자 0-9 또는 문자 A-Z). 예: A888888(A)

whatsappAuth

object

false

WhatsApp OTP 검증, authModes=whatsappAuth일 때 필수 입력

countryCode

string

false

국가/지역의 국제 코드, '+' 기호는 포함하지 않음

number

string

false

형식 검증 없이 길이만 최대 13자리로 제한

digitalSignature

boolean

false

디지털 서명 활성화 여부, 기본값 false

true-활성화

false-비활성화

tsp

string

false

서명자가 사용할 TSP 선택, 기본값 false.

설정하지 않으면 서명자가 사용할 TSP를 직접 선택합니다. 열거형 포함:

vinotek、eSignPersonal、localCertificates、iAmSmart、vnptSmartCa、adacomOneShot、audkenni

belgianIdCard、certEuropeUsbToken、certSignWebSign、chaveMovel、croatianIdCard、czechIdCard、dTrustSignMe、diia

estonianIdCard、estonianMobileId、evrotrust、finnishIdCard、frejaEid、frejaEidSign、gseGestionDeSeguridadElectronica、halcom

harica、idAustriaATrustSignatur、infoCert、ltId、latvianIdCard、latvianEParakstsMobile、lithuanianIdCard、lithuanianMobileId

mscTrustGate、mitId、norwegianBankId、oneId、pscWorldWallet、spid、serproId、simplySign

smartId、swedenBankId、swissId、swisscom、transSped、trustAsia、zealidApp、certMe

certSignUsbToken、eCertChile、eMudhra、itsme、mojeId、emdha

freeFormSign

boolean

false

서명자가 자유로운 도장 사용 가능 여부, 기본값 false

보충 설명:

freeFormSign을 true로 선택할 경우, sealInfos 내 다른 파라미터는 전달할 필요가 없습니다. 동시에 전달될 경우 freeFormSign의 우선순위가 sealInfos보다 높으며, sealInfos 내 파라미터는 적용되지 않습니다.

[주의] 자유로운 도장 사용은 서명자가 삽입할 수 있는 도장/서명의 수와 위치가 제한되지 않음을 의미합니다.

sealInfos

array

false

서명 작업 정보

fileKey

string

true

서명 파일 fileKey

signConfigs

array

false

컨트롤 위치 정보, 전자 서명을 수행하려면 반드시 컨트롤의 위치 정보를 지정해야 합니다.

fieldType

string

false

컨트롤 유형, 입력 가능:

signature-서명 컨트롤

stamp-도장 컨트롤

기본값은 signature입니다.

필수 입력 여부, 기본값은 필수입니다.

true-필수

false-선택

signFieldStyle

string

false

서명 컨트롤의 도장 방식, 기본값은 normalSeal입니다.

normalSeal-일반 도장

pagingSeal-페이지 경계 도장

페이지 경계 도장은 서명 컨트롤과 도장 컨트롤에서만 설정할 수 있습니다.

pagingSealMode

string

false

페이지 경계 도장의 적용 페이지 범위, 기본값은 all입니다.

all-모든 페이지 번호

assignedPages-지정된 페이지 번호

even-짝수 페이지

odd-홀수 페이지

signFieldStyle=pagingSeal일 때만 지정을 지원합니다.

sizeRule

string

false

서명 영역 크기 표시 방식

originalSize- 서명/도장 실제 크기에 따라 배치

targetSize- 서명/도장 영역의 가로세로 크기 사용자 정의

sizeRule, height, width가 모두 비어 있을 경우, 서명/도장 실제 크기에 따라 배치합니다;

sizeRule이 비어 있고 height, width가 비어 있지 않을 경우, 지정된 크기에 따라 배치합니다;

sizeRule이 비어 있지 않을 경우, 지정된 표시 방식에 따라 배치합니다;

교차 도장은 이 파라미터를 지정할 필요가 없으며, 실제 크기에 따라 배치됩니다.

height

int

false

서명 컨트롤 높이, fieldType이 signature/stamp인 경우에 적용되며, 단위는 px입니다. 양의 정수만 입력 가능하며, 기본값은 auto(시스템 자동 크기)입니다;

fieldType=signature일 경우, 설정 범위는 20-250px입니다;

fieldType=stamp일 경우, 설정 범위는 30-280px입니다;

교차 도장은 이 파라미터를 지정할 필요가 없습니다.

width

int

false

서명 컨트롤 너비, fieldType이 signature/stamp인 경우에 적용되며, 단위는 px입니다. 양의 정수만 입력 가능하며, 기본값은 auto(시스템 자동 크기)입니다;

fieldType=signature일 경우, 설정 범위는 20-250px입니다;

fieldType=stamp일 경우, 설정 범위는 30-280px입니다;

파일 간 인장에는 이 매개변수를 지정할 필요가 없습니다.

signatureOptions

string

false

서명 컨트롤 옵션. fieldType이 signature인 경우에만 적용됩니다.

입력 가능:

template

handDrawn

upload

aiHandDrawn

다중 선택 가능, 쉼표(",")로 구분, 기본값은 전체 선택

movable

boolean

false

서명 시 위치 이동 허용 여부, 기본값 false

false- 서명인이 자신의 서명 컨트롤 위치를 조정할 수 없음

true- 서명인이 자신의 서명 컨트롤 위치를 조정할 수 있음

allowedOptions

array

false

서명인의 승인 옵션, fieldType이 approval인 경우 적용됨. 기본값은 ["approve", "decline"]

approve- 동의

decline- 거부

pageNo

string

false

서명 페이지 번호; 연속 페이지는 "-"로 연결하고, 개별 페이지는 ","로 연결합니다. 예: 1-3, 6-10

pagingSealMode=assignedPages일 때 파일 간 인장이 찍히는 페이지 범위를 전달합니다. 파일 간 인장은 1페이지 이상의 파일에서만 사용할 수 있습니다.

posX

string

false

X축 좌표

보충 설명:

fieldType이 signature인 경우, 좌표 위치는 서명 영역을 의미합니다.좌하단；

fieldType이 stamp인 경우, 좌표 위치는 도장 영역을 의미합니다.중심점위치

2026년 2월 3일부터 fieldType이 signature 또는 stamp인 경우, 해당 좌표 위치는 도장 영역의 중심점 위치를 의미합니다.

교차 도장은 0을 전달할 수 있으며 null은 전달할 수 없으며, 컨트롤은 파일 오른쪽 가장자리에 고정됩니다.

posY

string

false

Y축 좌표

보충 설명:

fieldType이 signature인 경우, 좌표 위치는 서명 영역을 의미합니다.좌하단；

fieldType이 stamp인 경우, 좌표 위치는 도장 영역을 의미합니다.중심점위치

2026년 2월 3일부터 fieldType이 signature 또는 stamp인 경우, 해당 좌표 위치는 도장 영역의 중심점 위치를 의미합니다.

fillConfigs

array

false

컨트롤 정보 입력

fieldName

string

false

컨트롤 이름, 문자 수 제한 128

required

boolean

false

필수 입력 여부, 기본값 필수

true-필수 입력

false-선택 입력

fieldType

string

false

컨트롤 유형:

1-단일 줄 텍스트

15-체크박스

textField

object

false

텍스트 컨트롤 속성

overflowType

int

false

text에만 적용, 기본값 1

1-글자 크기 자동 축소

2-입력 제한

minFontSize

float

false

text에만 적용, overflowType=1에만 적용, 기본값 8.

5, 5.5, 6, 6.5, 7, 7.5, 8, 9, 10, 10.5, 11, 12, 14, 15, 16, 18, 20, 22, 24, 26, 28, 36, 42, 48, 56, 72

width

int

false

컨트롤 너비, 기본값 160px

font

int

false

text에만 적용, 글꼴, 기본값 송체.

1-송체

2-신송체

4-헤이티

5-카이티

6-Arial

7-Helvetica

9-Times New Roman

10-방송

11-Georgia

12-Monospace

fontSize

float

false

text에만 적용, 글꼴 크기, 기본값 12

5, 5.5, 6, 6.5, 7, 7.5, 8, 9, 10, 10.5, 11, 12, 14, 15, 16, 18, 20, 22, 24, 26, 28, 36, 42, 48, 56, 72

textColor

string

false

text에만 적용, 16진수 색상, 기본값 검은색 #000

bold

boolean

false

text에만 적용, 글꼴 굵기 여부, 기본값 false

true-굵게

false-굵지 않음

italic

boolean

false

text에만 적용, 기울임꼴 여부, 기본값 false

true-기울임꼴

false-일반꼴

underline

boolean

false

text에만 적용, 밑줄 추가 여부, 기본값 false

true-밑줄 추가

false-밑줄 없음

lineThrough

boolean

false

text에만 적용되며, 취소선을 추가할지 여부를 나타냅니다. 기본값은 false입니다.

true-취소선 추가

false-취소선 미추가

horizontalAlignment

string

false

text에만 적용되며, 수평 정렬 형식을 지정합니다. 기본값은 left입니다.

LEFT-왼쪽 정렬

CENTER-가운데 정렬

RIGHT-오른쪽 정렬

tickBoxField

object

false

체크박스 속성

tickOptions

array

false

Check에만 적용되며, 기본값은 1입니다.

1-체크

2-엑스 표시

posX

float

false

컨트롤 위치 X좌표

posY

float

false

컨트롤 위치 Y좌표

pageNo

string

false

컨트롤이 위치한 페이지 번호

signDateConfigs

array

false

서명 날짜 위치 정보

movable

boolean

false

서명 시 위치 이동 허용, 기본값 false

false- 서명인이 자신의 서명 컨트롤 위치를 조정할 수 없음

true- 서명인이 자신의 서명 컨트롤 위치를 조정할 수 있음

pageNo

string

false

서명 페이지 번호; 연속된 페이지는 "-"로 연결하고, 개별 페이지는 ","로 연결합니다. 예: 1-3, 6-10

연속되지 않은 경우 ","로 구분하여 전달

posX

float

false

x축 오프셋, 좌표 원점은 페이지 왼쪽 하단

posY

float

false

y축 오프셋, 좌표 원점은 페이지 왼쪽 하단

signDateFormat

string

false

서명 날짜 형식, 기본 형식은 yyyy-MM-dd

다음 형식을 지원:

yyyy년 MM월 dd일

yyyy-MM-dd

yyyy/MM/dd

dd.MM.yyyy

MM dd yyyy

dd MM yyyy