Export API 가이드

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에는 새로운 필드 이름을 설정하면 됩니다.

Export API Request Body

POST 요청 시 본문에 포함될 정보는 문서의 상태와 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를 사용하는 예시입니다.

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": "[email protected]",
               "name": "John Doe"
          },
          {
               "order": 2,
               "email": "[email protected]",
               "name": "Jane Doe"
          },
          {
               "order": 3,
               "email": "[email protected]",
               "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": "[email protected]",
    "comment": "",
    "next_email": "[email protected]",
    "next_name": "Jane Doe",
    "field_list": [{
        "name": "1단계작성자이름",
        "value": "John Doe",
        "email": "[email protected]",
        "order": 1
    }, {
        "name": "수집이용항목",
        "value": "생년월일, 이메일 주소",
        "email": "[email protected]",
        "order": 1
    }, {
        "name": "Text_0",
        "value": "",
        "email": "[email protected]",
        "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": "[email protected]",
    "comment": "",
    "field_list": [{
          "name": "1단계작성자이름",
          "value": "John Doe",
          "email": "[email protected]",
          "order": 1
    }, {
          "name": "수집이용항목",
          "value": "생년월일, 이메일 주소",
          "email": "[email protected]",
          "order": 1
    }, {
          "name": "Text_0",
          "value": "abcd",
          "email": "[email protected]",
          "order": 2
    }],
    "status": "Complete",
    "order": 2
}