DocuSign API: 사용자 정의 필드 값으로 봉투를 검색하는 방법?

DocuSign API에서 봉투 탐색을 효율적으로 관리하기

디지털 서명 솔루션의 경쟁 환경에서 DocuSign의 API는 개발자와 기업이 워크플로를 자동화할 수 있는 강력한 도구로 두각을 나타냅니다. 일반적인 과제는 사용자 지정 메타데이터를 기반으로 특정 봉투(DocuSign에서 문서 패키지를 지칭하는 용어)를 검색하는 것입니다. 이러한 기능은 대량의 계약을 처리하는 기업에게 매우 중요하며, 수동으로 필터링할 필요 없이 타겟 검색을 가능하게 합니다. 비즈니스 관점에서 볼 때, 이러한 API 기능을 숙달하면 규정 준수 감사, 판매 추적 및 고객 지원을 간소화하여 궁극적으로 운영 비용을 절감할 수 있습니다.

DocuSign 또는 Adobe Sign과 전자 서명 플랫폼을 비교하고 계십니까?

eSignGlobal은 글로벌 규정 준수, 투명한 가격 책정 및 더 빠른 온보딩 프로세스를 갖춘 보다 유연하고 비용 효율적인 전자 서명 솔루션을 제공합니다.

👉 무료 평가판 시작

DocuSign API에서 봉투 및 사용자 지정 필드 이해하기

DocuSign 봉투는 문서, 수신자 및 서명 필드를 캡슐화하여 전자 서명의 핵심 단위를 나타냅니다. 텍스트 또는 레이블 필드라고도 하는 사용자 지정 필드를 사용하면 사용자가 계약 ID, 고객 이름 또는 상태 태그와 같은 메타데이터를 봉투에 직접 포함할 수 있습니다. 이러한 필드는 단순히 표시용이 아닙니다. CRM 시스템 또는 사용자 지정 대시보드 통합에 매우 유용한 프로그래밍 방식 쿼리를 지원합니다.

비즈니스 관점에서 볼 때, 검색을 위해 사용자 지정 필드를 활용하면 데이터 거버넌스를 향상시킬 수 있습니다. 금융 또는 의료와 같은 규제 산업의 기업은 규정 준수 마커를 기반으로 봉투를 필터링하여 감사 중에 빠른 액세스를 보장하는 데 사용할 수 있습니다. DocuSign의 API는 개발자 플랫폼의 일부이며 RESTful 엔드포인트를 통해 이 기능을 지원하며, Intermediate 요금제(연간 3,600달러)와 같은 가격 책정 계층은 이러한 작업에 대해 매달 최대 100개의 봉투를 제공합니다.

단계별 가이드: 사용자 지정 필드 값을 기반으로 봉투 검색하기

DocuSign API를 통해 사용자 지정 필드 값을 사용하여 봉투를 검색하려면 활성 개발자 계정과 API 자격 증명이 필요합니다. 이 프로세스는 2025년 현재 표준인 eSignature REST API v2.1을 사용한다고 가정합니다. 다음은 공식 문서를 기반으로 한 중립적이고 실용적인 연습입니다.

전제 조건 및 설정

1. API 액세스 권한 얻기: developer.docusign.com에서 DocuSign 개발자 샌드박스에 등록합니다. OAuth 인증에 사용할 통합 키(클라이언트 ID)와 비밀 키를 생성합니다. 프로덕션 환경의 경우 유료 요금제로 업그레이드하십시오. Starter 요금제(연간 600달러)는 기본 검색에 적합합니다.

2. 사용자 지정 필드 정의: 봉투를 만들 때 API를 통해 사용자 지정 필드를 추가합니다. 봉투 정의에서 customFields 객체를 사용합니다. 예:

   {
     "status": "sent",
     "emailSubject": "검토 계약",
     "customFields": {
       "textCustomFields": [
         {
           "name": "ClientID",
           "value": "CLI-12345",
           "required": "false"
         }
       ]
     }
   }
   

   이렇게 하면 "CLI-12345"가 “ClientID” 필드 아래에서 검색 가능한 값으로 포함됩니다.

3. 인증: JWT 또는 Auth Code Grant 흐름을 사용합니다. Python에서(requests 라이브러리 사용) JWT 요청의 예는 다음과 같습니다.

   import requests
   import jwt
   import time
   
   def get_jwt_token(integration_key, user_id, rsa_key, account_id):
       claim = {
           "iss": integration_key,
           "sub": user_id,
           "aud": "account-docusigncom",
           "iat": int(time.time()),
           "exp": int(time.time()) + 3600,
           "scope": "signature impersonation"
       }
       token = jwt.encode(claim, rsa_key, algorithm='RS256')
       response = requests.post(
           "https://account-docusign.com/oauth/token",
           headers={"Authorization": f"Bearer {token}"},
           data={
               "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
               "assertion": token
           }
       )
       return response.json()["access_token"]
   

   자리 표시자를 자격 증명으로 바꿉니다. 이 토큰은 후속 API 호출을 인증하는 데 사용됩니다.

검색 실행

핵심 엔드포인트는 GET /accounts/{accountId}/envelopes/search이지만 사용자 지정 필드 필터링의 경우 쿼리 매개변수와 결합하거나 검색 조건과 함께 더 유연한 GET /envelopes를 사용합니다. DocuSign의 검색 API를 사용하면 봉투 메타데이터(사용자 지정 값 포함)와 일치하는 searchText 매개변수를 통해 사용자 지정 필드로 쿼리할 수 있습니다.

• 기본 검색 엔드포인트: GET /accounts/{accountId}/envelopes?search_text={value}를 사용합니다. 이렇게 하면 봉투 제목, 이름 및 사용자 지정 필드가 검색됩니다.

  정확한 사용자 지정 필드 일치의 경우 고급 검색에서 query 매개변수를 활용합니다. 그러나 직접 사용자 지정 필드 쿼리에는 Envelopes: listStatusChanges 또는 유사한 권한이 필요합니다.

  cURL 요청 예:

  curl -X GET "https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes?search_text=CLI-12345" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json"
  

  응답 스니펫:

  {
    "envelopes": [
      {
        "envelopeId": "abc-123-def",
        "status": "completed",
        "customFields": {
          "textCustomFields": [
            {
              "name": "ClientID",
              "value": "CLI-12345"
            }
          ]
        }
      }
    ]
  }
  

• 사용자 지정 필드를 사용한 고급 필터링: 특정 봉투 검색의 경우 먼저 날짜 범위 또는 상태 내에서 봉투를 검색한 다음 클라이언트 측에서 필터링합니다. DocuSign은 효율성을 높이기 위해 fromDate 및 toDate 매개변수를 search_text와 함께 사용하는 것이 좋습니다. 할당량을 초과하는 경우(예: Intermediate 요금제에서 매달 100개의 봉투) 대량 기능을 위해 Advanced(연간 5,760달러)로 업그레이드하는 것을 고려하십시오.

  코드에서 응답을 구문 분석하여 정확한 사용자 지정 필드 값과 일치시킵니다.

  import json
  
  response = requests.get(
      f"https://demo.docusign.net/restapi/v2.1/accounts/{account_id}/envelopes",
      headers={
          "Authorization": f"Bearer {access_token}",
          "Accept": "application/json"
      },
      params={"search_text": "CLI-12345", "from_date": "2025-01-01T00:00:00Z"}
  )
  envelopes = response.json()["envelopeSummary"]["envelopes"]
  matching_envelopes = [
      env for env in envelopes
      if any(cf["name"] == "ClientID" and cf["value"] == "CLI-12345" for cf in env.get("customFields", {}).get("textCustomFields", []))
  ]
  print(json.dumps(matching_envelopes, indent=2))
  

모범 사례 및 제한 사항

• 할당량 및 비용: 검색은 봉투 API 제한에 포함됩니다. 초과하면 초과 요금이 발생하거나 Enterprise 사용자 지정이 필요합니다.
• 보안: 무단 쿼리를 방지하기 위해 항상 HTTPS 및 역할 기반 액세스 권한을 사용하십시오.
• 오류 처리: 일반적인 문제는 401(잘못된 토큰) 또는 400(잘못된 쿼리)입니다. 디버깅을 위해 응답을 기록합니다.
• 확장성: 대용량 검색의 경우 DocuSign의 Connect 웹후크와 통합하여 업데이트를 푸시하고 폴링 요구 사항을 줄입니다.

이 API 기능은 DocuSign을 자동화된 규정 준수의 리더로 자리매김하지만 기업은 인증과 같은 추가 기능을 포함하여 총 비용을 평가해야 합니다.

DocuSign: 전자 서명 솔루션의 시장 리더

DocuSign은 2004년부터 전자 서명의 선구자였으며 포괄적인 문서 관리 도구를 제공합니다. 전자 서명 플랫폼에는 Personal(연간 120달러)에서 Business Pro(연간 480달러/사용자)까지의 요금제가 포함되어 있으며 API 액세스는 독립적인 개발자 프로그램을 통해 제공됩니다. 주요 기능으로는 템플릿, 대량 전송 및 400개 이상의 애플리케이션과의 통합이 있습니다. 고급 요구 사항의 경우 DocuSign의 Intelligent Agreement Management(IAM)는 CLM(계약 수명 주기 관리)과 AI 기반 통찰력을 결합하여 수정 및 위험 평가를 자동화합니다. IAM은 기업에 적합하지만 가격은 사용자 지정이며 시트 및 봉투 수에 따라 증가할 수 있습니다.

Adobe Sign: 엔터프라이즈 워크플로를 위한 강력한 통합

Adobe Document Cloud의 일부인 Adobe Sign은 PDF 도구 및 크리에이티브 제품군과의 원활한 통합에 탁월합니다. 가격은 개인의 경우 월별 약 10달러/사용자부터 시작하여 엔터프라이즈 사용자 지정 요금제로 확장됩니다. DocuSign과 유사한 사용자 지정 필드 및 API 검색을 지원하며 /agreements와 같은 엔드포인트를 사용하여 메타데이터를 쿼리합니다. 장점으로는 강력한 Adobe 에코시스템 연결 및 글로벌 규정 준수가 있지만 고급 API 기능에는 추가 라이선스가 필요할 수 있습니다. 기업은 서명 옆에 있는 문서 작성에 중점을 둡니다.

eSignGlobal: APAC 및 글로벌 규정 준수를 위한 맞춤형 솔루션

eSignGlobal은 특히 전자 서명 규정이 파편화되고 높은 기준과 엄격한 규제를 받는 아시아 태평양(APAC) 지역에서 전문 플레이어로 두각을 나타냅니다. 이메일 확인 또는 자기 선언에 의존하는 미국 ESIGN/UETA 또는 유럽 eIDAS의 프레임워크와 달리 APAC는 에코시스템 통합의 표준을 요구합니다. 여기에는 기업 간(G2B) 디지털 ID에 대한 정부와의 심층적인 하드웨어/API 수준의 도킹이 포함되어 기술 장벽을 서구 모델보다 훨씬 높입니다. eSignGlobal은 100개의 주요 글로벌 국가 및 지역의 규정 준수를 다루어 이 문제를 해결하고 홍콩과 싱가포르의 로컬 데이터 센터를 통해 APAC에서 우위를 점하고 있습니다. 강력한 인증을 위해 홍콩 iAM Smart 및 싱가포르 Singpass와 같은 원활한 통합을 지원합니다. 가격은 경쟁력이 있으며 Essential 요금제는 연간 299달러(연간 환산 시 월별 약 16.6달러)로 최대 100개의 서명된 문서, 무제한 사용자 시트 및 액세스 코드 확인을 허용합니다. 이 모든 것은 규정 준수, 비용 효율적인 기반을 기반으로 하며 많은 경쟁업체보다 낮으면서도 법적 효력을 유지합니다.

DocuSign보다 더 스마트한 대안을 찾고 계십니까?

eSignGlobal은 글로벌 규정 준수, 투명한 가격 책정 및 더 빠른 온보딩 프로세스를 갖춘 보다 유연하고 비용 효율적인 전자 서명 솔루션을 제공합니다.

👉 무료 평가판 시작

HelloSign (Dropbox Sign): SMB를 위한 간편한 솔루션

현재 Dropbox Sign인 HelloSign은 중소기업을 위한 사용자 친화적인 인터페이스를 우선시합니다. 무료 버전은 매달 최대 3개의 문서를 제공하며 유료 요금제는 매달 15달러부터 시작합니다. API는 /templates 및 /signatures와 같은 엔드포인트를 사용하여 사용자 지정 필드를 통해 봉투 검색을 지원하지만 DocuSign만큼 세분화되지는 않습니다. Dropbox와의 빠른 통합에 적합하며 엔터프라이즈급 사용자 지정보다는 사용 편의성에 중점을 둡니다.

전자 서명 플랫폼의 비교 개요

이 표는 중립적인 절충안을 강조합니다. 선택은 지역 요구 사항과 규모에 따라 달라집니다.

결론적으로 DocuSign의 API는 정확한 봉투 검색을 가능하게 하지만 대안을 탐색하면 특정 시장에 맞게 최적화할 수 있습니다. 지역 규정 준수의 경우 eSignGlobal은 DocuSign의 대안으로 균형 잡힌 옵션을 제공합니다.