Aller au contenu principal

Tutoriel de démarrage rapide

Un accès API nécessite une approbation

Pour utiliser l’API Legalesign, vous devez nous contacter pour obtenir l'autorisation d'utiliser l'API pour votre compte.

astuce

Vous utilisez Cursor, Claude ou un autre outil de codage IA ? Connectez-le à la documentation Legalesign pour une aide contextuelle pendant que vous suivez ce tutoriel.

Dans ce tutoriel, vous effectuerez les appels API clés dont la plupart des développeurs ont besoin dans une intégration eSignature - téléverser un document et l'envoyer pour signature.

L’API Legalesign est évolutive, polyvalente, et testée en production dans les systèmes de nos clients depuis de nombreuses années. Vous pouvez l’utiliser pour un simple document avec un seul signataire, ou envoyer des documents pour authentification ou approbations, optimisée pour les lots, avec des formulaires et plus encore. Vous pouvez l’intégrer pour un seul usage ou l’embarquer dans votre logiciel pour vos clients - voir les intégrations.

L’API REST effectue la plupart des fonctions et est le moyen le plus simple pour commencer. Si vous avez besoin de plus, consultez l’interface GraphQL. Legalesign est API first avec GraphQL. Vous pouvez utiliser l’un ou l’autre selon votre préférence.

Nous suivrons ces étapes :

  1. Créer un compte + clé API (voir Obtenir la vérification pour l'accès API).
  2. Confirmer que les identifiants fonctionnent et obtenir votre ID d’équipe.
  3. Téléverser un document via l’application web.
  4. Envoyer ce document à signer via l’API.
  5. Le télécharger après signature.
  6. Téléverser un document via l’API.

L’API REST Legalesign est facile à utiliser. La référence technique inclut un éditeur de code. Vous pouvez faire des requêtes directement depuis la référence technique avec votre clé API, mais sinon, copiez simplement et collez directement dans votre code.

Image du générateur de code
Figure 1 : L’éditeur de code de l’API REST.

Bibliothèques clientes

Ou pour l’interface GraphQL Node.js

astuce

Nous recommandons que les développeurs travaillent directement avec l’API plutôt qu’avec les SDK. Pour aider, il y a un générateur de code à couper-coller dans la spécification technique, et votre IA peut rapidement produire des exemples en utilisant la spec OpenAPI. Pourquoi ? L’API source a davantage de fonctionnalités que les SDK, vous voudrez de toute façon connaître les endpoints que vous utilisez, vous éviterez la surcharge d’abstraction et les dépendances, et—d’après notre expérience—cela vous fera gagner du temps.

1. Créer un compte

Rendez-vous sur inscription Legalesign. Utilisez un email classique pour créer le compte (n’utilisez pas Google), les identités fédérées comme Google ne fonctionneront pas avec l’API.

Vous serez invité à créer une équipe. Les équipes sont les éléments de base de Legalesign. Tout le traitement des documents se fait dans une équipe. Vous devez faire référence à votre équipe dans la plupart des appels API.

info

Une « équipe » ou un « groupe » désignent la même chose. Dans l’application web nous parlons d’« équipes », mais dans le schéma API c’est un groupe.

Contactez le support pour obtenir une clé API. Expliquez votre cas d'usage, votre expérience en développement API, et quelques détails pour confirmer que vous êtes réel (par ex. détails de votre lieu de travail).

Paramètres API

Une fois vérifié, rendez-vous sur le Tableau de bord API. Générez vos identifiants API dans la section Clé API.

Prenez un moment pour parcourir le Portail développeur.

Bac à sable

Dans la section Environnement, une alerte indique si vous êtes en mode bac à sable ou production.

Le bac à sable limite où vous pouvez envoyer vos documents. Vous verrez un formulaire pour ajouter jusqu’à 5 emails approuvés - ajoutez-en quelques-uns maintenant.

Quand votre intégration sera prête : passez en mode production.

astuce

Créez une deuxième équipe. Utilisez votre première équipe pour le dev et l’autre équipe(s) pour la prod. Informez le support du nom de votre équipe de dev pour l’exclure de la facturation.

Clé API

Dans la section Clé API vous verrez les détails de vos clés API. La clé elle-même ne vous sera affichée qu’au moment de sa création.

La section Quickstart contient des exemples à copier-coller pour tester votre clé.

Capture écran section clé API

Webhooks & Journaux

Ajoutez des webhooks (vos écouteurs pour les événements Legalesign), et consultez vos journaux.

Capture écran section webhooks

2. Une requête GET réussie

L’URL racine est toujours : https://eu-api.legalesign.com/

Commencez par une requête GET pour confirmer que vos identifiants fonctionnent. Remplacez les valeurs username et secret dans le code ci-dessous.

Curl est utilisé dans les exemples, et vous pouvez basculer entre cURL, Node.js, Python, C#, et Go avec les onglets ci-dessous.

curl -H "Authorization: ApiKey username:secret" -H "Content-Type: application/json" -X GET https://eu-api.legalesign.com/api/v1/group/

Documentation API : Référence API GET group.

Quand vous exécutez la requête ci-dessus, vous verrez vos groupes retournés en JSON. Succès. 👏

Les données de réponse contiennent l’« uri ressource » pour votre groupe et ressemblent à /api/v1/group/:groupId/. Notez-le, vous en aurez besoin pour la plupart des appels API.

astuce

Une uri ressource sera toujours formatée de la même façon. Pour un PDF ce sera '/api/v1/templatepdf/:pdfId/', pour un document envoyé ce sera '/api/v1/document/:documentId/'. Remarquez que toutes les URIs se terminent par une barre oblique. C’est également vrai pour les URLs de vos appels API, terminez-les toujours par une barre oblique.

Si la requête GET échoue, vérifiez que :

  • votre ApiKey est correctement formatée (commence par 'ApiKey'),
  • vous avez un en-tête Content-Type pour application/json, et
  • votre URL se termine par une barre oblique.

Voir aussi dépannage.

3. Téléverser un document via l’application web

Pour commencer, nous allons téléverser un document via l’application web et l’envoyer via l’API. Nous verrons comment téléverser un document via l’API plus tard.

Allez dans l’application web et téléversez votre document. Ajoutez un seul rôle de signataire et glissez un champ signature. La page de l’éditeur indiquera si le document est « valide » (un exemple d’« invalide » serait d’ajouter un rôle signataire sans champ signature associé).

Dans l’éditeur de formulaire, copiez l’ID alphanumérique long de l’URL, décodez-le en base64 et jetez les 3 premières lettres (qui devraient être 'tpl'). Le reste est un UUID qui est votre ID.

Dans le langage REST API, l’uri ressource pour ce document est /api/v1/templatepdf/UUID/.

En savoir plus sur les IDs web et API.

Notre nomenclature est qu’un document téléversé est un « template » et lorsque vous en envoyez un vous créez un « document ».

astuce

Si vous voulez archiver un template lors de l’envoi, réglez 'archive_upon_send' en attribut dans la requête de téléversement. Si vous voulez que le template n’apparaisse jamais et soit supprimé après envoi, donnez-lui le titre '[deleted]' - nos systèmes de nettoyage le détecteront et le supprimeront après un jour ou deux. Vous pouvez aussi définir des temps de rétention courts au niveau du groupe - en savoir plus.

4. Envoyer un document pour signature

Nous allons maintenant envoyer cela via l’API. N’oubliez pas d’utiliser un email approuvé dans votre bac à sable. Utilisez les onglets ci-dessous pour saisir la requête dans la langue de votre choix.

curl -H "Authorization: ApiKey [username]:[secret]" -H "Content-Type: application/json" -X POST --data '{ "group": "/api/v1/group/[:groupId]/", "name": "Name of doc", "templatepdf": "/api/v1/templatepdf/UUID/", "signers": [{"firstname": "Joe", "lastname": "Bloggs", "email": "[your@email.com]", "order": 0 }], "do_email": true }' https://eu-api.legalesign.com/api/v1/document/

Modifiez toutes les crochets []. Référence API pour envoyer un document.

astuce

Lorsque vous consultez la documentation de référence pour l’envoi d’un document, parcourez bien tous les attributs possibles. Vous verrez beaucoup de choses qui aideront à l’intégration pratique – des tags pour vos propres références et IDs (qui vous sont renvoyés dans les webhooks), une redirection pour les signataires, la possibilité de définir un texte personnalisé dans le PDF, et plus encore.

Un appel réussi retournera le code d’état 201.

Obtenir le nouvel ID du document envoyé

L’élément important de la réponse est le header location. Cela contient le nouvel ID du document.

astuce

Utilisez les attributs ‘tag’ du document et ajoutez vos propres références pour faciliter la liaison avec votre base de données.

Le header location ressemblera à /api/v1/status/:documentId/.

L’URI 'status' retourne un ensemble court (et rapide à requêter) d’attributs de document.

Pour demander tout d’un document, utilisez /api/v1/document/:documentId/.

info

Si une requête échoue, le CORPS de la réponse contient généralement des informations d’erreur. Si vous n’obtenez pas un statut de succès, vérifiez le CORPS pour un texte explicatif. Voir aussi dépannage.

En savoir plus sur l’appel API envoyer un document.

5. Télécharger le document signé

Avec l’ID du document envoyé que vous avez reçu plus haut, faites une requête de téléchargement PDF dans la langue de votre choix :

curl -H "Authorization: ApiKey [username]:[secret]" -o download.pdf -X GET https://eu-api.legalesign.com/api/v1/pdf/:documentId/

Référence API téléchargement PDF.

Le binaire PDF est dans le corps de la réponse. La commande curl '-o' place le CORPS de la réponse directement dans un fichier.

Beaucoup de bibliothèques REST ou HTTP traitent les objets réponse HTTP comme des fichiers, il suffit alors d’enregistrer l’objet de réponse comme un fichier normal.

astuce

Utilisez les webhooks pour être notifié d’un événement de signature puis téléchargez le document. Voir webhooks.

6. Téléverser un PDF

Cliquez ici pour télécharger un PDF d’exemple balisé en texte, plus d'informations sur les champs de formulaire PDF à suivre.

Pour cet appel, convertissez votre PDF en une chaîne encodée en base64. Ce n’est pas correctement fait dans le générateur de code de la documentation. Copiez plutôt ce pseudocode et votre IA préférée le convertira dans la langue de votre choix :

$data = (
'group': '/api/v1/group/:groupId/',
'title': 'title of pdf',
'pdf_file': base64encode(open('/path/to/file','rb')),
'process_tags': true
)
$headers = (
'Authorization': 'ApiKey username:secret',
'Content-Type': 'application/json'
)
response = httplibrary.post('https://eu-api.legalesign.com/api/v1/templatepdf/', jsonEncode($data), $headers)
assert response.status == 201

pdfId = response.headers['location']

Référence API upload PDF.

Comme d’habitude, une réponse POST réussie retournera le statut ‘201’ et le nouvel ID sera dans le header ‘location’ de la réponse.

assert response.status == 201
pdfId = response.headers['location']

Votre uri ressource pdf ressemblera à /api/v1/templatepdf/:pdfId/.

Envoyer le nouveau PDF

Retournez au code que vous avez utilisé pour envoyer votre premier document et remplacez la valeur templatepdf.

Refaites la requête et voilà, votre PDF est envoyé pour signature.

Avant de commencer à coder, continuez la lecture pour en savoir plus sur les champs PDF.

Qu’en est-il des champs PDF ?

Comment Legalesign sait-il où la personne doit signer sur le PDF, ou quelles sections modifier à l’envoi ? La réponse est que notre PDF a été pré-préparé avec des tags : nous mettons un tag texte Legalesign dans le PDF et réglons 'process_tags' à true dans la requête de chargement PDF.

Download a sample text-tagged PDF.

Les tags texte sont du texte spécialement formaté à placer dans un PDF. Legalesign analysera le texte dans votre fichier, remplaçant les tags par des champs de signature et de formulaire. Pour un seul signataire il suffit d’ajouter : <<t=signature>>. Legalesign l’identifie et place la signature à cet endroit. En savoir plus sur les tags texte.

Les tags texte demandent une courbe d’apprentissage et des essais/erreurs. D’autres méthodes sont exposées ci-dessous, mais elles donnent toute la capacité du système de formulaires Legalesign. Utilisez l’application web pour tester les tags. Contactez le support pour de l’aide et des exemples.

Voici 4 autres façons de configurer les champs :

1. Version la plus simple/rapide. Configurez votre PDF via l’application web Legalesign.

Après avoir téléversé un PDF vous accéderez à l’interface d’édition où vous pouvez glisser-déposer les champs de formulaire.

Glissez-déposez une signature, puis notez l’ID encodé dans l’adresse web. Cela ressemblera à quelque chose comme ‘dHBsMTRlZTQ0ZWUtZGE0Ni0xMWVmLTllZmUtMDI5ZGQ0ODkzZGRk’.

Décodez cet ID base64 et vous verrez un UUID préfixé par ‘tpl’. La partie UUID (supprimez ‘tpl’) est votre pdfID. En savoir plus sur les IDs Legalesign.

Votre uri ressource API PDF sera - /api/v1/templatepdf/:pdfId/.

Mettez cela dans l’attribut ‘templatepdf’ de l’appel envoyer un document.

info

Si vous prévoyez d’envoyer ce PDF plusieurs fois, assurez-vous que 'Archivage automatique' est désactivé. Voir comment

2. Utilisez les coordonnées x/y pour les champs.

La façon la plus simple de commencer avec les coordonnées x/y est de configurer un PDF dans l’application web puis de faire une requête API pour récupérer ces champs (GET PDF Fields - /api/v1/templatepdf/:pdfId/fields/).

L’objet JSON que vous récupérez est exactement le même schéma JSON que celui nécessaire pour créer des champs.

Utilisez-le comme modèle. Modifiez les valeurs et POSTez-le de nouveau au même endpoint (en ajustant l’ID PDF en conséquence). Point de terminaison Créer un champ PDF.

3. Intégrez notre page d’édition PDF. NOUVEAU !

Utilisez notre composant éditeur pour intégrer notre éditeur PDF directement dans votre application. En savoir plus sur le composant éditeur de document.

4. Champs de formulaire PDF NOUVEAU !

Si votre PDF contient des Champs de formulaire PDF normaux, Legalesign peut les importer automatiquement.

Bon codage !

Dans ce tutoriel, vous avez acquis des identifiants API, interrogé avec succès vos groupes, envoyé un document à signer utilisant HTML et PDF, et téléchargé un document signé.

Bon codage ! Nous sommes là pour vous aider, contactez le support pour toute assistance.

astuce

Bravo, vous êtes arrivé à la fin - merci d’avoir lu ceci. Notre dernière demande, et astuce, basée sur des années d’expérience de développeurs intégrant cette API, est que vous preniez un moment pour parcourir tous les attributs du point de terminaison créer un document (et cliquez pour voir ce que contiennent ‘signers’, ‘pdftext’ et ‘signertext’) - c’est l’appel le plus important de votre intégration. Créer un document de signature.

Étapes suivantes :