DocuSign API: 봉투 내 특정 수신인의 상태를 어떻게 가져오나요?

DocuSign 봉투의 수신자 상태 이해하기

디지털 계약이 빠르게 발전하는 세상에서 전자 서명 진행 상황을 추적하는 것은 DocuSign과 같은 플랫폼에 의존하는 기업에 매우 중요합니다. DocuSign API는 개발자에게 워크플로를 자동화하고 모니터링할 수 있는 강력한 도구를 제공하며, 특히 봉투 내 특정 수신자의 상태를 확인하는 데 유용합니다. 이 기능은 규정 준수를 보장하고 효율성을 높이며 팀이 지연 또는 완료에 신속하게 대응하도록 돕습니다. 판매 계약에서 HR 온보딩에 이르기까지 수신자가 문서를 확인, 서명 또는 거부했는지 알면 병목 현상을 방지하고 사용자 경험을 향상시킬 수 있습니다.

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

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

👉 무료 평가판 시작하기

DocuSign API를 통해 수신자 상태를 추적하는 이유는 무엇입니까?

기업은 운영을 간소화하기 위해 DocuSign의 API를 통합하지만 일반적인 과제는 개별 수신자의 작업을 실시간으로 모니터링하는 것입니다. DocuSign에서 "봉투"는 서명을 위해 하나 이상의 문서를 보내는 데 사용되는 컨테이너를 의미하며 순차적 또는 병렬 라우팅을 사용하는 여러 수신자가 포함될 수 있습니다. “전송됨”, “배달됨”, “서명됨”, “거부됨” 또는 "무효화됨"과 같은 수신자의 상태는 워크플로 상태에 대한 통찰력을 제공합니다. 예를 들어 다자간 계약에서 주요 승인자가 응답하지 않으면 자동 알림을 트리거하여 진행을 촉구할 수 있습니다.

비즈니스 관점에서 이 기능은 확장성을 지원합니다. 금융 서비스 또는 부동산 회사와 같이 대량 계약을 처리하는 회사는 이를 사용하여 완료율 보고서를 생성하고 수동 후속 조치를 줄이며 오류를 최소화합니다. 업계 관찰에 따르면 효율적인 상태 추적은 처리 시간을 최대 30%까지 단축하여 수익 주기에 직접적인 영향을 미칠 수 있습니다.

단계별 가이드: DocuSign API를 사용하여 수신자 상태 검색하기

봉투 내 특정 수신자의 상태를 가져오려면 DocuSign eSignature REST API(버전 2.1 이상)를 활용합니다. 이 프로세스에는 OAuth 2.0을 통한 인증과 API 엔드포인트에 대한 기본 이해가 필요합니다. 다음은 개발자 계정과 API 액세스 토큰이 있다고 가정하는 실용적인 연습입니다.

전제 조건

• API 자격 증명: DocuSign 개발자 센터에서 통합 키(클라이언트 ID), 비밀 키 및 사용자 ID를 가져옵니다. JWT 또는 Auth Code Grant 인증을 설정합니다.
• 도구: Postman, cURL 또는 DocuSign SDK와 결합된 Python/Node.js와 같은 프로그래밍 언어를 사용합니다.
• 봉투 ID: 봉투의 고유 ID가 필요합니다(API 또는 웹 애플리케이션을 통해 생성 시 생성됨).
• 수신자 ID 또는 이메일: 역할(예: “signer1”) 또는 이메일을 통해 특정 수신자를 식별합니다.

1단계: 인증 및 액세스 토큰 가져오기

먼저 액세스 토큰을 가져옵니다. JWT 인증의 경우(서버 간 애플리케이션에 권장):

curl -X POST "https://account-d.docusign.com/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=YOUR_JWT_TOKEN"

YOUR_JWT_TOKEN을 base64로 인코딩된 JWT 페이로드로 바꿉니다. 응답에는 약 1시간 동안 유효한 access_token이 포함됩니다.

2단계: Envelopes:Recipients 엔드포인트 호출

GET /envelopes/{envelopeId}/recipients 엔드포인트를 사용하여 상태를 포함한 모든 수신자의 세부 정보를 가져옵니다.

• 엔드포인트 URL: https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients
  • {accountId}를 DocuSign 계정 ID로 바꿉니다.
  • {envelopeId}를 대상 봉투의 ID로 바꿉니다.
• 헤더:
  • Authorization: Bearer {access_token}
  • Accept: application/json

cURL 요청 예시:

curl -X GET "https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients" \
  -H "Authorization: Bearer {access_token}"

3단계: 응답을 구문 분석하여 특정 수신자 가져오기

JSON 응답은 recipients.signers 또는 recipients.carbonCopies 등에서 수신자 배열을 반환합니다. email 또는 recipientId를 통해 일치하는 수신자를 찾습니다.

응답 조각 예시:

{
  "recipients": {
    "signers": [
      {
        "email": "recipient@example.com",
        "recipientId": "1",
        "status": "signed",
        "signedDateTime": "2025-01-15T10:30:00Z",
        "deliveryStatus": "delivered"
      }
    ]
  },
  "envelopeId": "{envelopeId}"
}

주목해야 할 주요 필드:

• status: 핵심 지표(예: “sent”, “viewed”, “signed”, “declined”, “faxpending”).
• declineReason: 거부된 경우 이유를 설명합니다.
• signedDateTime: 작업 타임스탬프.
• errorDetails: 발생한 문제.

특정 수신자의 경우 클라이언트에서 배열을 필터링합니다. recipientId를 알고 있는 경우 대상 엔드포인트 GET /envelopes/{envelopeId}/recipients/{recipientId}를 사용하여 더 정확한 세부 정보를 가져올 수 있습니다.

4단계: 에지 케이스 및 모범 사례 처리

• 오류 처리: HTTP 401(인증 실패) 또는 404(잘못된 ID)에 주의하십시오. 속도 제한(데모 계정의 경우 100회 호출/분)에 대한 재시도를 구현합니다.
• 실시간 업데이트 폴링: 상태가 즉시 업데이트되지 않습니다. 30~60초마다 엔드포인트를 폴링하거나 DocuSign Connect(Webhook)를 사용하여 이벤트 기반 알림을 받습니다.
• 보안: 항상 HTTPS를 사용하고 토큰 범위를 signature로 제한합니다.
• 테스트: 실제 비용을 피하기 위해 데모 환경(demo.docusign.net)에서 시작합니다. 프로덕션 환경에서는 na3.docusign.net 또는 특정 지역 URL을 사용합니다.

코드에서 Python SDK와 같은 라이브러리는 이 프로세스를 간소화합니다.

from docusign_esign import ApiClient, EnvelopesApi

api_client = ApiClient()
api_client.host = "https://demo.docusign.net/restapi"
api_client.set_default_header("Authorization", f"Bearer {access_token}")

envelopes_api = EnvelopesApi(api_client)
recipients = envelopes_api.get_recipients(account_id, envelope_id)
specific_recipient = next(r for r in recipients.signers if r.email == "recipient@example.com")
print(specific_recipient.status)

이 방법은 Salesforce와 같은 CRM 시스템 또는 사용자 지정 애플리케이션과의 통합에 매우 효율적이며 기업이 경고 또는 보고 대시보드를 자동화할 수 있도록 합니다.

비즈니스 통찰력: 전자 서명 생태계에서 API 사용

DocuSign의 API 가격은 Starter 플랜의 경우 연간 600달러(월 40개 봉투)부터 시작하여 대용량 요구 사항에 대한 사용자 지정 엔터프라이즈 옵션으로 확장됩니다. 강력하지만 할당량을 신중하게 관리해야 합니다. 대량 작업과 같은 자동화된 전송은 사용자당 연간 약 100개로 제한됩니다. 아시아 태평양 기업의 경우 국경 간 지연이 API 응답성에 영향을 미쳐 지역 대안을 평가해야 할 수 있습니다.

전자 서명 플랫폼 비교: DocuSign과 경쟁사

균형 잡힌 관점을 제공하기 위해 다음은 DocuSign과 Adobe Sign, eSignGlobal 및 HelloSign(현재 Dropbox의 일부)과 같은 주요 경쟁사의 중립적인 비교입니다. 이 표는 2025년 공개 데이터를 기반으로 하며 API 기능, 규정 준수 및 글로벌 기업의 확장성에 중점을 두고 가격, 기능 및 이점을 강조합니다.

이 비교는 엔터프라이즈급 API 깊이에서 DocuSign의 탁월함을 강조하는 반면, 대안은 비용 절감 또는 지역적 이점을 제공합니다.

Adobe Sign은 크리에이티브 도구와의 통합으로 두각을 나타내 마케팅 팀에 적합하지만 API는 DocuSign의 봉투 중심 모델이 아닌 PDF에 더 중점을 둡니다.

대안 살펴보기: Adobe Sign, eSignGlobal 및 HelloSign

Adobe Sign은 서명자 상태를 쿼리하기 위해 /agreements/{agreementId}/participants 엔드포인트를 사용하는 상태 추적을 위한 DocuSign과 유사한 안정적인 API를 제공합니다. 문서 집약적인 산업에서 높이 평가되지만 복잡한 라우팅에는 덜 민첩하게 느껴질 수 있습니다.

eSignGlobal은 아시아 태평양 시장의 신흥 기업으로 100개의 주요 국가 및 지역에서 글로벌 규정 준수를 지원하며 아시아 태평양 지역에서 특히 강점을 보입니다. 이 지역의 전자 서명 환경은 파편화되어 있으며 높은 표준과 엄격한 규정이 있어 기본 검증 이상의 내용이 필요합니다. 미국과 EU가 이메일 또는 자기 선언 프레임워크 ESIGN/eIDAS 표준에 의존하는 것과 달리 아시아 태평양은 “에코시스템 통합” 접근 방식을 강조합니다. 여기에는 정부 대 기업(G2B) 디지털 ID와의 심층적인 하드웨어/API 수준 통합이 포함되어 서구 규범을 훨씬 능가하는 기술 장벽이 높아집니다. eSignGlobal은 홍콩의 iAM Smart 및 싱가포르의 Singpass와 같은 도구를 기본적으로 지원하여 원활하고 규정을 준수하는 워크플로를 구현하여 이 문제를 해결합니다. 가격은 경쟁력이 있으며 Essential 플랜은 월 약 24.9달러(연간 299달러)로 최대 100개의 서명된 문서, 무제한 사용자 좌석 및 액세스 코드를 통한 검증을 허용하면서 높은 규정 준수를 유지합니다. 따라서 규제 대상 시장에서 팀을 확장하는 데 비용 효율적인 옵션이며 회사는 유연한 가격 책정과 더 빠른 지역 성능을 제공하여 전 세계적으로 DocuSign 및 Adobe Sign과 적극적으로 경쟁하고 있습니다.

HelloSign은 /agreement/recipients를 통해 수신자 상태에 대한 간단한 API 호출을 제공하며 파일 관리를 위해 Dropbox와 잘 통합됩니다. 소규모 팀에 적합하지만 DocuSign에 비해 엔터프라이즈 자동화 깊이가 부족합니다.

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

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

👉 무료 평가판 시작하기

전자 서명 선택에 대한 최종 생각

API 기반 봉투 관리 정확성을 우선시하는 기업의 경우 DocuSign은 여전히 기준입니다. 그러나 요구 사항이 진화함에 따라, 특히 다양한 지역에서 eSignGlobal과 같은 중립적인 대안은 강력한 지역 규정 준수를 제공하여 비용과 기능을 효과적으로 균형을 맞추는 DocuSign의 대안으로 부상하고 있습니다.