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 토큰을 발급해 보겠습니다.

1. Access 토큰 발급과 문서 작성 및 전송을 더 쉽고 빠르게 테스트 해볼 수 있도록 미리 이폼사인 API 실습 가이드용 를 만들어 놓았습니다. 아래 Run in Postman 버튼을 클릭해 주세요. 이폼사인 API 실습 가이드용 Postman collection은 실습가이드를 따라 하는데 필요한 API만 포함하고 있습니다. 현재 제공 중인 모든 API는 Swagger eformsign API 가이드 에서 확인할 수 있습니다.

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

이폼사인 API 실습 가이드용을 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를 사용하여 문서 작성 및 요청을 해보겠습니다.

이폼사인 API 실습 가이드용의 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 가이드 에서 확인할 수 있습니다.