Guide d'intégration API

Sur cette page, vous trouverez la description de l'API eSign. Nous commençons par une présentation générale de l'API. Si vous recherchez des exemples, nous vous recommandons l'échantillon Postman, la structure des enveloppes ainsi que nos cas d'usage et exemples.

Principes de l'API v6

• Seuls HTTP GET et POST sont utilisés.
• Nommage cohérent et structures symétriques dans l'API.
• Harmonisation entre l'interface utilisateur Web (WebUI) et l'API, tant au niveau des fonctionnalités que du vocabulaire.
• Terminologie et structures simplifiées.
• Suppression des types abstraits.

Aperçu et Références

L'API est destinée aux développeurs souhaitant intégrer Datasure eSign dans leur application, ainsi qu'aux administrateurs désirant automatiser certaines interactions avec Datasure eSign (ex. : synchronisation des utilisateurs).

Aperçu rapide

eSign utilise une API REST basée sur JSON.

Le workflow de base consiste à :

1. Téléverser un document.
2. Envoyer une enveloppe avec une configuration d’enveloppe.
3. Optionnellement, avant l’envoi, il est possible de préparer l’enveloppe pour récupérer la configuration des étapes de travail (workstep configuration) nécessaires à l’envoi.

Pour plus d’informations sur la configuration des enveloppes, consultez la section Structure des enveloppes.

La configuration d’une enveloppe se compose :

• De la partie enveloppe, qui définit le workflow.
• D’une définition d’action et d’une configuration de signature pour chaque action (workstep configuration).

La configuration des étapes de travail (workstep configuration) est une description au format JSON (REST) des tâches du signataire (ex. : champs de signature, champs de formulaire) ainsi que des configurations supplémentaires du document.

Démarrage rapide

Le moyen le plus simple de commencer est d'activer le mode développeur pour un utilisateur.

En tant que développeur (ou utilisateur avancé), vous pouvez :

• Envoyer des enveloppes via Datasure eSign dans l’interface Web.
• Télécharger la configuration complète de l’enveloppe (y compris les configurations des étapes de travail).

Ainsi, Datasure eSign (espace utilisateur sur esign.datasure.net) peut être utilisé comme un outil de conception de configurations, permettant de préparer facilement une enveloppe. Une fois la configuration téléchargée, il suffit de remplacer les informations et paramètres des destinataires.

Ressources

Référence de l'API REST (Swagger)

Version ≥ 3.1 | Accéder à la documentation API REST

Tutoriels REST

Ces tutoriels vous aident à vous familiariser avec la technologie API et les outils les plus courants pour effectuer des premiers tests d’appels API avant d’implémenter votre propre code d’intégration.

➡️ Consulter le tutoriel REST avec Postman

Tutoriel : Hello World 🌍

Ce tutoriel permet d’approfondir l'intégration de l'API Datasure eSign. Il s’adresse à un public déjà familier avec les outils permettant d’exécuter des appels API, tels que Postman ou SoapUI.

➡️ Accéder au tutoriel Hello World

Mode développeur

➡️ Accéder au mode développeur

Exemple de code en Java

Un exemple de code en JavaSE-12 utilisant l'API REST est disponible.

📥 Télécharger l'exemple Java

eSign Viewer 2019

• Refonte de l'interface
  ➡️ En savoir plus sur eSign Viewer 2019
• Personnalisation avancée
  ➡️ Accéder aux options de personnalisation avancée

Intégration & Cas d'utilisation

➡️ Consulter les intégrations et cas d'utilisation

FAQ Développeur

➡️ Accéder à la FAQ développeur

Codes d'erreur eSign

➡️ Consulter la liste des codes d’erreur

Concepts généraux

Validation des objets

Les objets de type chaîne de caractères (string) et tableau (array) sont soumis à une validation.

Si vous survolez un objet dans la section modèle de la documentation API (ex. : Swagger UI), vous pouvez voir quelles validations sont appliquées.

Exemple de validation

Dans l’exemple suivant, la validation appliquée au tableau Documents impose :

• Un minimum d’un document à inclure.
• Un maximum de 50 documents autorisés.

Pour les objets de type chaîne de caractères (string), la longueur est vérifiée.

Par exemple, dans le cas suivant, la validation impose une longueur maximale de 100 caractères pour la chaîne Name.

Les Ids ont une longueur fixe, ce qui signifie que les valeurs minimale et maximale sont identiques.

Autorisation

Cette section couvre les options d’autorisation pour les intégrations via l’API REST.

L’API REST propose plusieurs méthodes d’autorisation, décrites dans les chapitres suivants.

• Si l'autorisation est valide, la réponse sera un HTTP 200 OK.
• En cas d’échec d’authentification, une erreur HTTP 401 Unauthorized sera retournée.

Utilisation des jetons API

Nous recommandons d’utiliser des jetons API spécifiques à chaque utilisateur.
Chaque utilisateur peut créer plusieurs tokens pour différentes intégrations applicatives.

Le apiToken doit être envoyé dans l’en-tête HTTP de la requête.

Exemples d’autorisation

Autorisation avec Bearer Token

Authorization: Bearer asdfngtmvv8pfmsuaxpzz85zux3e63dd9zttrwitx9mln6qka6tds83du3p3lroe

Autorisation avec un jeton API spécifique

ApiToken: asdfngtmvv8pfmsuaxpzz85zux3e63dd9zttrwitx9mln6qka6tds83du3p3lroe

Création d’un jeton API utilisateur

Un jeton API peut être généré dans Paramètres → API Tokens et Applications, section "API Tokens".

Les jetons créés par Datasure eSign sont actuellement des chaînes alphanumériques de 64 caractères. Toutefois, la longueur et le jeu de caractères autorisés peuvent évoluer dans les futures versions du produit.

Spécification du format

💡 Remarque : La clé API peut être n’importe quelle valeur alphanumérique de 64 caractères et ne suit pas nécessairement le format GUID.

⚠️ Cette spécification peut évoluer dans les versions futures du produit.

Callbacks

L'API permet de définir plusieurs callbacks.

⚠️ Attention :

• Seul le callback d’enveloppe (envoyé directement par Datasure eSign) est déclenché une fois que l’enveloppe atteint un état final.
• Le callback de mise à jour du statut est envoyé par un sous-composant et peut nécessiter un temps de post-traitement avant que l’enveloppe atteigne son état final.

Mécanisme de retries pour les callbacks

Si le serveur ne renvoie pas une réponse HTTP 2xx ou en cas de timeout, l’API réessaiera plusieurs fois l’envoi du callback selon la séquence suivante :

Résumé

• L'API effectue jusqu'à 30 tentatives sur une durée de 36 heures et 15 minutes.
• Si aucune réponse HTTP 2xx n'est reçue après la 30ᵉ tentative, le callback est définitivement abandonné.
• Des notifications d'erreur apparaissent dans l’interface après 10 tentatives échouées.
• L'envoi peut être relancé manuellement depuis l'interface des erreurs.

Types de Callbacks

L'API Datasure eSign prend en charge plusieurs types de callbacks :

• CallbackConfiguration
• Draft Callbacks

Callback d’Enveloppe (Envelope Callback)

Ce callback de base est déclenché lorsque l’enveloppe atteint un état final (terminée ou rejetée). Il est défini via le paramètre :

"CallbackUrl": ""

💡 Remarque : Si vous intégrez Datasure eSign, il est recommandé d’utiliser le callback de statut d’enveloppe (documenté ci-dessous), qui peut fournir plus de détails et être plus utile pour l'intégration.

Placeholders disponibles

• ##EnvelopeId## → Identifiant de l’enveloppe
• ##Action##
  • envelopeFinished → Lorsque l’enveloppe est terminée (complétée ou rejetée).

Exemple de callback d’enveloppe

https://www.mycallback.at?envelope=##EnvelopeId##

Callback de Statut d’Enveloppe (Envelope Status Callback)

Les callbacks de statut d’enveloppe sont déclenchés en fonction d’événements ou d’actions liés à l’enveloppe. Ils sont définis via le paramètre :

"StatusUpdateCallbackUrl": ""

Ces callbacks fournissent des détails supplémentaires sur les actions réalisées sur l’enveloppe.

💡 Remarque :

• Le système attend une URL complète, y compris la liste des paramètres que vous souhaitez recevoir, avec les placeholders qui seront remplacés par leurs valeurs au moment de l’exécution.
• Vous pouvez ajouter vos propres paramètres personnalisés (ex. : références internes).
• Sur les environnements SaaS mutualisés, seuls les callbacks HTTPS sont autorisés (ports 443 et 1025-65535).

Placeholders disponibles pour l’URL de callback

• ##EnvelopeId## → Identifiant de l’enveloppe
• ##Action##
  • workstepFinished → Étape de travail terminée
  • workstepRejected → Étape de travail rejetée
  • workstepDelegated → Étape de travail déléguée
  • workstepOpened → Étape de travail ouverte
  • sendSignNotification → Notification de signature envoyée
  • envelopeExpired → Enveloppe expirée
  • workstepDelegatedSenderActionRequired → Une action de l’expéditeur est requise suite à une délégation

Exemple de callback de statut d’enveloppe

https://www.mycallback.at?envelope=##EnvelopeId##&action=##Action##

Exemple avec un paramètre personnalisé (internalid)

https://www.mycallback.at?envelope=##EnvelopeId##&action=##Action##&internalid=1234

Callbacks d'Événements d'Étape de Travail (Workstep Event Callbacks)

Les callbacks d’événements d’étape de travail sont des notifications spécifiques aux événements déclenchés par le composant sous-jacent "eSIGN Server Platform". Ces événements sont routés à travers le système de notifications de Datasure eSign.

🚨 Important :

• Ces callbacks fournissent des informations plus détaillées sur les événements liés aux étapes de travail (worksteps).
• Cependant, ces événements ne sont pas nécessairement synchronisés avec les événements d’enveloppe.
• Pour déclencher des actions sur l’API Datasure eSign, privilégiez les callbacks d’enveloppe ou les callbacks de statut d’enveloppe.

Configuration détaillée des callbacks sur des événements spécifiques

📌 Proxy pour les callbacks
Il est possible de configurer un proxy pour tous les callbacks.

Exemple de configuration :

<callbackProxySettings>
    <!-- Activer (1) ou désactiver (0) l'utilisation du proxy pour les callbacks -->
    <enabled>0</enabled>
    
    <!-- Adresse du serveur proxy -->
    <address></address>
    
    <!-- Contourner le proxy pour les adresses locales (1 = bypass local, 0 = toujours utiliser le proxy) -->
    <bypassProxyOnLocal>0</bypassProxyOnLocal>
    
    <networkCredentials>
        <!-- Domaine d'authentification -->
        <domain></domain>
        <!-- Nom d'utilisateur -->
        <username></username>
        <!-- Mot de passe (si non chiffré, retirer l’attribut "enc") -->
        <password enc="sec2"></password>
    </networkCredentials>
</callbackProxySettings>

🔹 Remarque :
Les requêtes locales (ex. : http://localhost, http://127.0.0.1) peuvent être configurées pour ne pas utiliser le proxy.

Placeholders définis pour les Workstep Callbacks

Ces placeholders permettent d’envoyer des notifications précises et détaillées sur les événements de signature et d’étapes de travail. 🚀

Types d’événements disponibles pour les callbacks

Les types d’événements suivants peuvent être configurés dans la section CallbackConfiguration.

📌 Remarque :

• L'activation d'un ou plusieurs types d’événements dans cette configuration équivaut à l’approche de whitelist utilisée dans l’API v5.
• Ces événements permettent d’être notifié des actions spécifiques effectuées sur une enveloppe ou une étape de travail (workstep).

Exemple de configuration de callback

"CallbackConfiguration": {
  "CallbackUrl": "string",
  "StatusUpdateCallbackUrl": "string",
  "ActivityActionCallbackConfiguration": {
    "Url": "string",
    "ActionCallbackSelection": {
      "ConfirmTransactionCode": true,
      "DefaultEventType": true,
      "AgreementAccepted": true,
      "AgreementRejected": true,
      "RequestPrepareAuthenticationInformationSuccess": true,
      "PrepareAuthenticationSuccess": true,
      "AuthenticationFailed": true,
      "AuthenticationRejected": true,
      "AuthenticationSuccess": true,
      "ReAuthenticationFailed": true,
      "AuditTrailRequested": true,
      "AuditTrailXmlRequested": true,
      "CalledPage": true,
      "WhoIsInformation": true,
      "DocumentDownloaded": true,
      "FlattenedDocumentDownloaded": true,
      "AddedAnnotation": true,
      "AddedAttachment": true,
      "AppendedDocument": true,
      "FormsFilled": true,
      "ConfirmReading": true,
      "PageViewChanged": true,
      "SendTransactionCode": true,
      "PrepareSignWorkstepDocument": true,
      "SignWorkstepDocument": true,
      "UndoAction": true,
      "WorkstepCreated": true,
      "WorkstepFinished": true,
      "WorkstepRejected": true,
      "DisablePolicyAndValidityChecks": true,
      "EnablePolicyAndValidityChecks": true,
      "AppendFileToWorkstep": true,
      "AppendTasksToWorkstep": true,
      "SetOptionalDocumentState": true,
      "PreparePayloadForBatch": true
    }
  }
}

Liste des types d’événements disponibles

Résumé

• Les callbacks permettent d’être notifié sur divers événements liés aux enveloppes et aux étapes de travail.
• Une configuration flexible permet d'activer uniquement les événements souhaités.
• Utilisation possible d’un proxy pour les callbacks (voir section précédente).
• Ajout de paramètres personnalisés pour enrichir les notifications.

🚀 Avec ces callbacks, il est possible d’automatiser et de surveiller en temps réel les événements de signature et d’authentification !

Callbacks des Brouillons (Draft Callbacks)

Les callbacks de brouillon sont déclenchés lorsqu’un brouillon est utilisé ou supprimé.

🔹 Configuration du callback
Le callback est défini dans CreateDraftOptions via le paramètre :

"AfterSendCallbackUrl": ""

Il est appelé lors de la création d’un brouillon via l’endpoint :
➡️ Draft_Create API

Placeholders disponibles

Types d'actions possibles

Exemple de callback de brouillon

https://www.mycallback.at?draft=##DraftId##

Résumé

• Ces callbacks sont utiles pour suivre l’utilisation ou la suppression de brouillons.
• Ils sont configurés dans CreateDraftOptions via AfterSendCallbackUrl.
• Ils permettent d'être notifié lorsque :
  ✅ Un brouillon est envoyé (draftSent). ❌ Un brouillon est supprimé (draftDiscarded).

🚀 Grâce à ces notifications, vous pouvez surveiller en temps réel la gestion des brouillons dans Datasure eSign.