Aller au contenu principal

Tutoriel de démarrage rapide

astuce

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

Dans ce tutoriel, vous réaliserez les appels API clés dont la plupart des développeurs ont besoin pour 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 chez nos clients depuis de nombreuses années. Vous pouvez l’utiliser pour un simple document avec un seul signataire, ou envoyer des documents pour témoins ou approbations, optimisée pour les lots, avec des formulaires et plus encore. Vous pouvez intégrer pour un seul usage ou l’intégrer dans votre logiciel pour vos clients - voir les intégrations.

L’API REST réalise la plupart des fonctions et est la façon la plus simple de commencer. Si vous avez besoin de plus, consultez l’interface GraphQL. Legalesign est prioritairement API avec GraphQL. Vous pouvez utiliser l’un ou l’autre selon vos préférences.

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 récupérer votre ID d’équipe.
  3. Téléverser un document via l’application web.
  4. L’envoyer pour signature via l’API.
  5. Le télécharger après signature.
  6. Téléverser un document via l’API.

L’API REST de 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, ou simplement copier-coller 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 à copier-coller dans la spécification technique, et votre AI peut rapidement produire des exemples en utilisant la spec OpenAPI. Pourquoi ? L’API source offre plus de fonctionnalités que les SDK, vous devrez de toute façon connaître les endpoints que vous utilisez, vous évitez la surcharge d’abstraction et les dépendances, et—d’après notre expérience—you allez plus vite.

1. Créer un compte

Rendez-vous sur inscription Legalesign et suivez le processus pour créer un compte.

Vous serez invité à créer une équipe. Les équipes sont les éléments de base de Legalesign. Tout le traitement des documents s’effectue au sein d’une équipe. Vous devez référencer votre équipe dans la plupart des appels API.

info

Un 'team' ou un 'group' désignent la même chose. Dans l’application web, nous parlons d’'équipes', mais dans le schéma API c’est un group.

Paramètres API

Rendez-vous sur le Tableau de bord API. Générez vos identifiants API dans la section Clé API.

Prenez un moment pour découvrir le Portail Développeur.

Sandbox

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

Le mode sandbox applique une limitation de 100 appels par heure. Il n’y a aucune restriction sur les adresses email des destinataires.

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

astuce

Créez une deuxième équipe. Utilisez votre première équipe pour le développement et les autres pour la production. Informez le support du nom de votre équipe de dev pour qu’elle soit exclue 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 montrée qu’au moment de sa création.

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

Capture d’écran de la section Clé API

Webhooks & Journaux

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

Capture d’écran de la 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 your_api_key par votre clé du Portail Développeur.

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

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

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

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

Les données de la réponse contiennent l’'URI ressource' de votre groupe qui ressemble à /api/v1/group/:groupId/. Notez-le, vous en aurez besoin pour la plupart des appels API.

astuce

Une URI ressource aura toujours ce format. Pour un PDF, ce serait '/api/v1/templatepdf/:pdfId/', pour un document envoyé ce sera '/api/v1/document/:documentId/'. Remarquez que toutes les URIs se terminent par un slash. C’est aussi vrai pour les URLs de vos appels API, terminez-les toujours par un slash.

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

  • votre en-tête Authorization est correctement formaté (commence par Bearer ),
  • vous avez un en-tête Content-Type pour application/json, et
  • votre URL se termine bien par un slash.

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 ensuite via l’API. Nous verrons comment téléverser un document via l’API plus tard.

Allez sur l’application web et téléversez votre document. Ajoutez un rôle de signataire unique et placez un champ de 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 de signature associé).

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

En langage REST API, l’URI ressource de 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 'modèle' et quand vous en envoyez un vous créez un 'document'.

astuce

Si vous voulez archiver un modèle quand le document est envoyé, définissez 'archive_upon_send' comme attribut dans la requête de téléversement. Si vous ne voulez jamais que le modèle apparaisse et souhaitez le supprimer après l’envoi, donnez-lui le titre '[deleted]' - nos systèmes de nettoyage le détecteront et le supprimeront au bout d’un jour ou deux. Vous pouvez aussi définir des durées de rétention courtes au niveau groupe - en savoir plus.

4. Envoyer un document pour signature

Maintenant, nous l’enverrons via l’API. Utilisez les onglets ci-dessous pour récupérer la requête dans votre langage préféré.

curl -H "Authorization: Bearer your_api_key" -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/

Mettez à jour tous les crochets []. Référence API pour envoyer un document.

astuce

Quand vous consultez la documentation de référence pour l’envoi d’un document, regardez bien toutes les options possibles. Vous verrez beaucoup d’attributs utiles pour les aspects pratiques d’une intégration — des tags pour vos propres références et IDs (qui vous reviennent dans les webhooks), une redirection pour les signataires, définir du texte personnalisé dans le pdf, et plus encore.

Un appel réussi renverra le code statut 201.

Obtenir le nouvel ID du document envoyé

La partie importante de la réponse est l’en-tête location. Il contient votre nouvel ID 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.

L’en-tête location ressemblera à /api/v1/status/:documentId/.

L’URI 'status' retourne un ensemble réduit (et rapide à interroger) d’attributs du document.

Pour demander tout sur 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 ne recevez 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 Send Document.

5. Télécharger le document signé

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

curl -H "Authorization: Bearer your_api_key" -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 de réponse HTTP comme des fichiers, dans ce cas il suffit d’enregistrer votre objet réponse comme un fichier normal.

astuce

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

6. Téléverser un PDF

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

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

$data = (
'group': '/api/v1/group/:groupId/',
'title': 'title of pdf',
'pdf_file': base64encode(open('/path/to/file','rb')),
'process_tags': true
)
$headers = (
'Authorization': 'Bearer your_api_key',
'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 téléversement PDF.

Comme d’habitude, une réponse POST réussie renverra le statut '201' et le nouvel ID sera dans l’en-tête 'location' de la réponse.

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

L’URI ressource de votre pdf ressemblera à /api/v1/templatepdf/:pdfId/.

Envoyer le nouveau PDF

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

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

Avant de commencer à coder, cependant, lisez la suite 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 les sections à modifier à l’envoi ? La réponse est que notre PDF a été préparé à l’avance avec des tags : nous plaçons un tag texte Legalesign dans le PDF et définissons 'process_tags' à true dans la requête de téléversement PDF.

Téléchargez un PDF d’exemple taggé en texte.

Les tags texte sont du texte spécialement formaté à insérer dans un PDF. Legalesign analysera le texte de 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 le reconnaîtra et placera la signature à cet endroit. En savoir plus sur les tags texte.

Les tags texte ont une courbe d’apprentissage et nécessitent essais et erreurs. D’autres méthodes sont exposées ci-dessous, mais vous bénéficiez de la pleine capacité du système de formulaires Legalesign avec cela. 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 facile/rapide. Configurez votre PDF en utilisant l’application web Legalesign.

Après avoir téléversé un PDF, vous accéderez à l’interface de l’éditeur où vous pouvez glisser-déposer des 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 cette ID en base64 et vous verrez un UUID préfixé par 'tpl'. La partie UUID (enlevez 'tpl') est votre pdfID. En savoir plus sur les IDs Legalesign.

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

Mettez ceci dans l’attribut 'templatepdf' de l’appel send document.

info

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

2. Utilisez des 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 interroger l’API pour ces champs (GET PDF Fields - /api/v1/templatepdf/:pdfId/fields/).

L’objet JSON que vous recevrez est le même schéma JSON exact nécessaire pour créer des champs.

Utilisez-le comme modèle. Modifiez les valeurs et POSTez-les à la même endpoint (en ajustant l’ID PDF le cas échéant). Endpoint création 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 documents.

4. Champs de formulaire PDF NOUVEAU !

Si votre PDF contient des champs de formulaire PDF classiques, 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 pour signature en 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és jusqu’au bout — merci de votre lecture. Notre dernière requête et conseil, basé sur des années d’expérience des développeurs intégrant cette API, est que vous preniez un moment pour lire tous les attributs du point de terminaison création de 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 :