비대면 계약 시작

• 비대면 계약 서식을 시작합니다.

• export_api 값을 따로 설정하여 받아올 값의 형식을 지정할 수 있습니다.(선택사항)

• export_api 란 고객님이 진행중 승인, 반려를 할 경우 설정된 값을 설정된 URL로 esignon에서 request 해주는 기능입니다.

• ※ Body 파라미터 중 Required 값은 필수 값이므로 입력하지 않으시면 요청에 실패합니다. 또한, Optional 이지만 Array 타입의 파라미터를 사용하실 경우 Array 내부 파라미터 값 중 Required 값을 꼭 입력해주셔야 합니다. 사용을 하지 않으실 경우에 내부 파라미터를 입력하실 필요가 없습니다.

• ※ language 파리미터의 경우 기본값 "ko-KR" ( 설정 안했을경우 )

API 주소 정보

Url	Type	Code
https://docs.esignon.net/api/:companyId/startsimple	POST	5005Q

Request

Parameters

PathParameters

Parameter Name	DataType	Description
:companyId	String	회사아이디

Headers

Parameter Name	DataType	Required	Description
Content-Type	String	Required	"application/json"
Authorization	String	Required	"esignon ${발급받은토큰}"

Body

Body - Header Parameter

Parameter Name	DataType	Required	Description
request_code	String	Required	"5005Q"(API 고유 코드)
version	String	Required	"9.9.99"

Body - Body Parameter

Parameter Name	DataType	Required	Description
workflow_name	String	Required	문서명 ( 계약서 이름 )
doc_id	String	Required	시작할 서식 ID
memb_email	String	Required	계약 시작자 이메일
language	String	Optional	"ko-KR", "en-US", "ja-JP" 전달하는 메일 및 플레이화의 표기언어 카톡의 경우 한글만 제공
comment	String	Optional	전달메시지
expireddate	String	Optional	YYYY-MM-DD형식으로 입력 문서의 작성기한 설정 년 - 월 - 일
preview	String	Optional	"preview" - 입력값 고정 옵션 설정시 비대면 계약 시작이 아닌 미리보기URL 이 제공됩니다.
player_list	Array	Required	서명하는 고객의 정보를 입력 서식의 단계에 맞춰서 작성 필수
player_list.email	String	Required	이메일 or 전화번호
player_list.name	String	Required	계약 진행자 이름
player_list.mobile_number	String	Optional	본인인증에 사용할 번호
player_list.password_hint	String	Optional	계약 진행시 사용할 비밀번호 힌트
player_list.password	String	Optional	계약 진행시 사용할 비밀번호
field_list	Array	Optional	미리 입력할 값이 있을 경우 추가하는 값 입력가능한 박스 : RadioBox, CheckBox, LabelBox, TextBox, PictureBox, DatePickerBox(날짜박스)
field_list.field_name	String	Optional	각 필드명 (서식 수정의 오른쪽 에서 정의한 박스 이름)
field_list.field_value	String	Optional	Radio, Check Box : "N" or "Y" Label, Text Box : 텍스트 값 DatePickerBox : YYYY-MM-DD 형식의 날짜 입력 PictureBox : 이미지를 base64로 인코딩한 텍스트 값 ( ※ 가능한 이미지 파일 확장자는 jpg, jpeg, png입니다. 다른 확장자 파일을 넣을 경우 문서가 열리지 않을 수 있습니다. 이미지 파일 크기는 1MB를 넘지 않아야 합니다.)
export_api_info	Array	Optional	작성 데이터를 내보낼시에 설정하는 값
export_api_info.api_type	String	Required	"StartAndEnd"(시작과 끝만) or "ALL" (전부)
export_api_info.url	String	Required	통신 받을 url
export_api_info.link_type	String	Optional	embed 전용옵션 문서 완료 시 이력인증서, PDF 문서 URL의 type을 변경 default - viewer URL "download" - download URL
export_api_info.request_code	String	Optional	고객이 정의하는 임의의 값 or "embed"( ExportAPI 설명 참조)
export_api_info.authorization	String	Optional	데이터를 수신받을때 헤더 authorization 로 설정하고 싶은 값 (수신측에서 암호토큰을 받아서 보안상 활용하고 싶으신경우)
export_api_info.request_params	Array	Optional	문서내부에 특정 값을 받아 오고싶을때 사용
export_api_info.request_params.param_id	String	Required	받아올 파라미터 이름(사용자 지정)
export_api_info.request_params.param_value	String	Required	request_params.fields에서 받아올 값이 문서에 없는경우 받아올 기본 값
export_api_info.request_params.fields	Array	Required	서식 내부에 있는 필드명을 조회하여 필드이름에 해당하는 값이 문서에 존재할 경우 request_params.param_value 대신에 들어가는 값
export_api_info.request_params.fields.doc_id	String	Required	서식 ID
export_api_info.request_params.fields.field_name	String	Required	값을 가져올 서식 내 필드 명
customer_list	Array	Optional	참조자가 있을 경우 추가
customer_list.email	String	Required	이메일 or 휴대폰번호
customer_list.name	String	Required	참조자 이름
customer_list.language	String	Optional	"ko-KR", "en-US", "ja-JP"

Request Body Example

{
	"header": {
		"request_code": "5005Q",
		"version": "9.9.99"
	},
	"body": {
		"biz_id": "0",
		"workflow_name": "{ 작성할 문서명 }",
		"memb_email":"{ 계약 시작자 이메일 }",
		"doc_id": "{서식 ID}",
		"language": "ko-KR",
		"comment": "",
		"expireddate": "YYYY-MM-DD",
		"player_list": [{
			"field_owner": "1",
			"email": "{ 받는 사람 email or 받는 사람 휴대폰 번호 }",
      "name":"{ 받는 사람 이름 }",
			"mobile_number": "{ 휴대폰 본인인증시 사용할 휴대폰번호 }",
      "password_hint":"{ 비밀번호 힌트 }",
      "password":"{비밀번호}"
		},{
			"field_owner": "2",
			"email": "{}",
      "name":"{}",
			"mobile_number": "{}",
      "password_hint":"{}",
      "password":"{}"
		}],
		"field_list": [{
				"field_name": "{ field_name }", 
				"field_value": "{ field_value }"
			}
		],
		"customer_list": [{
				"email": "{ id_type에 따라서 참조자 이메일 or 휴대폰번호 }",
	      "name":"{ 참조자 이름 }"
		}],
		"export_api_info": {
				"api_type": "{ StartAndEnd or ALL }",
				"url": "{ 통신 받을 url }",
				"link_type": "{download or null}",
				"request_code": "{ 고객이 정의하는 임의 값 }",
				"authorization": "{설정 URL로 request 시에 Header - authorization 으로 받아올 값 }",
	      "request_params": [{
								"param_id": "{받아올 파라미터 이름(사용자 지정)}",
								"param_value": "{fields에서 설정한 값이 없을 경우 받아올 기본 값}",
								"fields": [{ 
                            "doc_id":"{ 서식 ID }",
                            "field_name":"{ 값을 가져올 서식 내 필드명 }" 
          			}]
				}]
	   }
	}
}

request_params 서식에 field_name으로 등록한 필드 박스의 값이 없을경우 param_id:param_value return 값이 있을경우엔 param_id:field_value를 return

Request Body Example - only Required

{
	"header": {
		"request_code": "5005Q",
		"version": "9.9.99"
	},
	"body": {
		"biz_id": "0",
		"workflow_name": "{ 작성할 문서명 }",
		"memb_email":"{ 계약 시작자 이메일 }",
		"doc_id": "{서식 ID}",
		"language": "ko-KR",
		"player_list": [{
			"field_owner": "1",
			"email": "{ 받는 사람 email or 받는 사람 번호 }",
			"name": "{ 받는 사람 이름 }"
		}, {
			"field_owner": "2",
			"email": "{}",
			"name": "{}"
		}]
	}
}

Request Body Example - For TEST Account

{
	"header": {
		"request_code": "5005Q",
		"version": "9.9.99"
	},
	"body": {
		"biz_id": "0",
		"memb_email": "[email protected]",
		"language": "ko-KR",
		"comment": "",
		"workflow_name": "TEST-NAME",
		"doc_id": "1",
		"player_list": [{
				"field_owner": "1",
				"email": "[email protected]",
				"name": "TEST"
			},
			{
				"field_owner": "2",
				"email": "[email protected]",
				"name": "TEST"
			}
		],
		"field_list": [{
			"field_name": "name",
			"field_value": "name-value"
		}],
		"customer_list": [{
			"email": "[email protected]",
			"name": "TEST"
		}]
	}
}

Response

Code	Description	Reference
200	성공	형식이 잘못 된 경우 result_msg 참조
400	연결 실패

Result_msg

Code	Description	Reference
00	성공	성공
-1	실패	문서명은 1~128자로 입력해주세요. timezone_offset의 형식이 잘못되었습니다. // ( +XX:XX or -XX:XX ) 형식 문서이름에 특수문자를 포함할 수 없습니다.(\', \", \\, /, :, |, <, >, . ?) 이름에 특수문자를 포함할 수 없습니다.(\', \", \\, /, :, |, <, >, . ?) 휴대폰 형식이 맞지 않습니다. ( - 유무 상관없음 ) 이메일 형식이 맞지 않습니다. 휴대폰 본인인증 요청 생년월일의 날짜가 적합하지 않습니다. 8자리로 입력해주세요.(ex.20200120)(요청 생년월일 :**** ) 비밀번호에 한글은 입력할 수 없습니다. 비밀번호에 특수문자[\' \" \]를 입력할 수 없습니다. 비밀번호인증 비밀번호(password)는 4~15자로 입력해주세요. 비밀번호인증 힌트는 50자 이하로 입력해주세요. 메세지 글자수를 초과했습니다.(250자 제한) player_list의 name 값은 필수로 입력하셔야 합니다. 시작하는 사람(memb_email:***)은 회사에 가입된 사람이여야 합니다. 존재하지 않는 서식입니다. (서식아이디:**) 서식에 작성자가 설정되지 않았습니다. 서식메뉴에서 해당 서식의 문서 작성자를 지정해주세요.(서식아이디:**) 설정한 문서작성자 수( * )와 서식의 문서작성자 수( * )가 일치하지 않습니다.
10	실패	실패
11	실패	수신 메세지의 Body 정보가 잘못된 형태여서 파싱하지 못했습니다.
12	실패	eSignon 서비스 이용기간이 만료되었습니다. 고객지원센터로 연락부탁드립니다.(02-6299-5926)
13	실패	eSignon 서비스 사용건수가 초과되었습니다. 고객지원센터로 연락부탁드립니다.(02-6299-5926)
19	실패	날짜형식이 잘못되었습니다. ( 만료일 설정 )
20	실패	지난 날짜를 만료일로 설정할 수 없습니다.
99	실패	Unexpected exception ( 잘못된 포맷 )

Response Body Example

{ 
 "header":{
   "session_id": "S1001", 
   "response_code": "5005A",
   "result_code": "00", 
   "result_msg": "Work Flow가 시작됩니다.", 
   "version": "9.9.99" }, 
 "body":{ 
   "comp_id": "{ 회사 ID }", 
   "biz_id": "0", 
   "memb_email": "{ 계약 시작자 이메일 }", 
   "workflow_id": "{ 문서아이디 }", 
   "workflow_name": "{ 시작된 서식 이름 }", 
   "token": "{ 문서를 시작한 사람이 계약의 첫번째 작성자일 경우 작성페이지에 접근할때 사용하는 토큰값 }", 
   "lang": "ko-KR" }
}

Response 로 수신한 토큰을 https://docs.esignon.net/mail/sign?token=:token 경로에 token 값을 입력 한뒤 접근하면 진행중인 계약서에 접근할 수 있습니다. ( 생성자 기준으로 발급되는 token 입니다. 생성자가 만약 계약 단계에 있을경우 해당 URL로 서명이 가능 그 외의 경우에는 해당 URL로 진행중인 문서 확인이 가능합니다. )

Response export_api Example

{
	"header": {
		"api_name": "export",
		"session_id": "S1001",
		"request_code": "{ exportAPI_info 에서 지정한 request_code 값 }",
		"authorization":"{ 비대면 계약 API 사용시 설정했던 authorization 값 }"
	},
	"body": {
		"clientid": "{ eSignonAPI 사용을 위한 Unique ID }",
		"processid": "1", //문서의 진행 단계 구분값
		"requestid": "{ header 의 request_code 값 }",
		"actionid": "1", //문서의 진행 단계 구분값
		"workdatetime": "2020-01-31 04:23:28.0", //작성완료시간
		"worktype": "CF", //CF=승인, RT=반려 ( 처음 계약자가 반려시 문서는 취소 처리됩니다.)
		"wfuid": "{}", //문서의 고유ID
		"useremail": "{ 서명자 이메일or휴대폰번호 }", 
		"opinion": "", //승인, 반려시 고객들이 반려 메세지,전송 메세지를 사용한 경우 출력
		"param_id": "param_value", // fields 값을 설정한 경우 fields_value를 return
	}
}

Response Body Example ( Preview )

{
	"header": {
		"response_code": "5005A",
		"result_code": "00",
		"result_msg": "success (preview url)",
		"version": "9.9.99"
	},
	"body": {
		"preview_url": "미리보기 URL"
	}
}

preview 옵션 설정시 Response로 비대면 계약 시작이 아닌 미리보기 URL이 제공됩니다.