DocuSign API: Wie sucht man Umschläge anhand von benutzerdefinierten Feldwerten?

Effizientes Management der Envelope-Navigation in der DocuSign API

In der wettbewerbsorientierten Landschaft der digitalen Signaturlösungen sticht die API von DocuSign als leistungsstarkes Werkzeug für Entwickler und Unternehmen zur Automatisierung von Arbeitsabläufen hervor. Eine häufige Herausforderung besteht darin, bestimmte Envelopes – DocuSigns Bezeichnung für Dokumentenpakete – anhand von benutzerdefinierten Metadaten abzurufen. Diese Fähigkeit ist für Unternehmen, die eine große Anzahl von Vereinbarungen verarbeiten, von entscheidender Bedeutung, da sie gezielte Suchen ermöglicht, ohne dass eine manuelle Filterung erforderlich ist. Aus geschäftlicher Sicht kann die Beherrschung solcher API-Funktionen die Compliance-Prüfungen, die Vertriebsverfolgung und den Kundensupport rationalisieren und letztendlich die Betriebskosten senken.

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

Verständnis von Envelopes und benutzerdefinierten Feldern in der DocuSign API

Ein DocuSign-Envelope stellt die Kerneinheit für elektronische Signaturen dar und umfasst Dokumente, Empfänger und Signaturfelder. Benutzerdefinierte Felder, auch Text- oder Beschriftungsfelder genannt, ermöglichen es Benutzern, Metadaten wie Vertrags-IDs, Kundennamen oder Status-Tags direkt in den Envelope einzubetten. Diese Felder dienen nicht nur zur Anzeige; sie unterstützen programmatische Abfragen, was für die Integration in CRM-Systeme oder benutzerdefinierte Dashboards von unschätzbarem Wert ist.

Aus geschäftlicher Sicht kann die Nutzung benutzerdefinierter Felder für die Suche die Datenverwaltung verbessern. Unternehmen in regulierten Branchen wie dem Finanz- oder Gesundheitswesen können sie verwenden, um Envelopes anhand von Compliance-Markierungen zu filtern und so einen schnellen Zugriff während Audits zu gewährleisten. Die API von DocuSign ist Teil ihrer Entwicklerplattform und unterstützt diese Funktionalität über RESTful-Endpunkte, wobei Preisstufen wie der Intermediate-Plan (3.600 US-Dollar pro Jahr) bis zu 100 Envelopes pro Monat für solche Operationen bieten.

Schritt-für-Schritt-Anleitung: Suchen von Envelopes anhand von Werten in benutzerdefinierten Feldern

Um Envelopes über die DocuSign API anhand von Werten in benutzerdefinierten Feldern zu suchen, benötigen Sie ein aktives Entwicklerkonto und API-Zugangsdaten. Dieses Verfahren setzt voraus, dass Sie die eSignature REST API v2.1 verwenden, den aktuellen Standard von 2025. Im Folgenden finden Sie eine neutrale, praktische Anleitung, die auf der offiziellen Dokumentation basiert.

Voraussetzungen und Einrichtung

1. API-Zugriff erhalten: Registrieren Sie sich für eine DocuSign-Entwickler-Sandbox unter developer.docusign.com. Generieren Sie einen Integrationsschlüssel (Client-ID) und einen geheimen Schlüssel für die OAuth-Authentifizierung. Für Produktionsumgebungen aktualisieren Sie auf einen kostenpflichtigen Plan – der Starter-Plan (600 US-Dollar pro Jahr) ist für grundlegende Suchen geeignet.

2. Benutzerdefinierte Felder definieren: Fügen Sie beim Erstellen eines Envelopes benutzerdefinierte Felder über die API hinzu. Verwenden Sie das Objekt customFields in der Envelope-Definition. Zum Beispiel:

   {
     "status": "sent",
     "emailSubject": "Agreement for Review",
     "customFields": {
       "textCustomFields": [
         {
           "name": "ClientID",
           "value": "CLI-12345",
           "required": "false"
         }
       ]
     }
   }
   

   Dadurch wird "CLI-12345" als durchsuchbarer Wert unter dem Feld "ClientID" eingebettet.

3. Authentifizierung: Verwenden Sie den JWT- oder Auth Code Grant-Flow. Ein Beispiel für eine JWT-Anfrage in Python (mit der Bibliothek requests) sieht wie folgt aus:

   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"]
   

   Ersetzen Sie die Platzhalter durch Ihre Zugangsdaten. Dieses Token wird zur Authentifizierung nachfolgender API-Aufrufe verwendet.

Ausführen der Suche

Der wichtigste Endpunkt ist GET /accounts/{accountId}/envelopes/search, aber für die Filterung nach benutzerdefinierten Feldern kombinieren Sie Abfrageparameter oder verwenden Sie flexibler GET /envelopes mit Suchkriterien. Die Such-API von DocuSign ermöglicht die Abfrage nach benutzerdefinierten Feldern über den Parameter searchText, der Envelope-Metadaten einschließlich benutzerdefinierter Werte abgleicht.

• Grundlegender Such-Endpunkt: Verwenden Sie GET /accounts/{accountId}/envelopes?search_text={value}. Dadurch werden Envelope-Betreff, -Name und benutzerdefinierte Felder durchsucht.

  Für eine genaue Übereinstimmung mit benutzerdefinierten Feldern verwenden Sie den Parameter query in der erweiterten Suche. Direkte Abfragen nach benutzerdefinierten Feldern erfordern jedoch Envelopes: listStatusChanges oder ähnliche Berechtigungen.

  Beispiel für eine cURL-Anfrage:

  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"
  

  Antwort-Snippet:

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

• Erweiterte Filterung mit benutzerdefinierten Feldern: Für bestimmte Envelope-Suchen rufen Sie zunächst Envelopes innerhalb eines Datumsbereichs oder Status ab und filtern Sie dann clientseitig. DocuSign empfiehlt, die Parameter fromDate und toDate in Kombination mit search_text zu verwenden, um die Effizienz zu steigern. Wenn Ihre Mengen das Kontingent überschreiten (z. B. 100 Envelopes pro Monat im Intermediate-Plan), sollten Sie ein Upgrade auf Advanced (5.760 US-Dollar pro Jahr) für Batch-Funktionen in Betracht ziehen.

  Analysieren Sie in Ihrem Code die Antwort, um genaue Werte für benutzerdefinierte Felder zu finden:

  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))
  

Best Practices und Einschränkungen

• Kontingente und Kosten: Suchen werden auf die Envelope-API-Limits angerechnet. Überschreitungen führen zu zusätzlichen Gebühren oder erfordern eine Enterprise-Anpassung.
• Sicherheit: Verwenden Sie immer HTTPS und rollenbasierte Zugriffskontrollen, um unbefugte Abfragen zu verhindern.
• Fehlerbehandlung: Häufige Probleme sind 401 (ungültiges Token) oder 400 (ungültige Abfrage). Protokollieren Sie Antworten zur Fehlersuche.
• Skalierbarkeit: Für Suchen mit hohem Volumen integrieren Sie sich in DocuSigns Connect-Webhook, um Aktualisierungen zu pushen und den Bedarf an Polling zu reduzieren.

Diese API-Funktionen positionieren DocuSign als führendes Unternehmen im Bereich der automatisierten Compliance, obwohl Unternehmen die Gesamtkosten, einschließlich Add-ons wie die Identitätsprüfung, bewerten sollten.

DocuSign: Marktführer für E-Signatur-Lösungen

DocuSign ist seit 2004 ein Pionier im Bereich der elektronischen Signaturen und bietet umfassende Tools für das Dokumentenmanagement. Die E-Signatur-Plattform umfasst Pläne von Personal (120 US-Dollar pro Jahr) bis Business Pro (480 US-Dollar pro Benutzer und Jahr), wobei der API-Zugriff über separate Entwicklerpläne erfolgt. Zu den wichtigsten Funktionen gehören Vorlagen, Massenversand und Integrationen mit über 400 Anwendungen. Für erweiterte Anforderungen kombiniert DocuSigns Intelligent Agreement Management (IAM) CLM (Contract Lifecycle Management) mit KI-gestützten Erkenntnissen, um Überarbeitungen und Risikobewertungen zu automatisieren. IAM ist für Unternehmen geeignet, obwohl die Preise individuell sind und mit der Anzahl der Sitze und Envelopes steigen können.

Adobe Sign: Leistungsstarke Integration für Unternehmensworkflows

Adobe Sign, Teil der Adobe Document Cloud, zeichnet sich durch die nahtlose Integration mit PDF-Tools und der Creative Suite aus. Die Preise beginnen bei etwa 10 US-Dollar pro Benutzer und Monat für Einzelpersonen und reichen bis zu benutzerdefinierten Enterprise-Plänen. Es unterstützt ähnliche benutzerdefinierte Felder und API-Suchen wie DocuSign und verwendet Endpunkte wie /agreements zum Abfragen von Metadaten. Zu den Vorteilen gehören die starke Verbindung zum Adobe-Ökosystem und die globale Compliance, aber erweiterte API-Funktionen erfordern möglicherweise zusätzliche Lizenzen. Unternehmen schätzen den Fokus auf die Dokumentenerstellung neben der Signatur.

eSignGlobal: Maßgeschneiderte Lösungen für APAC und globale Compliance

eSignGlobal sticht als spezialisierter Akteur hervor, insbesondere in der Region Asien-Pazifik (APAC), wo die Vorschriften für elektronische Signaturen fragmentiert, hochstandardisiert und streng reguliert sind. Im Gegensatz zu den Rahmenbedingungen von US ESIGN/UETA oder EU eIDAS – die sich auf E-Mail-Verifizierung oder Selbsterklärung verlassen – erfordert APAC Ökosystemintegrationen, die Standard sind. Dies beinhaltet eine tiefe Hardware-/API-Integration mit digitalen Identitäten von Regierung zu Unternehmen (G2B), wodurch die technischen Hürden deutlich höher sind als bei westlichen Modellen. eSignGlobal begegnet diesem Problem, indem es die Compliance in über 100 wichtigen globalen Ländern und Regionen abdeckt und durch lokale Rechenzentren in Hongkong und Singapur eine starke Präsenz in APAC hat. Es unterstützt die nahtlose Integration mit Hongkong iAM Smart und Singapur Singpass für eine robuste Authentifizierung. Die Preise sind wettbewerbsfähig, wobei der Essential-Plan 299 US-Dollar pro Jahr kostet (was jährlich etwa 16,6 US-Dollar pro Monat entspricht) und bis zu 100 signierte Dokumente, unbegrenzte Benutzerplätze und Zugriffscode-Verifizierung ermöglicht – alles auf einer Compliance-orientierten, kostengünstigen Basis, die unter vielen Wettbewerbern liegt und gleichzeitig die Rechtsgültigkeit gewährleistet.

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

HelloSign (Dropbox Sign): Einfache Lösung für KMUs

HelloSign, jetzt Dropbox Sign, priorisiert eine benutzerfreundliche Oberfläche für kleine und mittlere Unternehmen. Die kostenlose Version bietet bis zu drei Dokumente pro Monat, kostenpflichtige Pläne beginnen bei 15 US-Dollar pro Monat. Die API unterstützt die Envelope-Suche über benutzerdefinierte Felder und verwendet Endpunkte wie /templates und /signatures, ist aber weniger detailliert als DocuSign. Geeignet für die schnelle Integration mit Dropbox, wobei der Schwerpunkt auf Benutzerfreundlichkeit und nicht auf unternehmensweiter Anpassung liegt.

Vergleichende Übersicht über E-Signatur-Plattformen

Diese Tabelle hebt neutrale Kompromisse hervor; die Wahl hängt von den regionalen Bedürfnissen und der Größe ab.

Zusammenfassend lässt sich sagen, dass die API von DocuSign zwar eine präzise Envelope-Suche ermöglicht, die Erkundung von Alternativen jedoch die Optimierung für bestimmte Märkte ermöglichen kann. Für die regionale Compliance bietet eSignGlobal als DocuSign-Alternative eine ausgewogene Option.