빠르게 봉투 시작하기

POST /esignglobal/v1/envelope/createAndStart

인터페이스 설명

빠르게 봉투를 시작하고, 봉투 생성, 서명할 파일 추가, 서명자 추가 등의 기능을 포함합니다.

자동 시작 지원 : 인터페이스 호출 성공 후, 봉투가 성공적으로 생성 및 시작되며, 이때 봉투가 자동으로 순환을 시작합니다.
자동 종료 지원 : 모든 서명자가 서명을 완료하면 봉투가 자동으로 종료됩니다.

요청 매개변수

매개변수 이름					유형	필수	설명
subject					string	true	봉투 제목 예: “Offer Letter”
remark					string	false	봉투 메모，길이 제한 1000자
signerSettings					object	false	서명자가 수행할 수 있는 작업
	allowTransfer				boolean	false	서명자가 해당 봉투를 다른 사람이 서명하도록 전달할 수 있는지 여부, 기본값은 false입니다. true-봉투의 서명자가 봉투를 다른 사람에게 전달할 권한을 갖도록 허용합니다. false-봉투의 서명자가 봉투를 다른 사람에게 전달할 권한을 갖도록 허용하지 않습니다.
	allowModifyName				boolean	false	서명자가 이름을 수정할 수 있는지 여부, 템플릿 서명에만 적용되며 기본값은 false입니다. true-서명자가 이름을 수정하도록 허용합니다. false-서명자가 이름을 수정하도록 허용하지 않습니다.
expireAfterSeconds					long	false	봉투 만료 시간, 몇 초 후 봉투가 만료되는지 만료 범위: 86,400초(1일) ~ 7,776,000초(90일)
redirectUrl					string	false	유효한 https 주소여야 합니다.
callBackUrl					string	false	콜백 주소(길이 500), https 프로토콜 주소와 일치해야 합니다.
sendLaterAfterSeconds					long	false	사용자가 지연 전송하도록 지원하며, 단위는 초입니다. 지원 시간 범위: 3600초(1시간) ~ 259200초(30일)
CCInfos					array	false	참조인 정보 모음
	userEmail				string	false	참조인 이메일 주소
	userName				string	false	참조인 이름, 서명 페이지 및 봉투에 참조인 이름을 외부에 표시하는 데 사용됩니다. 【주의】: 다음 9개의 특수 문자(/ \ : * " < > \| ？)와 모든 이모지 표정을 포함할 수 없습니다.
	customizeSettings				object	false	사용자 정의 구성
		notificationSettings			object	false	알림 유형 사용자 정의 구성
			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 한국어
signFiles					array	true	서명 파일 정보 모음, 파일 추가 순서대로 표시됩니다.
	fileKey				string	true	서명 파일 fileKey, PDF 형식만 지원
attachments					array	false	봉투 첨부 파일 모음, 파일 추가 순서대로 표시됩니다.
	fileKey				string	false	파일 fileKey
signerInfos					array	true	서명자 정보 모음
	businessId				string	false	개발자 정의 비즈니스 번호, 길이 제한 500
	deliveryMethods				string	false	알림 방법, 기본값은 auto auto- userEmail을 전달하면 이메일 알림을 보내고, phoneNumber를 전달하면 SMS 알림을 보냅니다. none- 메시지 알림을 보내지 않음 email- 이메일 알림 보내기 sms- SMS 알림 보내기 WhatsApp- WhatsApp 알림 보내기
	userEmail				string	false	서명자 이메일 주소
	userName				string	true	서명자 이름, 서명 페이지 및 봉투에 서명자 이름을 표시하는 데 사용됩니다. 【참고】 다음 9개의 특수 문자(/ \ : * " < > \| ？) 및 모든 이모티콘을 포함할 수 없습니다.
	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 한국어
	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-전자 신분 인증 whatsappAuth-WhatsApp OTP 인증
	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- i AM Smart를 사용하여 인증
			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-비활성화
	freeFormSign				boolean	false	서명자가 자유롭게 서명할 수 있는지 여부, 기본값은 false입니다. 추가 설명: freeFormSign을 true로 선택하면 sealInfos 아래의 다른 매개변수를 전달할 필요가 없습니다. 동시에 전달하면 freeFormSign의 우선 순위가 sealInfos보다 높으며 sealInfos 아래의 매개변수는 적용되지 않습니다. [주의]자유 서명은 서명자가 드래그할 수 있는 도장/서명 수량 및 위치를 제한하지 않습니다.
	sealInfos				array	false	서명 작업 정보
		fileKey			string	true	서명 파일 fileKey
		signConfigs			array	false	컨트롤 위치 정보, 전자 서명을 하려면 반드시 컨트롤의 위치 정보를 지정해야 합니다.
			fieldType		string	false	컨트롤 유형, 기본값은 signature입니다. signature- 서명 컨트롤 stamp- 도장 컨트롤 approval- 승인 컨트롤
			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		float	false	x축 좌표 [주의] fieldType이 signature인 경우 좌표 위치는 서명 영역을 나타냅니다.왼쪽 하단； fieldType이 stamp인 경우 좌표 위치는 날인 영역을 나타냅니다.중심점위치 2026년 2월 3일부터 fieldType이 signature 또는 stamp인 경우 좌표 위치는 날인 영역의 중심점 위치를 나타냅니다.
			posY		float	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	텍스트에만 적용, 글꼴, 기본값 송체 1-송체 2-신송체 4-흑체 5-해서체 6-Arial 7-Helvetica 9-Times New Roman 10-방송체 11-Georgia 12-Monospace
				fontSize	float	false	텍스트에만 적용, 글꼴 크기, 기본값 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	텍스트에만 적용, 16진수 색상, 기본값 검은색 #000
				bold	boolean	false	텍스트에만 적용, 글꼴 굵게 여부, 기본값 false true-굵게 false-굵게 아님
				italic	boolean	false	텍스트에만 적용, 기울임체 여부, 기본값 false true-기울임체 false-기울임체 아님
				underline	boolean	false	텍스트에만 적용, 글꼴에 밑줄을 추가할지 여부, 기본값 false true-밑줄 추가 false-밑줄 추가 안 함
				lineThrough	boolean	false	텍스트에만 적용, 취소선을 추가할지 여부, 기본값 false true-취소선 추가 false-취소선 추가 안 함
				horizontalAlignment	string	false	텍스트에만 적용, 수평 가운데 정렬 형식, 기본값 left LEFT-왼쪽 정렬 CENTER-가운데 정렬 RIGHT-오른쪽 정렬
			tickBoxField		object	false	체크 상자 속성
				tickOptions	array	false	tickBox에만 적용되며 기본값은 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

요청 예시

{
    "subject": "员工入职合约",
    "remark": "这是描述",
    "expireAfterSeconds": 86400,
    "redirectUrl": "https://app-sml.esignglobal.com/home/main/esign/contract/list/inbox",
    "signFiles": [
      {
        "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c"
      },
      {
        "fileKey": "$c7567683-2fc1-47a5-82c1-570d4839afd8$3119805980"
      }
    ],
    "signerInfos": [
      {
        "userEmail": "sender_user@tsign.cn",
        "userName": "sender_user_name",
        "phoneNumber": {
        	"countryCode": "86",
        	"number": "158****9242"
        }
        "signOrder": 1,
        "authModes": "sms",
        "authConfig": {
            "sms": {
                "countryCode": "86",
                "number": "158****9242"
            }
        },
        "sealInfos": [
        {
            "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c",
            "signConfigs": [
              {
                "fieldType": "stamp",
                "pageNo": "1,3-5",
                "posX": 100.22222,
                "posY": 100.11111
              }
              "fillConfigs": [
              {
                "fieldId": "df0dd777bc774a2ba3fec4d108de242d",
                "fieldKey": "必填单行文本自动缩小字号最小字号Arial",
                "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": "888b899853544c49bd819d9f6d1e52cf",
                  "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
CCInfos		array	참조인 정보 모음
	userEmail	string	참조인 이메일 주소
	userName	string	참조인 이름
signFiles		array	서명 파일 정보 모음
	fileKey	string	서명 파일 fileKey
attachments		array	봉투 첨부 파일 모음
	fileKey	string	파일 fileKey
signerInfos		array	서명 정보
	businessId	string	개발자 정의 비즈니스 번호, 길이 제한 500
	userEmail	string	서명자 이메일 주소
	userName	string	서명자 이름
	signUrl	string	서명 링크 주소
	signOrder	int	서명자 서명 순서, 최소 1
	accessCode	string	서명 페이지 액세스 암호

응답 예시

{
  "code": "0",
    "data": {
    "signerInfos": [
      {
        "accessCode": "123456",
        "userEmail": "sender_user@tsign.cn",
        "signUrl": "http://app-test.esignglobal-inc.com/home/main/sign/start/base/dosign?envelopeId=4cd738a60225445f9d5f3afec468a639&signature=eyJhbGciOiJIUzI1NiIsInppcCI6IkRFRiJ9.eNqqVkrOzytJrShRsqpWSs0rS83JL0gNSSzO9kxRslJKtjC1MDKxTDVIMzA0SU4xSTIwNjAxSDRNTTVKMTIxTFOqrQUAAAD__w.YMBA5X9O8Ylk7x2rma-s1WxGwo2cjqy-O9CCQopzw88&tenantToken=AA0DDgQ0Y2Q3MzhhNjAyMjU0NDVmOWQ1ZjNhZmVjNDY4YTYzuQ4GNGNkNzM4YTYwMjI1NDQ1ZjlkNWYzYWZlYzQ2OGE2M7kOCjRjZDczOGE2MDIyNTQ0NWY5ZDVmM2FmZWM0NjhhNjO5AIBjNDIwMzg1ZDMyYzU0MGE4YTk1ZTE3ZTNkZmZjMDNm4g%3D%3D",
        "userName": "sender_user_name",
        "signOrder": "1"
      }
    ],
      "signFiles": [
      {
        "fileKey": "4150a67c-d4f0-45e6-88e9-541ce6d0c73c"
      },
      {
        "fileKey": "$c7567683-2fc1-47a5-82c1-570d4839afd8$3119805980"
      }
    ],
      "envelopeId": "4cd738a60225445f9d5f3afec468a639"
  },
  "message": "success"
}