서명자 추가

POST/esignglobal/v1/envelope/recipients/addSigners

인터페이스 설명

봉투에 서명자를 추가합니다. 서명자는 서명 작업입니다. 서명자에게 컨트롤, 신원 확인 방법 등의 정보를 추가하는 것을 포함합니다.

주의:

봉투가 열린 후 새로운 서명자를 추가하는 것을 지원합니다. 새로 추가된 서명자의 서명 순서는 서명 중인 서명자의 서명 순서 값보다 작거나 같을 수 없습니다.
동일한 서명자(이메일을 사용자 고유 식별자로 사용)는 중복해서 추가할 수 없습니다. 서명 작업 정보를 업데이트해야 하는 경우 해당 서명자를 다시 추가하십시오.
하나의 봉투에 최대 10명의 서명자만 있을 수 있습니다.

요청 매개변수

매개변수 이름					유형	필수	설명
envelopeId					string	true	봉투 ID
signerInfos					array	true	서명자 정보 모음
	businessId				string	false	개발자가 정의한 업무 번호, 길이 500
	userEmail				string	true	서명자 이메일 주소
	phoneNumber				object	false	문자 메시지 알림이 필요한 경우 필수 입력, 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 스페인어
	userName				string	true	서명자 이름이며, 서명 페이지와 프로세스에 서명자 이름을 외부에 표시하는 데 사용됩니다. 【주의】다음 9개의 특수 문자(/ \ : * " < > \| ？)와 모든 이모티콘을 포함할 수 없습니다.
	signOrder				int	true	서명자의 서명 순서이며, 최소값은 1입니다. 순서 없는 서명은 동일한 순서 값을 지정할 수 있습니다.
	anySigner				boolean	false	임의의 한 명의 서명을 지원할지 여부, 기본값은 false입니다. true-동일한 signOrder에서 한 명만 서명하면 됩니다. false-동일한 signOrder에서 모든 사람이 서명해야 합니다.
	authModes				string	false	신원 인증 방식, 기본값은 noAuth입니다. 열거형 유형: noAuth-인증 안 함 accessCode-서명 암호 인증 사용 sms-SMS OTP 인증 idVerification-신분증 인증 emailAuth-이메일 OTP 인증 digitalId-전자 신원 인증
	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를 사용하여 인증
			idNumber		string	false	서명인이 인증해야 할 신분증 번호
	digitalSignature				boolean	false	디지털 서명 활성화 여부, 기본값은 false true-활성화 false-사용 안 함
	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-도장 컨트롤 approval-승인 컨트롤 기본값은 signature입니다.
			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 다중 선택 가능, ","로 구분, 기본적으로 모두 선택
			movable		boolean	false	서명 시 위치 이동 허용, 기본값은 false false-서명자가 자신의 서명 컨트롤 위치를 조정할 수 없음 true-서명자가 자신의 서명 컨트롤 위치를 조정할 수 있음
			allowedOptions		array	false	서명자가 승인할 수 있는 옵션으로, fieldType이 approval인 경우에 적용됩니다. 기본값은 ["approve", "decline"]입니다. approve-동의 decline-거절
			pageNo		string	false	서명 페이지 번호; 연속 페이지 번호는 "-"로 연결하고, 개별 페이지 번호는 ","로 연결합니다. 예: 1-3, 6-10
			posX		string	false	X축 좌표 추가 설명: fieldType이 signature인 경우 좌표 위치는 서명 영역을 나타냅니다.왼쪽 하단； fieldType이 stamp인 경우 좌표 위치는 날인 영역을 나타냅니다.중심점위치 2026년 2월 3일부터 fieldType이 signature 또는 stamp인 경우 좌표 위치는 날인 영역의 중심점 위치를 나타냅니다.
			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	텍스트에만 적용되며 기본값은 1입니다. 1-자동 글꼴 크기 축소 2-입력 제한
				minFontSize	float	false	텍스트에만 적용되며 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에만 적용되며, 글꼴은 기본적으로 SimSun입니다. 1-SimSun 2-NSimSun 4-Heiti 5-Kaiti 6-Arial 7-Helvetica 9-Times New Roman 10-Fangsong 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

요청 예시

{
    "envelopeId": "{{envelope-id}}",
    "signerInfos": [
        {
    	   "userEmail": "sender_user@esignglobal.com",
    	   "userName": "sender_user_name",
    	   "signOrder": 1,
    	   "authModes": "sms",
           "authConfig": {
                "sms": {
                    "countryCode": "86",
                    "number": "158****9242"
                }
            },
            "sealInfos": [
                {
                    "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c",
                    "signConfigs": [
                        {
                           "fieldType": "stamp",
                            "pageNo": "1",
                            "posX": 100.22,
                            "posY": 100
                        }
                    ],
                    "fillConfigs": [
                        {
                            "fieldId": "df0dd777bcc4d108de242d",
                            "fieldKey": "demo",
                            "pageNo": "1",
                            "posX": "88.70021",
                            "posY": 745.409,
                            "fieldType": "1",
                            "required": true,
                            "textField": {
                                "overflowType": "1",
                                "minFontSize": 8,
                                "font": "6",
                                "fontSize": "12",
                                "textColor": "#54ACD2",
                                "bold": false,
                                "italic": true,
                                "lineThrough": false,
                                "horizontalAlignment": "RIGHT"
                            }
                        },
                        {
                            "fieldId": "96e6c7d414f04e98938ea84013b",
                            "fieldKey": "红色加深斜体下划线删除线",
                            "pageNo": "1",
                            "posX": 94.516624,
                            "posY": 284.54953,
                            "fieldType": "1",
                            "required": false,
                            "textField": {
                                "overflowType": "1",
                                "minFontSize": 10.5,
                                "font": "1",
                                "fontSize": 12.0,
                                "textColor": "#E25041",
                                "bold": true,
                                "italic": true,
                                "lineThrough": true,
                                "horizontalAlignment": "LEFT"
                            }
                        },
                        {
                            "fieldId": "888b899853544c49bd819d9f6d1",
                            "fieldKey": "必填勾选控件选中样式不显示边框",
                            "pageNo": "3",
                            "posX": 451.77127,
                            "posY": 429.07626,
                            "fieldType": "15",
                            "required": true,
                            "tickBoxField": {
                                "tickOptions": [1,2],
                                "showBorder": false
                            }
                        }
                    ]
                    "signDateConfigs":[
                          "pageNo":"1",
                          "posX": 100.22,
                          "posY": 100,
                          "signDateFormat": "dd MMM yyyy"
                    ]
                }
            ]
        }
    ]
}

응답 매개변수

매개변수 이름			유형	설명
envelopeId			string	봉투 ID
signFiles			array	서명 문서 모음
	fileKey		string	서명 문서 fileKey
attachments			array	봉투 첨부 파일 모음
	fileKey		string	파일 fileKey
signerInfos			array	서명자 정보 모음
	businessId		string	개발자 정의 비즈니스 번호, 길이 500
	userEmail		string	서명자 이메일 주소
	userName		string	서명자 이름
	signOrder		int	서명자 노드 순서, 최소 1
		accessCode	string	서명 페이지 액세스 암호

응답 예시

{
    "code": "0",
    "data": {
        "signerInfos": [
            {
                "organizationName": "Esign Global CO.",
                "userLastName": "",
                "accessCode": "",
                "userEmail": "sender_user@tsign.cn",
                "userFirstName": "",
                "signOrder": "1"
            }
        ],
        "signFiles": [
            {
                "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c"
            }
        ],
        "attachments": [

        ],
        "envelopeId": "9fbe6c8190824227bde29136b0145c81"
    },
    "message": "success"
}