Intégration avec Postman

Création d’une Collection

Dans ce tutoriel, vous allez réaliser votre premier appel API ainsi que les opérations suivantes :
✅ Envoyer des enveloppes ✅ Téléverser des documents ✅ Télécharger des documents signés

Nous allons commencer par créer une Collection pour regrouper toutes les requêtes.

Étapes :

1️⃣ Accédez à l’onglet "New"
2️⃣ Sélectionnez "Collection"

Création d’une Requête

Après avoir créé une nouvelle Collection, nous allons y enregistrer notre première requête.

Étapes :

1️⃣ Accédez à l’onglet "New"
2️⃣ Sélectionnez "Request" 3️⃣ Choisissez un nom et enregistrez la requête dans la collection

Authentification

L’authentification est une étape essentielle pour exécuter des requêtes API.
Elle garantit à la fois la sécurité et la validation des appels API.

📌 Toutes les requêtes API nécessitent une authentification.

Utilisation d’un jeton API

📌 Exemples d’authentification

✅ Avec un Bearer Token

Authorization: Bearer asdfngtmvv8pfmsuaxpzz85zux3e63dd9zttrwitx9mln6qka6tds83du3p3lroe

✅ Avec un API Token spécifique

ApiToken: asdfngtmvv8pfmsuaxpzz85zux3e63dd9zttrwitx9mln6qka6tds83du3p3lroe

Où trouver votre jeton API ?

➡️ Accédez à Paramètres > API Tokens et Apps

📌 Bonnes pratiques :

Ne partagez pas votre jeton API avec d’autres utilisateurs.
Utilisez des clés API distinctes pour chaque intégration afin d’éviter d’exposer une seule clé à plusieurs systèmes.
En cas de fuite accidentelle, vous pourrez révoquer uniquement la clé compromise sans impacter les autres intégrations.

Premier Appel API : Récupérer la Version

Nous allons commencer par un premier appel API simple afin de vérifier la version actuelle de l’API.

1️⃣ Configuration de la requête

✅ Type de requête : GET
✅ URI :

https://esign.datasure.net/Api/v6/system/version

✅ Authentification : Ajouter le jeton API dans l’en-tête (Header)

📌 Exemple d’en-tête d’authentification

ApiToken: your_api_token_here

2️⃣ Réponse attendue

Si l’appel est réussi, l’API retourne la version actuelle :

"22.20.0.754"

3️⃣ Récapitulatif des étapes

1️⃣ Définir la requête en modeGET
2️⃣ Spécifier l’URL : https://esign.datasure.net/Api/v6/system/version 3️⃣ Ajouter l’authentification (ApiToken) dans l’en-tête 4️⃣ Envoyer la requête et récupérer la version de l’API

🚀 Votre première requête API avec Datasure eSign est maintenant exécutée avec succès ! 🎯

Téléverser un fichier

📌 Important :

Il n’est pas possible de téléverser plusieurs fichiers en une seule requête.
Avant d’envoyer une enveloppe, il faut téléverser un fichier.

1️⃣ Configuration de la requête

✅ Type de requête : POST
✅ URI :

https://demo.esignanywhere.net/Api/v6/file/upload

✅ Authentification : Ajouter le jeton API dans l’en-tête (Header)
✅ Corps de la requête (Body - Form-Data) :

Clé : file
Valeur : Sélectionnez un fichier à téléverser

2️⃣ Réponse attendue

Si l’appel est réussi, l’API retourne un FileId unique :

{
    "FileId": "8ed62e60-6370-433f-9164-2589bc0d73c7"
}

3️⃣ Récapitulatif des étapes

1️⃣ Définir la requête en modePOST
2️⃣ Spécifier l’URL : https://esign.datasure.net/Api/v6/file/upload 3️⃣ Ajouter l’authentification (ApiToken) dans l’en-tête 4️⃣ Sélectionner un fichier dans le corps de la requête (form-data) 5️⃣ Envoyer la requête et récupérer leFileId

📌 Remarque

🔹 LeFileId sera nécessaire pour les appels API suivants (ex. : création d’une enveloppe).

🚀 Votre fichier est maintenant téléversé avec succès ! 🎯

Envoi d'une Enveloppe

📌 Objectif : Envoyer une enveloppe avec le document téléversé précédemment.

✅ Lien vers la documentation API :
🔗 Swagger - Envoi d'Enveloppe

1️⃣ Configuration de la requête

✅ Type de requête : POST
✅ URI :

https://esign.datasure.net/Api/v6/envelope/send

✅ Authentification : Ajouter le jeton API dans l’en-tête (Header)

📌 En-tête d’authentification

ApiToken: your_api_token_here

✅ Corps de la requête (Body) (voir encore plus bas pour l'exemple de configuration json)

Type : raw
Format : JSON
RemplacezFileId par celui obtenu lors du téléversement du fichier.

2️⃣ Exemple de configuration JSON pour l’envoi d’une enveloppe

{
    "Documents": [{
        "FileId": "d33d43ca-1234-1234-1234-b645fc4e0fb2",
        "DocumentNumber": 1
    }],
    "Name": "Test",
    "Activities": [{
        "Action": {
            "Sign": {
                "RecipientConfiguration": {
                    "ContactInformation": {
                        "Email": "jane.doe@sample.com",
                        "GivenName": "Jane",
                        "Surname": "Doe",
                        "LanguageCode": "EN"
                    }
                },
                "Elements": {
                    "Signatures": [{
                        "ElementId": "sample sig click2sign",
                        "Required": true,
                        "DocumentNumber": 1,
                        "DisplayName": "Sign here",
                        "AllowedSignatureTypes": {
                            "ClickToSign": {}
                        },
                        "FieldDefinition": {
                            "Position": {
                                "PageNumber": 1,
                                "X": 100,
                                "Y": 200
                            },
                            "Size": {
                                "Width": 100,
                                "Height": 70
                            }
                        }
                    }]
                },
                "SigningGroup": "firstSigner"
            }
        }
    }, {
        "Action": {
            "SendCopy": {
                "RecipientConfiguration": {
                    "ContactInformation": {
                        "Email": "john.doe@sample.com",
                        "GivenName": "John",
                        "Surname": "Doe",
                        "LanguageCode": "EN"
                    }
                }
            }
        }
    }]
}

3️⃣ Explication du workflow de l’enveloppe

📄 Un document est inclus (FileId doit être remplacé par l'ID réel du fichier téléversé lors du call API précédent).
✍️ Premier destinataire (Jane Doe) signe avec ClickToSign.
📩 Deuxième destinataire (John Doe) reçoit une copie du document signé.

4️⃣ Réponse attendue

Si l’appel est réussi, l’API retourne un EnvelopeId unique :

{
    "EnvelopeId": "4ba56b64-42c0-42ff-97c3-6d8febc7c39e"
}

5️⃣ Récapitulatif des étapes

1️⃣ Définir la requête en modePOST
2️⃣ Spécifier l’URL : https://esign.datasure.net/Api/v6/envelope/send 3️⃣ Ajouter l’authentification (ApiToken) dans l’en-tête 4️⃣ Ajouter la configuration JSON de l’enveloppe dans leBody 5️⃣ Envoyer la requête et récupérer l’EnvelopeId

📌 Remarque

🔹 LeEnvelopeId sera nécessaire pour les appels API suivants, notamment pour récupérer l’état de l’enveloppe ou télécharger le document signé.

🚀 Votre enveloppe est maintenant envoyée avec succès ! 🎯

Ouvrir l’Enveloppe

📌 Objectif :
Après avoir envoyé une enveloppe et obtenu son EnvelopeId, vous pouvez récupérer l’URL de redirection permettant d’ouvrir et de signer le document via l’interface web.

✅ Endpoint API :

https://esign.datasure.net/api/v6/envelope/{envelopeId}/viewerlinks

1️⃣ Configuration de la requête

✅ Type de requête : GET
✅ URI :

https://esign.datasure.net/api/v6/envelope/{envelopeId}/viewerlinks

🔹 Remplacez{envelopeId} par l’ID de l’enveloppe obtenue lors de l’envoi.

✅ Authentification : Ajouter le jeton API dans l’en-tête (Header)

2️⃣ Réponse attendue

Si l’appel est réussi, l’API retourne une liste de liens de visualisation (ViewerLinks), chacun correspondant à un destinataire de l’enveloppe.

{
    "ViewerLinks": [
        {
            "ActivityId": "5609d2ea-1234-1234-1234-1959e63fde64",
            "Email": "john.doe@sample.com",
            "ViewerLink": "https://esign.datasure.net/viewer?token=..."
        }
    ]
}

3️⃣ Explication du retour API

Clé	Description
`ActivityId`	Identifiant de l’activité associée à l’enveloppe.
`Email`	Adresse e-mail du destinataire.
`ViewerLink`	Lien permettant d’ouvrir et de signer l’enveloppe en ligne.

4️⃣ Utilisation du lien de redirection

📌 LeViewerLink permet d’ouvrir et de signer le document directement via un navigateur.

🚀 Intégrez ce lien dans votre portail web pour permettre aux utilisateurs de signer les documents en ligne. 🎯

Télécharger le document signé

📌 Objectif :

Récupérer les identifiants (FileId) des documents signés.
Télécharger les documents à partir de leursFileId.

1️⃣ Récupérer les identifiants des fichiers signés

✅ Type de requête : GET
✅ URI :

https://esign.datasure.net/Api/v6/envelope/{envelopeId}/files

🔹 Remplacez{envelopeId} par l’ID de l’enveloppe.

✅ Authentification : Ajouter le jeton API dans l’en-tête (Header)

🔹 Réponse attendue

{
    "Documents": [
        {
            "FileId": "78b271f2-1234-1234-1234-3799951b1d54",
            "FileName": "Test.pdf",
            "Attachments": [],
            "PageCount": 1,
            "DocumentNumber": 1
        }
    ],
    "AuditTrail": {
        "FileId": "7a86456c-1234-1234-1234-032757afa88e",
        "XmlFileId": "dc60dcd4-1234-1234-1234-8828c79a2c88"
    },
    "Disclaimers": []
}

2️⃣ Télécharger le document signé

Veuillez noter qu'il faut que l'enveloppe soit en "Terminer" pour pouvoir accéder aux documents signés.

✅ Type de requête : GET
✅ URI :

https://esign.datasure.net/Api/v6/file/{fileId}

🔹 Remplacez{fileId} par l’ID du fichier signé récupéré à l’étape précédente.

✅ Authentification : Ajouter le jeton API dans l’en-tête (Header)

📥 Réponse attendue

📌 Le fichier signé (Test.pdf) est téléchargé en réponse à cette requête.

📌 Récapitulatif des étapes

1️⃣ Obtenir la liste des fichiers signés avec :

GET https://esign.datasure.net/Api/v6/envelope/{envelopeId}/files

2️⃣ Récupérer leFileId du document signé dans la réponse JSON.
3️⃣ Télécharger le document avec leFileId via :

GET https://esign.datasure.net/Api/v6/file/{fileId}

🚀 Vous avez maintenant téléchargé le document signé avec succès ! 🎯