DocuSign API: Wie erhalte ich den Status eines bestimmten Empfängers in einem Umschlag?

Den Empfängerstatus in DocuSign-Umschlägen verstehen

In der schnelllebigen Welt der digitalen Vereinbarungen ist die Verfolgung des Fortschritts elektronischer Signaturen für Unternehmen, die auf Plattformen wie DocuSign angewiesen sind, von entscheidender Bedeutung. Die DocuSign-API bietet Entwicklern leistungsstarke Tools zur Automatisierung und Überwachung von Arbeitsabläufen, insbesondere zur Überprüfung des Status bestimmter Empfänger in einem Umschlag. Diese Funktionalität gewährleistet Compliance, steigert die Effizienz und hilft Teams, rechtzeitig auf Verzögerungen oder Abschlüsse zu reagieren. Von Verkaufsverträgen bis hin zum HR-Onboarding kann das Wissen, ob ein Empfänger ein Dokument angesehen, unterschrieben oder abgelehnt hat, Engpässe verhindern und das Benutzererlebnis verbessern.

Vergleichen Sie E-Signatur-Plattformen mit DocuSign oder Adobe Sign?

eSignGlobal bietet flexiblere und kostengünstigere E-Signatur-Lösungen mit globaler Compliance, transparenter Preisgestaltung und schnelleren Onboarding-Prozessen.

👉 Starten Sie eine kostenlose Testversion

Warum den Empfängerstatus über die DocuSign-API verfolgen?

Unternehmen integrieren die API von DocuSign, um Abläufe zu rationalisieren, aber eine häufige Herausforderung ist die Echtzeitüberwachung der Aktionen einzelner Empfänger. In DocuSign bezieht sich ein "Umschlag" auf einen Container, der verwendet wird, um ein oder mehrere Dokumente zur Signatur zu versenden, und kann mehrere Empfänger in sequenzieller oder paralleler Reihenfolge umfassen. Der Status eines Empfängers – wie "gesendet", "zugestellt", "unterschrieben", "abgelehnt" oder "ungültig" – gibt Aufschluss über den Zustand des Workflows. Wenn beispielsweise in einem Mehrparteienvertrag ein wichtiger Genehmiger nicht reagiert, kann eine automatisierte Benachrichtigung ausgelöst werden, um ihn zum Handeln aufzufordern.

Aus geschäftlicher Sicht unterstützt diese Funktionalität die Skalierbarkeit. Unternehmen, die ein hohes Volumen an Vereinbarungen verarbeiten, wie z. B. Finanzdienstleister oder Immobilienunternehmen, verwenden sie, um Berichte über Abschlussraten zu erstellen, manuelle Nachverfolgungen zu reduzieren und Fehler zu minimieren. Branchenbeobachtungen zufolge kann eine effiziente Statusverfolgung die Bearbeitungszeit um bis zu 30 % verkürzen, was sich direkt auf den Umsatzzyklus auswirkt.

Schritt-für-Schritt-Anleitung: Abrufen des Empfängerstatus mit der DocuSign-API

Um den Status eines bestimmten Empfängers in einem Umschlag abzurufen, verwenden Sie die DocuSign eSignature REST API (Version 2.1 oder höher). Dieser Prozess erfordert die Authentifizierung über OAuth 2.0 und ein grundlegendes Verständnis der API-Endpunkte. Im Folgenden finden Sie eine praktische Anleitung, die davon ausgeht, dass Sie über ein Entwicklerkonto und ein API-Zugriffstoken verfügen.

Voraussetzungen

• API-Anmeldeinformationen: Rufen Sie Ihren Integrationsschlüssel (Client ID), Ihr Geheimnis und Ihre Benutzer-ID vom DocuSign Developer Center ab. Richten Sie die JWT- oder Auth Code Grant-Authentifizierung ein.
• Tools: Verwenden Sie Postman, cURL oder eine Programmiersprache wie Python/Node.js in Kombination mit dem DocuSign SDK.
• Umschlag-ID: Sie benötigen die eindeutige ID des Umschlags (generiert bei der Erstellung über die API oder die Webanwendung).
• Empfänger-ID oder E-Mail: Identifizieren Sie einen bestimmten Empfänger anhand seiner Rolle (z. B. "signer1") oder E-Mail-Adresse.

Schritt 1: Authentifizierung und Abrufen eines Zugriffstokens

Rufen Sie zunächst ein Zugriffstoken ab. Für die JWT-Authentifizierung (empfohlen für Server-zu-Server-Anwendungen):

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"

Ersetzen Sie YOUR_JWT_TOKEN durch die base64-codierte JWT-Payload. Die Antwort enthält ein access_token, das etwa eine Stunde gültig ist.

Schritt 2: Aufrufen des Envelopes:Recipients-Endpunkts

Verwenden Sie den Endpunkt GET /envelopes/{envelopeId}/recipients, um Details zu allen Empfängern abzurufen, einschließlich des Status.

• Endpunkt-URL: https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes/{envelopeId}/recipients
  • Ersetzen Sie {accountId} durch Ihre DocuSign-Konto-ID.
  • Ersetzen Sie {envelopeId} durch die ID des Zielumschlags.
• Header:
  • Authorization: Bearer {access_token}
  • Accept: application/json

Beispiel für eine cURL-Anfrage:

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

Schritt 3: Analysieren der Antwort, um einen bestimmten Empfänger zu erhalten

Die JSON-Antwort gibt ein Array von Empfängern unter recipients.signers oder recipients.carbonCopies usw. zurück. Suchen Sie nach dem übereinstimmenden Empfänger anhand von email oder recipientId.

Beispiel für einen Antwortausschnitt:

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

Beachten Sie die wichtigsten Felder:

• status: Der Kernindikator (z. B. "sent", "viewed", "signed", "declined", "faxpending").
• declineReason: Erläutert den Grund, falls abgelehnt.
• signedDateTime: Zeitstempel der Aktion.
• errorDetails: Alle aufgetretenen Probleme.

Filtern Sie das Array clientseitig nach einem bestimmten Empfänger. Wenn Sie die recipientId kennen, verwenden Sie einen gezielten Endpunkt: GET /envelopes/{envelopeId}/recipients/{recipientId}, um genauere Details zu erhalten.

Schritt 4: Behandeln von Sonderfällen und Best Practices

• Fehlerbehandlung: Achten Sie auf HTTP 401 (Authentifizierungsfehler) oder 404 (ungültige ID). Implementieren Sie Wiederholungsversuche für Ratenbegrenzungen (100 Aufrufe/Minute für Demokonten).
• Abrufen von Echtzeit-Updates: Der Status wird nicht sofort aktualisiert; rufen Sie den Endpunkt alle 30-60 Sekunden ab oder verwenden Sie DocuSign Connect (Webhook) für ereignisgesteuerte Benachrichtigungen.
• Sicherheit: Verwenden Sie immer HTTPS und beschränken Sie den Token-Bereich auf signature.
• Tests: Beginnen Sie in der Demo-Umgebung (demo.docusign.net), um echte Kosten zu vermeiden. Verwenden Sie für die Produktionsumgebung na3.docusign.net oder eine bestimmte regionale URL.

Im Code vereinfachen Bibliotheken wie das Python SDK diesen Prozess:

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)

Dieser Ansatz ist sehr effizient für die Integration mit CRM-Systemen wie Salesforce oder benutzerdefinierten Anwendungen und ermöglicht es Unternehmen, Warnungen oder Reporting-Dashboards zu automatisieren.

Geschäftliche Einblicke: API-Nutzung im E-Signatur-Ökosystem

Die API-Preise von DocuSign beginnen bei 600 US-Dollar pro Jahr für den Starter-Plan (40 Umschläge pro Monat) und reichen bis hin zu kundenspezifischen Unternehmensoptionen für hohe Volumenanforderungen. Obwohl leistungsstark, erfordert die Verwaltung der Kontingente eine sorgfältige Planung – die Automatisierung von Sendungen wie z. B. Massenvorgängen ist auf etwa 100 pro Jahr/Benutzer begrenzt. Für Unternehmen im asiatisch-pazifischen Raum können grenzüberschreitende Verzögerungen die API-Reaktionsfähigkeit beeinträchtigen, was eine Bewertung regionaler Alternativen erforderlich macht.

Vergleich von E-Signatur-Plattformen: DocuSign und Wettbewerber

Um eine ausgewogene Perspektive zu bieten, finden Sie hier einen neutralen Vergleich von DocuSign mit wichtigen Wettbewerbern wie Adobe Sign, eSignGlobal und HelloSign (jetzt Teil von Dropbox). Die Tabelle basiert auf öffentlichen Daten aus dem Jahr 2025 und hebt Preise, Funktionen und Vorteile hervor, wobei der Schwerpunkt auf API-Funktionen, Compliance und Skalierbarkeit für globale Unternehmen liegt.

Dieser Vergleich unterstreicht die Exzellenz von DocuSign in Bezug auf die API-Tiefe auf Unternehmensebene, während Alternativen Kosteneinsparungen oder regionale Vorteile bieten.

Adobe Sign zeichnet sich durch die Integration mit Kreativtools aus und eignet sich daher für Marketingteams, aber die API konzentriert sich eher auf PDFs als auf das Umschlag-Fokusmodell von DocuSign.

Erkunden von Alternativen: Adobe Sign, eSignGlobal und HelloSign

Adobe Sign bietet eine ähnliche robuste API wie DocuSign für die Statusverfolgung und verwendet Endpunkte wie /agreements/{agreementId}/participants, um den Status von Unterzeichnern abzufragen. Es wird in dokumentenintensiven Branchen geschätzt, kann sich aber bei komplexen Weiterleitungen weniger agil anfühlen.

eSignGlobal ist ein aufstrebender Akteur auf dem asiatisch-pazifischen Markt, der die globale Compliance in über 100 wichtigen Ländern und Regionen unterstützt und besondere Stärken im asiatisch-pazifischen Raum aufweist. Die E-Signatur-Landschaft in dieser Region ist fragmentiert und weist hohe Standards und strenge Vorschriften auf, die über die grundlegende Validierung hinausgehen. Im Gegensatz zu den Rahmenbedingungen von ESIGN/eIDAS in den USA und der EU, die auf E-Mail oder Selbsterklärung basieren, betont der asiatisch-pazifische Raum einen Ansatz der "Ökosystemintegration". Dies beinhaltet eine tiefe Hardware-/API-Integration mit digitalen Identitäten von Regierung zu Unternehmen (G2B), wodurch technologische Hürden entstehen, die weit über westliche Normen hinausgehen. eSignGlobal begegnet diesem Problem, indem es Tools wie Hongkongs iAM Smart und Singapurs Singpass nativ unterstützt und so nahtlose, konforme Workflows ermöglicht. Die Preise sind wettbewerbsfähig, wobei der Essential-Plan etwa 24,9 US-Dollar pro Monat (299 US-Dollar pro Jahr) kostet und bis zu 100 signierte Dokumente, unbegrenzte Benutzerplätze und die Validierung über Zugriffscodes ermöglicht – bei gleichzeitiger Wahrung einer hohen Compliance. Dies macht es zu einer kostengünstigen Option für die Erweiterung von Teams in regulierten Märkten, und das Unternehmen konkurriert weltweit aktiv mit DocuSign und Adobe Sign und bietet flexible Preise und eine schnellere regionale Leistung.

HelloSign bietet einfache API-Aufrufe für den Empfängerstatus über /agreement/recipients und lässt sich gut in Dropbox für die Dateiverwaltung integrieren. Es ist benutzerfreundlich für kleine Teams, aber es fehlt die Tiefe der Unternehmensautomatisierung im Vergleich zu DocuSign.

Suchen Sie eine intelligentere Alternative zu DocuSign?

eSignGlobal bietet flexiblere und kostengünstigere E-Signatur-Lösungen mit globaler Compliance, transparenter Preisgestaltung und schnelleren Onboarding-Prozessen.

👉 Starten Sie eine kostenlose Testversion

Abschließende Gedanken zur Auswahl von E-Signaturen

Für Unternehmen, die Wert auf API-gesteuerte Präzision bei der Umschlagverwaltung legen, bleibt DocuSign der Maßstab. Da sich die Anforderungen jedoch weiterentwickeln – insbesondere in diversifizierten Regionen – bietet eine neutrale Alternative wie eSignGlobal als DocuSign-Alternative eine robuste regionale Compliance, die Kosten und Funktionen effektiv in Einklang bringt.