DocuSign API：カスタムフィールド値でエンベロープを検索する方法

DocuSign API における効率的なエンベロープナビゲーション

デジタル署名ソリューションの競争環境において、DocuSign の API は、開発者や企業のワークフローを自動化するための強力なツールとして際立っています。一般的な課題の 1 つは、カスタムメタデータに基づいて特定のエンベロープ（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": "Agreement for Review",
     "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 webhook と統合して更新をプッシュし、ポーリングの必要性を減らします。

この API 機能により、DocuSign はコンプライアンス自動化のリーダーとしての地位を確立していますが、企業は認証などのアドオンを含む総コストを評価する必要があります。

DocuSign：電子署名ソリューションの市場リーダー

DocuSign は 2004 年以来、電子署名のパイオニアであり、包括的なドキュメント管理ツールを提供しています。その電子署名プラットフォームには、Personal（年間 120 ドル）から Business Pro（年間 480 ドル/ユーザー）までのプランが含まれており、API アクセスは独立した開発者プログラムを通じて提供されます。主な機能には、テンプレート、一括送信、および 400 以上のアプリケーションとの統合が含まれます。高度なニーズに対応するために、DocuSign の Intelligent Agreement Management (IAM) は、CLM（契約ライフサイクル管理）と AI 駆動の洞察を組み合わせ、改訂とリスク評価を自動化します。IAM は企業に適していますが、価格はカスタムであり、シート数とエンベロープ数によって増加する可能性があります。

Adobe Sign：エンタープライズワークフローの強力な統合

Adobe Sign は Adobe Document Cloud の一部であり、PDF ツールおよびクリエイティブスイートとのシームレスな統合に優れています。価格は個人向けに月額約 10 ドル/ユーザーから始まり、エンタープライズカスタムプランまで拡張されます。DocuSign と同様のカスタムフィールドと API 検索をサポートしており、/agreements などのエンドポイントを使用してメタデータをクエリします。利点には、強力な Adobe エコシステムとの連携とグローバルコンプライアンスが含まれますが、高度な API 機能には追加のライセンスが必要になる場合があります。企業は、署名に加えてドキュメント作成に重点を置いていることを重視しています。

eSignGlobal：APAC およびグローバルコンプライアンス向けのカスタマイズされたソリューション

eSignGlobal は、特にアジア太平洋（APAC）地域において、専門的なプレーヤーとして際立っています。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 向けの簡単なソリューション

HelloSign（現在は Dropbox Sign）は、中小企業向けのユーザーフレンドリーなインターフェイスを優先しています。無料版では月あたり最大 3 つのドキュメント、有料プランは月額 15 ドルから始まります。その API は、/templates や /signatures などのエンドポイントを使用して、カスタムフィールドによるエンベロープ検索をサポートしていますが、DocuSign ほどきめ細かくはありません。Dropbox との迅速な統合に適しており、エンタープライズレベルのカスタマイズではなく、使いやすさに重点を置いています。

電子署名プラットフォームの比較概要

この表は、中立的なトレードオフを強調しています。選択は、地域のニーズと規模によって異なります。

結論として、DocuSign の API は正確なエンベロープ検索を可能にしますが、代替案を検討することで、特定の市場向けに最適化できます。地域のコンプライアンスについては、eSignGlobal が DocuSign の代替案としてバランスの取れたオプションを提供します。