API DocuSign : Comment rechercher des enveloppes par valeur de champ personnalisé ?

Gestion efficace de la navigation dans les enveloppes de l'API DocuSign

Dans le paysage concurrentiel des solutions de signature numérique, l'API de DocuSign se distingue comme un outil puissant pour les développeurs et les entreprises qui automatisent les flux de travail. Un défi courant consiste à récupérer des enveloppes spécifiques (le terme utilisé par DocuSign pour désigner les paquets de documents) en fonction de métadonnées personnalisées. Cette capacité est essentielle pour les entreprises qui traitent un grand nombre d'accords, car elle permet des recherches ciblées sans avoir à effectuer de tri manuel. D'un point de vue commercial, la maîtrise de ces fonctionnalités de l'API peut rationaliser les audits de conformité, le suivi des ventes et le support client, ce qui permet de réduire les coûts d'exploitation.

Vous comparez les plateformes de signature électronique avec DocuSign ou Adobe Sign ?

eSignGlobal offre une solution de signature électronique plus flexible et plus rentable, avec une conformité mondiale, une tarification transparente et un processus d'intégration plus rapide.

👉 Démarrez un essai gratuit

Comprendre les enveloppes et les champs personnalisés dans l'API DocuSign

Une enveloppe DocuSign représente l'unité centrale de la signature électronique, encapsulant les documents, les destinataires et les champs de signature. Les champs personnalisés, également appelés champs de texte ou d'étiquette, permettent aux utilisateurs d'intégrer directement des métadonnées (telles que l'ID du contrat, le nom du client ou les étiquettes d'état) dans l'enveloppe. Ces champs ne servent pas uniquement à l'affichage ; ils permettent des requêtes programmatiques, ce qui est très utile pour l'intégration avec les systèmes CRM ou les tableaux de bord personnalisés.

D'un point de vue commercial, l'utilisation de champs personnalisés pour la recherche peut améliorer la gouvernance des données. Les entreprises des secteurs réglementés, tels que la finance ou la santé, peuvent les utiliser pour filtrer les enveloppes en fonction des balises de conformité, garantissant ainsi un accès rapide lors des audits. L'API de DocuSign, qui fait partie de sa plateforme de développement, prend en charge cette fonctionnalité via des points de terminaison RESTful, avec des niveaux de tarification tels que le plan Intermédiaire (3 600 $ par an) offrant jusqu'à 100 enveloppes par mois pour de telles opérations.

Guide étape par étape : Recherche d'enveloppes par valeur de champ personnalisé

Pour rechercher des enveloppes à l'aide de valeurs de champs personnalisés via l'API DocuSign, vous avez besoin d'un compte de développeur actif et d'informations d'identification API. Cette procédure suppose que vous utilisez l'API REST eSignature v2.1, qui est la norme actuelle en 2025. Voici une procédure neutre et pratique basée sur la documentation officielle.

Prérequis et configuration

1. Obtenir l'accès à l'API : Inscrivez-vous à un bac à sable de développeur DocuSign sur developer.docusign.com. Générez une clé d'intégration (ID client) et une clé à utiliser pour l'authentification OAuth. Pour l'environnement de production, passez à un plan payant : le plan Starter (600 $ par an) convient pour les recherches de base.

2. Définir des champs personnalisés : Lors de la création d'une enveloppe, ajoutez des champs personnalisés via l'API. Utilisez l'objet customFields dans la définition de l'enveloppe. Par exemple :

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

   Cela intègre "CLI-12345" comme valeur recherchable sous le champ "ClientID".

3. Authentification : Utilisez le flux JWT ou Auth Code Grant. Un exemple de requête JWT en Python (à l'aide de la bibliothèque requests) est le suivant :

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

   Remplacez les espaces réservés par vos informations d'identification. Ce jeton est utilisé pour authentifier les appels d'API ultérieurs.

Exécution de la recherche

Le point de terminaison clé est GET /accounts/{accountId}/envelopes/search, mais pour le filtrage des champs personnalisés, combinez les paramètres de requête ou utilisez le GET /envelopes plus flexible avec des critères de recherche. L'API de recherche de DocuSign permet d'interroger les champs personnalisés via le paramètre searchText, qui correspond aux métadonnées de l'enveloppe, y compris les valeurs personnalisées.

• Point de terminaison de recherche de base : Utilisez GET /accounts/{accountId}/envelopes?search_text={value}. Cela analyse les sujets, les noms et les champs personnalisés des enveloppes.

  Pour une correspondance exacte des champs personnalisés, utilisez le paramètre query dans la recherche avancée. Cependant, les requêtes directes de champs personnalisés nécessitent des autorisations telles que Envelopes: listStatusChanges ou similaires.

  Exemple de requête 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"
  

  Extrait de réponse :

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

• Filtrage avancé avec des champs personnalisés : Pour les recherches d'enveloppes spécifiques, récupérez d'abord les enveloppes dans une plage de dates ou un état, puis filtrez côté client. DocuSign recommande de combiner les paramètres fromDate et toDate avec search_text pour plus d'efficacité. Si votre volume dépasse les quotas (par exemple, 100 enveloppes par mois pour le plan Intermédiaire), envisagez de passer à Advanced (5 760 $ par an) pour les fonctionnalités de traitement par lots.

  Dans le code, analysez la réponse pour faire correspondre les valeurs exactes des champs personnalisés :

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

Bonnes pratiques et limitations

• Quotas et coûts : Les recherches sont comptabilisées dans les limites de l'API Envelope. Le dépassement entraînera des frais supplémentaires ou nécessitera une personnalisation Enterprise.
• Sécurité : Utilisez toujours HTTPS et un contrôle d'accès basé sur les rôles pour empêcher les requêtes non autorisées.
• Gestion des erreurs : Les problèmes courants incluent 401 (jeton non valide) ou 400 (requête non valide). Enregistrez les réponses pour le débogage.
• Évolutivité : Pour les recherches à volume élevé, intégrez-vous à DocuSign's Connect webhook pour les mises à jour push, réduisant ainsi les besoins en interrogation.

Cette fonctionnalité API positionne DocuSign comme un leader de l'automatisation de la conformité, bien que les entreprises doivent évaluer le coût total, y compris les modules complémentaires tels que l'authentification.

DocuSign : Leader du marché des solutions de signature électronique

DocuSign est un pionnier de la signature électronique depuis 2004, offrant une suite complète d'outils de gestion de documents. Sa plateforme eSignature comprend des plans allant de Personal (120 $ par an) à Business Pro (480 $ par an/utilisateur), l'accès à l'API se faisant via un plan de développeur distinct. Les fonctionnalités clés incluent les modèles, l'envoi groupé et l'intégration avec plus de 400 applications. Pour les besoins avancés, Intelligent Agreement Management (IAM) de DocuSign combine CLM (Contract Lifecycle Management) avec des informations basées sur l'IA, automatisant la révision et l'évaluation des risques. IAM convient aux entreprises, bien que la tarification soit personnalisée et puisse augmenter avec le nombre de sièges et d'enveloppes.

Adobe Sign : Intégration puissante pour les flux de travail d'entreprise

Adobe Sign, qui fait partie d'Adobe Document Cloud, excelle dans l'intégration transparente avec les outils PDF et les suites créatives. La tarification commence à environ 10 $/utilisateur par mois pour les particuliers, s'étendant aux plans personnalisés pour les entreprises. Il prend en charge les champs personnalisés et la recherche API similaires à DocuSign, en utilisant des points de terminaison tels que /agreements pour interroger les métadonnées. Les avantages incluent une forte affinité avec l'écosystème Adobe et la conformité mondiale, mais les fonctionnalités API avancées peuvent nécessiter des licences supplémentaires. Les entreprises apprécient son accent sur la création de documents aux côtés de la signature.

eSignGlobal : Solutions sur mesure pour la conformité APAC et mondiale

eSignGlobal se distingue comme un acteur spécialisé, en particulier dans la région Asie-Pacifique (APAC), où les réglementations en matière de signature électronique sont fragmentées, très normées et strictement réglementées. Contrairement aux cadres américains ESIGN/UETA ou européens eIDAS - qui s'appuient sur la vérification par e-mail ou l'auto-déclaration - l'APAC exige des normes d'intégration de l'écosystème. Cela implique un couplage profond au niveau du matériel/API avec les identités numériques gouvernementales à entreprise (G2B), ce qui augmente considérablement les barrières technologiques au-delà des modèles occidentaux. eSignGlobal relève ce défi en couvrant la conformité dans plus de 100 pays et régions du monde, avec une forte présence dans la région APAC grâce à des centres de données locaux à Hong Kong et à Singapour. Il prend en charge l'intégration transparente avec iAM Smart de Hong Kong et Singpass de Singapour pour une authentification forte. La tarification est compétitive, avec un plan Essential à 299 $ par an (environ 16,6 $ par mois annualisés), permettant jusqu'à 100 documents signés, des sièges d'utilisateurs illimités et la vérification du code d'accès - le tout sur une base de conformité et de rentabilité inférieure à celle de nombreux concurrents tout en maintenant la force juridique.

Vous recherchez une alternative plus intelligente à DocuSign ?

eSignGlobal offre une solution de signature électronique plus flexible et plus rentable, avec une conformité mondiale, une tarification transparente et un processus d'intégration plus rapide.

👉 Démarrez un essai gratuit

HelloSign (Dropbox Sign) : Solution simple pour les PME

HelloSign, maintenant Dropbox Sign, privilégie une interface conviviale pour les petites et moyennes entreprises. Une version gratuite permet jusqu'à trois documents par mois, avec des plans payants à partir de 15 $ par mois. Son API prend en charge la recherche d'enveloppes via des champs personnalisés, en utilisant des points de terminaison tels que /templates et /signatures, bien que moins granulaire que DocuSign. Convient pour une intégration rapide avec Dropbox, l'accent étant mis sur la facilité d'utilisation plutôt que sur la personnalisation de niveau entreprise.

Aperçu comparatif des plateformes de signature électronique

Ce tableau met en évidence les compromis neutres ; le choix dépend des besoins régionaux et de l'échelle.

En conclusion, bien que l'API de DocuSign permette une recherche précise d'enveloppes, l'exploration d'alternatives peut optimiser pour des marchés spécifiques. Pour la conformité régionale, eSignGlobal offre une option équilibrée en tant qu'alternative à DocuSign.