비대면 계약 시작

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

  • 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": "guide@esignon.net",
		"language": "ko-KR",
		"comment": "",
		"workflow_name": "TEST-NAME",
		"doc_id": "1",
		"player_list": [{
				"field_owner": "1",
				"email": "guide@esignon.net",
				"name": "TEST"
			},
			{
				"field_owner": "2",
				"email": "guide@esignon.net",
				"name": "TEST"
			}
		],
		"field_list": [{
			"field_name": "name",
			"field_value": "name-value"
		}],
		"customer_list": [{
			"email": "guide@esignon.net",
			"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이 제공됩니다.

Previous시작Next비대면 계약 - ExportAPI 설명

Last updated