eformsign API 시작하기: 실습 가이드

이폼사인 API를 사용하여 문서 작성 및 수신자에게 전송하기

이 가이드에서는 이폼사인 API를 사용하여 수신자에게 이메일로 문서 작성 및 수신자에게 전송하는 방법을 준비부터 문서 요청까지 테스트해 보실 수 있도록 순서대로 설명합니다.

이폼사인에서 API 키를 생성한 후, API 테스트용 앱인 Postman을 사용하여 키를 인증하고 문서를 작성해 수신자에게 전송해 보겠습니다.

Note

미리 Postman 계정을 생성하고 앱 을 다운로드하거나 웹 버전에 액세스하세요.

이폼사인 API를 사용한 문서 작성 및 전송은 다음의 프로세스로 진행됩니다. (1~3번은 API 활용을 위한 준비과정입니다.)

1. 템플릿 만들기

2. API 키 생성하기

3. Access token 발급하기 (API 키 인증)

4. API를 사용하여 문서 작성 및 요청하기

준비사항 1. 템플릿 만들기

이폼사인 API를 사용하여 문서를 작성하고 수신자에게 전송하려면 우선 이폼사인 서비스에 로그인 후 템플릿을 만들고 저장해야 합니다.

이 가이드에서는 최초 문서 작성자가 한 명의 수신자에게 이메일을 통해 문서 작성 요청을 보내는 간단한 워크플로우를 설정하여 템플릿을 만들어 보겠습니다.

대표관리자 계정으로 이폼사인에 로그인합니다.
메뉴에서 템플릿 관리를 클릭하여 이동합니다.
새로운 템플릿을 만들기 위해 새 템플릿 만들기를 클릭합니다.
서 참여자 설정 팝업에서 문서 작성에 참여할 사람을 설정합니다. 이 가이드에서는 최초 작성자인 시작과 수신자인 회원을 설정하겠습니다.

시작과 회원이 작성할 입력항목을 문서에 추가하고 입력항목 ID 입력, 참여자별 입력항목의 작성권한을 설정합니다.

화면 상단에서 설정하기를 클릭하여 이동 후 워크플로우를 설정합니다. 워크플로우는 시작(참여자) - 회원(참여자), 2단계로 설정하고 회원 단계 우측 속성에서 알림 옵션 - 이메일을 선택합니다.

템플릿을 저장 및 배포한 후 해당 템플릿의 설정 아이콘을 다시 클릭합니다. 이때 URL의 UUID에 표시된 템플릿 ID를 복사해 둡니다. 템플릿 ID는 템플릿을 사용하여 문서를 작성할 때 필요합니다.

준비사항 2. API 키 생성하기

템플릿을 다 만들었으면 이제 API 키를 생성할 차례입니다.

이폼사인에서 [커넥트 > API/Webhook > API 키 관리] 페이지로 이동한 후 화면 우측의 API 키 생성을 클릭합니다.

API 키 생성 팝업이 나타나면 별칭 및 애플리케이션 이름을 입력하고 검증 유형을 Bearer token으로 선택한 후 값을 입력하고 저장합니다.

Note

이폼사인 API에서는 세 가지 검증 유형을 지원하고 있으며, 이번 실습 가이드에서는 Bearer token 방식을 사용해서 진행하겠습니다.

Note

검증 유형에 대한 자세한 내용은 eformsign API 사용하기 가이드의 API 키 발급 및 비밀키 확인하기 를 참고해 주세요.

생성된 API 키를 확인하고 복사합니다. API 키는 Access 토큰을 발급할 때 필요합니다.

준비사항 3. Access 토큰 발급하기 (API 키 인증)

API 키를 생성한 후에는 인증을 거쳐 Access 토큰을 발급받아야 합니다. 이번 가이드에서는 API 테스트 툴인 Postman을 사용하여 API 키 인증 후 Access 토큰을 발급해 보겠습니다.

Access 토큰 발급과 문서 작성 및 전송을 더 쉽고 빠르게 테스트 해볼 수 있도록 미리 이폼사인 API reference collection를 만들어 놓았습니다. 아래 Run in Postman 버튼을 클릭해 주세요.

위 버튼을 클릭하면 로그인 창이 뜹니다. 미리 가입한 계정으로 로그인해 주세요.
로그인 후 다음과 같은 화면이 표시되면 Fork Collection을 클릭합니다. 미리 만들어 놓은 이폼사인 API reference collection을 사용자의 workspace로 fork합니다.

이폼사인 API reference collection을 workspace로 fork하면 다음과 같은 화면을 확인할 수 있습니다.

token 폴더의 Access Token 발급(bearer)를 선택합니다.
Headers 탭을 클릭하여 eformsign_signature와 Authorization 값을 다음과 같은 형태로 입력합니다.
- eformsign_signature: Bearer {{API 키 생성 시 설정한 토큰값}}
- Authorization: Bearer {{base64 인코딩된 API 키}}

Tip

base 64 인코딩은 온라인 Base 64 인코더 사이트에서 진행해 주세요.

Body 탭으로 이동한 후 raw를 선택하고 execution_time 및 member_id 값을 입력한 다음 Send 버튼을 클릭하여 API를 호출합니다.

Tip

execution_time은 토큰이 요청된 시간, 즉 timestamp입니다. 요청 후 30초안에 13자리 밀리초 시간을 입력하세요.

해당 값은 Epoch Converter 와 같은 사이트에서 변환할 수 있습니다.

[참고] Epoch Converter 사이트 사용법:

Human date to Timestamp 버튼 좌측에 있는 입력란에 GMT 시간(한국시간에서 -9시간)을 입력하고 버튼을 클릭합니다.
Timestamp in milliseconds 값을 확인합니다.

Note

Member_id는 문서를 작성하는 계정ID(대표계정으로 로그인한 계정)입니다. 이 정보는 회사 관리 > 회사 정보 >상세 정보에서 확인할 수 있습니다.

아래와 같이 API키가 정상적으로 인증되면 (Status: 200 OK) Access 토큰이 발급됩니다. Response body에서 api_url, refresh_token, access_token 값을 확인할 수 있습니다.

Note

Access 토큰의 유효시간은 3600초(1시간)으로 설정되어 있으며, 유효시간이 만료되면 해당 토큰으로 더 이상 API를 사용할 수 없습니다. 따라서 Access 토큰을 재발급하거나 Access 토큰 갱신 API를 사용해 토큰을 갱신해야 합니다.

Access 토큰 갱신 API에 대한 내용은 Swagger 에서 확인하실 수 있습니다.

API를 사용하여 문서 작성 및 요청하기

API 키가 인증되어 Access 토큰이 발급되었으므로 모든 준비가 끝났습니다. 이제 API를 사용하여 문서 작성 및 요청을 해보겠습니다.

eformsign API reference collection의 document 폴더에서 POST 새 문서 작성 (최초 작성자가 회사 멤버)를 선택합니다.

Important

중요!

URL은 위의 준비사항 3-8 단계에서의 response body에서 받은 api_URL을 입력하세요(예 kr.api.eformsign.com).

Params 탭에서 template_id*에 값을 입력합니다.
*템플릿 ID는 템플릿 생성 후 URL에서 복사해 둔 값입니다.

Authorization 탭에서, Type을 Bearer Token으로 선택하고 발급받은 Access 토큰 값을 입력합니다.

이제 API로 문서를 작성하고 보낼 준비가 거의 완료되었습니다! 하지만 그 전에 마지막으로 해야할 일이 있습니다. 문서를 보내기 전에 문서 이름, 수신자 정보, 워크플로우 정보, 그리고 최초 작성자가 입력해야 하는 필드 ID 및 값 등의 문서 정보를 입력해야 합니다.

해당 정보는 Body 탭에서 JSON 형식으로 입력합니다. 실습용은 샘플로 거의 모든 데이터가 미리 입력되어 있습니다. 사용자의 문서 정보에 맞게 데이터를 수정할 수 있으며, 문서 정보의 모든 schema는 Swagger 에서 확인할 수 있습니다.

샘플

{
  "document": {
    "document_name": "회원가입 신청서",
    "comment": "신청서 작성 부탁드립니다.",
    "recipients": [
      {
        "step_type": "05",
        "use_mail": true,
        "use_sms": false,
        "member": {
          "name": "홍길동",
          "id": "honggildong@forcs.com",
          "sms": {
            "country_code": "+82",
            "phone_number": "01023456789"
          }
        },
        "auth": {
          "password": "6789",
          "password_hint": "휴대폰번호 뒷자리를 입력해주세요.",
          "valid": {
            "day": 7,
            "hour": 0
          }
        }
      }
    ],
    "fields": [
      {
        "id": "회원구분",
        "value": "일반"
      }
    ],
    "select_group_name": "",
    "notification": []
  }
}

위와 같이 body를 입력하면 13646ef03fd54f2388c0e0e25afe017c의 ID를 가진 템플릿으로 회사 멤버인 최초 작성자가 입력항목 ID ‘회원구분’에 ‘일반’을 입력하고 수신자 이메일 주소인 honggildong@forcs.com 으로 문서가 전송됩니다.

모든 데이터를 확인한 후 Send 버튼을 클릭하면 문서가 수신자에게 전송됩니다.

위와 같이 API 호출이 성공하면(Status: 200 OK) 수신자의 이메일로 문서 작성 요청 메일이 전송됩니다.

진행 중 문서함에서 API로 전송된 문서를 확인할 수 있습니다.

이제 수신자는 이폼사인을 통해 작성된 문서를 이메일로 받아서 확인하면 이폼사인을 통해 문서 작성 요청을 받았으며, 이를 작성하여 제출하면 문서가 완료됩니다.

위와 같은 방식으로 이폼사인의 다양한 API를 손쉽게 테스트해볼 수 있습니다.

이폼사인 API에 대한 자세한 내용은 eformsign API 사용하기 가이드 및 Swagger eformsign API 가이드 에서 확인할 수 있습니다.