如何通过DocuSign REST API获取所有用户收发的信封及收件人信息？

Hey there! As someone who's worked extensively with DocuSign's admin APIs, I can walk you through exactly how to pull full envelope details (including recipient lists) across all your managed accounts—this is totally doable with the eSignature API, and it gives you way more flexibility than the built-in dashboard reports.

1. Set Up Admin-Level Authentication #

Since you're an admin needing access to all accounts, JWT Authentication is the way to go—it lets you authenticate without user interaction, perfect for batch operations. Here's what you'll need:

• An integration key (from your DocuSign developer account)
• An RSA key pair (generate one via the DocuSign admin console or openssl)
• Admin consent for your integration key to access all managed accounts

2. Fetch All Managed Accounts #

First, get a list of all accounts under your admin purview using the Accounts API:

GET /v2.1/accounts

This returns an array of account objects, each with an accountId—you'll need this for every subsequent call to target specific accounts.

3. Pull Envelopes + Recipient Data #

For each account, you have two efficient ways to get envelope details and their recipients:

Option A: Get Envelopes with Recipients Included #

Use the include query parameter to fetch recipient data alongside envelope details in one call, reducing API overhead:

GET /v2.1/accounts/{accountId}/envelopes?include=recipients

You can add filters like from_date/to_date to narrow down results, or status to target specific envelope states (e.g., completed, sent).

Option B: Fetch Envelopes First, Then Recipients #

If you need more granular recipient data (like routing order, delivery status), fetch envelopes first, then call the recipients endpoint for each envelope:

# Get envelope list
GET /v2.1/accounts/{accountId}/envelopes

# Get recipients for a single envelope
GET /v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients

4. Handle Pagination #

DocuSign paginates large result sets (default is 100 items per page). Check the nextUri field in the response—if it exists, make another call to that URI to get the next page of data until nextUri is null.

5. Example Python Snippet #

Here's a quick example to illustrate the flow (using requests):

import requests
import jwt
import time

# JWT Setup
integration_key = "YOUR_INTEGRATION_KEY"
rsa_private_key = open("private_key.pem", "r").read()
admin_user_id = "YOUR_ADMIN_USER_ID"
base_url = "https://demo.docusign.net/restapi" # Switch to production when ready

# Generate JWT Token
payload = {
    "iss": integration_key,
    "sub": admin_user_id,
    "aud": "account-d.docusign.com", # Use "account.docusign.com" for production
    "iat": int(time.time()),
    "exp": int(time.time()) + 3600, # Token expires in 1 hour
    "scope": "signature impersonation"
}
jwt_token = jwt.encode(payload, rsa_private_key, algorithm="RS256")

# Get Access Token
auth_response = requests.post(
    f"{base_url}/v2/oauth2/token",
    data={
        "grant_type": "urn:ietf:params:oauth:grant-type:jwt-bearer",
        "assertion": jwt_token
    }
)
access_token = auth_response.json()["access_token"]
headers = {"Authorization": f"Bearer {access_token}"}

# Fetch All Accounts
accounts_response = requests.get(f"{base_url}/v2.1/accounts", headers=headers)
accounts = accounts_response.json()["accounts"]

# Iterate Over Accounts to Get Envelopes + Recipients
for account in accounts:
    account_id = account["accountId"]
    print(f"Processing account: {account_id}")
    
    # Get Envelopes with Recipients
    envelopes_response = requests.get(
        f"{base_url}/v2.1/accounts/{account_id}/envelopes?include=recipients",
        headers=headers
    )
    envelopes = envelopes_response.json()["envelopes"]
    
    for envelope in envelopes:
        print(f"Envelope ID: {envelope['envelopeId']}, Subject: {envelope['emailSubject']}")
        print("Recipients:")
        for recipient in envelope["recipients"]["signers"]: # Adjust for other recipient types (cc, etc.)
            print(f"- {recipient['name']} ({recipient['email']}) - Status: {recipient['status']}")

Key Notes #

• Rate Limits: DocuSign enforces rate limits (check the X-RateLimit-Limit and X-RateLimit-Remaining headers in responses). If you're pulling large datasets, add delays between calls or use asynchronous processing.
• Permissions: Ensure your admin account has the necessary permissions (Account Read, Envelope Read at minimum) to access all envelopes and recipients across accounts.
• Data Volume: For very large numbers of envelopes, consider using the DocuSign Bulk Export API as an alternative—it's optimized for large-scale data extraction.

内容的提问来源于stack exchange，提问作者Horcrux