Export API는 문서에 승인, 반려, 취소 이벤트가 발생했을 때, HTTP POST 요청을 생성하여 지정된 URL로 문서 관련 정보(JSON 형식)를 보내주는 Webhook 기능입니다. Export API의 사용을 위해서는 비대면 문서 시작 API 요청 시 body parameter의 export_api_info 값을 설정해야 합니다.

작성자가 문서를 승인, 취소, 반려하거나 API로 상태변경을 요청한 경우 설정된 URL로 문서 관련 정보가 전달됩니다.

export_api_info

url: 이벤트 발생 시 데이터를 전달 받을 서버측 callback URL(endpoint)입니다. 외부에서 접근할 수 있는 도메인만 가능합니다.
authorization: POST 요청 시 HTTP 헤더의 Authorization에 설정할 값입니다. 서버측으로 요청할 때 access token을 포함해야 하는 경우 사용합니다.
api_type: 데이터를 전달 받을 단계를 설정합니다. ALL인 경우 모든 작성 단계에서, StartAndEnd인 경우 첫번째와 마지막 작성 단계에서만 POST 요청이 생성됩니다.
is_embed: true인 경우 이싸인온에서 작성자에게 이메일 및 카카오톡 알림을 발송하지 않습니다. POST 요청 본문에 포함된 작성 진행 URL 또는 완료 문서 URL을 이용해 직접 작성자에게 문서 작성 요청을 하거나 완료 문서를 전달하고 싶은 경우 활용할 수 있습니다.
link_type: is_embed가 true일 때 본문에 포함될 완료 문서 URL과 이력인증서 URL의 타입을 지정합니다. download일 경우 완료 문서, 이력인증서를 다운 받을 수 있는 URL을, 따로 지정하지 않은 경우 viewer의 URL을 제공합니다.
field_names: 문서의 필드 정보를 받아올 때, 필드 이름을 따로 지정하고 싶은 경우 사용합니다. field_name에는 변경이 필요한 필드의 이름을, new_name에는 새로운 필드 이름을 설정하면 됩니다.

발송되는 웹훅의 Request Body

문서의 상태가 변경될 때마다(예: 작성 완료, 반려, 취소), 이싸인온은 고객이 비대면 문서 시작 API 호출 시 전달한 Callback URL로 POST 요청을 보냅니다.

이 Webhook을 통해 문서의 현재 상태와 데이터(Payload)를 받아보실 수 있습니다.

Webhook Payload 구조

전송되는 데이터(Payload)의 구조는 is_embed 값과 문서 상태에 따라 달라집니다.

is_embed가 false인 경우

{
  "workflow_id": 문서 아이디,
  "client_id": "eSignon API 사용을 위한 Unique ID",
  "completed_date": "작성 완료 시간",
  "command_type": "CF", // CF: 승인, RT: 반려
  "name": "작성자 이름",
  "email": "작성자 이메일",
  "comment": "전달 메세지",
  "field_list":[ // 작성된 필드 값 목록
    {
      "name": "필드 이름",
      "value": "필드 값",
      "email": "작성자 이메일",
      "order": 필드 작성 단계
    }],
  "status": "문서 상태",
  "order": 작성 완료 단계,
  "is_embed": "embed 설정 여부",
  "version": "Export API 버전"
}

is_embed가 true이고 진행 중 상태인 경우: 계약 진행 URL이 포함됩니다.

{
  "workflow_id": 문서 아이디,
  "client_id": "eSignon API 사용을 위한 Unique ID",
  "completed_date": "작성 완료 시간",
  "command_type": "CF", // CF: 승인, RT: 반려
  "name": "작성자 이름",
  "email": "작성자 이메일",
  "comment": "전달 메세지",
  "field_list":[ // 작성된 필드 값 목록
    {
      "name": "필드 이름",
      "value": "필드 값",
      "email": "작성자 이메일",
      "order": 필드 작성 단계
    }],
  "next_email": "다음 작성자 이메일",
  "next_name": "다음 작성자 이름",
  "sign_url": "다음 작성자에게 전달할 문서 진행 url",
  "status": "문서 상태",
  "order": 작성 완료 단계,
  "is_embed": "embed 설정 여부",
  "version": "Export API 버전"
}

is_embed가 true이고 완료 상태인 경우: 완료 문서, 이력 인증서 URL이 포함됩니다.

{
  "workflow_id": 문서 아이디,
  "client_id": "eSignon API 사용을 위한 Unique ID",
  "completed_date": "작성 완료 시간",
  "command_type": "CF", // CF: 승인, RT: 반려
  "name": "작성자 이름",
  "email": "작성자 이메일",
  "comment": "전달 메세지",
  "field_list":[ // 작성된 필드 값 목록
    {
      "name": "필드 이름",
      "value": "필드 값",
      "email": "작성자 이메일",
      "order": 필드 작성 단계
    }],
  "download_url": "완료 문서 url",
  "certificate_url": "이력인증서 url",
  "status": "문서 상태",
  "order": 작성 완료 단계,
  "is_embed": "embed 설정 여부",
  "version": "Export API 버전"
}

사용 예시

다음은 문서 시작 시 Export API를 사용하는 예시입니다.

Export API 사전 테스트

아래의 코드를 참조하여 개발 서버에서 Export API 요청을 성공적으로 수신하는지 테스트하실 수 있습니다.
(Callback URL을 http(s)://url/exportApiTest 로 가정한 경우이며, url은 별도 설정)
개발 서버에서 요청을 수신한 경우 다음과 같은 로그를 확인하실 수 있습니다. @@ stringbuilder:{요청값}
위 과정을 통해 개발 서버에서 요청 및 수신할 수 있음을 확인하였다면, 이싸인온에서 제공하는 API를 문제 없이 이용하실 수 있습니다.

@RequestMapping(value = "/exportApiTest", method = {RequestMethod.POST})
    public void esignonExportTest(HttpServletRequest request) throws Exception {
        StringBuilder stringBuilder = new StringBuilder();
        String line = null;
        
        try {
            BufferedReader reader = request.getReader();
            while ((line = reader.readLine()) != null) {
                stringBuilder.append(line);
            }
        } catch (Exception e) {
            e.printStackTrace();
        }
        log.debug("@@ stringBuilder: {}", stringBuilder.toString());

        JSONParser parser = new JSONParser();
        Object obj = parser.parse(stringBuilder.toString());
        JSONObject jsonObj = (JSONObject)obj;
        log.debug("@@ jsonObj:{}",  jsonObj);
    }
}

A 회사에서 이싸인온을 통해 계약서를 진행하는 경우 (2단계 문서)
A회사의 서버 URL: http://123.456.789.555:8080
이싸인온에서 넘어온 데이터를 처리하기 위한 API endpoint: http://123.456.789.555:8080/exportApiTest

1. 비대면 문서 시작 API 요청

curl --request POST \
     --url 'https://docs.esignon.net/api/v3/workflows/start?offset=%2B09%3A00' \
     --header 'Authorization: esignon 이싸인온토큰입력' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
     "recipient_list": [
          {
               "order": 1,
               "email": "johnDoe@gmail.com",
               "name": "John Doe"
          },
          {
               "order": 2,
               "email": "janeDoe@gmail.com",
               "name": "Jane Doe"
          },
          {
               "order": 3,
               "email": "richardRoe@gmail.com",
               "name": "Richard Roe"
          },
     ],
     "export_api_info": {
          "field_names": [
               {
                    "field_name": "JDTex_1",
                    "new_name": "수집이용항목"
               },
               {
                    "field_name": "JDTex_0",
                    "new_name": "1단계작성자이름"
               }
          ],
          "url": "http://123.456.789.555:8080/exportApiTest",
          "api_type": "ALL",
          "link_type": "download",
          "authorization": "header test",
					"is_embed": true
     },
     "workflow_name": "export api test",
     "template_id": 287,
     "expiry_date": "2023-03-31 00:00:00"
}

2. 1단계 작성자가 문서 작성 완료 또는 상태 변경 API를 이용해 승인

3. 이싸인온 서버에서 callback URL로 문서 정보 담아서 `POST` 요청

curl --request POST \
     --url 'http://123.456.789.555:8080/exportApiTest' \
     --header 'Authorization: header test' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "is_embed": true,
    "workflow_id": 736,
    "version": "v3",
    "client_id": "clientid",
    "completed_date": "2023-02-01 10:16:02 (UTC+09:00)",
    "command_type": "CF",
    "name": "John Doe",
    "email": "johnDoe@gmail.com",
    "comment": "",
    "next_email": "janeDoe@gmail.com",
    "next_name": "Jane Doe",
    "field_list": [{
        "name": "1단계작성자이름",
        "value": "John Doe",
        "email": "johnDoe@gmail.com",
        "order": 1
    }, {
        "name": "수집이용항목",
        "value": "생년월일, 이메일 주소",
        "email": "johnDoe@gmail.comr",
        "order": 1
    }, {
        "name": "Text_0",
        "value": "",
        "email": "janeDoe@gmail.com",
        "order": 2
    }],
    "sign_url": "https:\/\/docs.esignon.net\/mail\/sign?token=sXj6icE....gq8%3D&lang=ko",
    "status": "Playing",
    "order": 1
}

4. 2단계 작성자가 문서 작성 완료 또는 상태 변경 API를 이용해 승인

5. 이싸인온 서버에서 callback URL로 문서 정보 담아서 `POST` 요청

curl --request POST \
     --url 'http://123.456.789.555:8080/exportApiTest' \
     --header 'Authorization: header test' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
    "is_embed": true,
    "workflow_id": 736,
    "version": "v3",
    "client_id": "client id",
    "completed_date": "2023-02-01 10:34:49 (UTC+09:00)",
    "command_type": "CF",
    "certificate_url": "https:\/\/docs.esignon.net\/api\/cert\/download?token=D2L...%3D&lang=ko",
    "download_url": "https:\/\/docs.esignon.net\/api\/doc\/download?token=8JQMiv4...%3D&lang=ko",
    "name": "Jane Doe",
    "email": "janeDoe@gmail.com",
    "comment": "",
    "field_list": [{
          "name": "1단계작성자이름",
          "value": "John Doe",
          "email": "johnDoe@gmail.com",
          "order": 1
    }, {
          "name": "수집이용항목",
          "value": "생년월일, 이메일 주소",
          "email": "johnDoe@gmail.comr",
          "order": 1
    }, {
          "name": "Text_0",
          "value": "abcd",
          "email": "janeDoe@gmail.com",
          "order": 2
    }],
    "status": "Complete",
    "order": 2
}