Tutoriel de démarrage rapide
Utilisez-vous Cursor, Claude ou un autre outil d'IA pour coder ? Connectez-le aux docs Legalesign pour une aide contextuelle pendant que vous suivez ce tutoriel.
Dans ce tutoriel, vous effectuerez les principales appels API dont la plupart des développeurs ont besoin pour une intégration eSignature : télécharger 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 plusieurs années. Vous pouvez l’utiliser pour un document simple à un seul signataire, ou envoyer des documents pour validation ou approbations, optimisé 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 manière la plus simple de commencer. Si vous avez besoin de plus, consultez l’interface GraphQL. Legalesign est d’abord API avec GraphQL. Vous pouvez utiliser l’un ou l’autre, selon votre préférence.
Nous suivrons ces étapes :
- Créer un compte + clé API (voir Obtenir la vérification pour l’accès API).
- Confirmer que les identifiants fonctionnent et obtenir votre ID d’équipe.
- Télécharger un document via l’application web.
- L’envoyer pour signature via l’API.
- Le télécharger après signature.
- Télécharger 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, sinon il suffit de copier-coller dans votre code.
Figure 1 : L’éditeur de code de l’API REST.
Bibliothèques clientes
Ou pour l’interface GraphQL Node.js
Nous recommandons que les développeurs travaillent directement avec l’API plutôt qu’avec les SDKs. Pour aider, il y a un générateur de code à copier-coller dans la spécification technique, et votre IA peut rapidement produire des exemples en utilisant le spécification OpenAPI. Pourquoi ? L’API source offre plus de fonctionnalités que les SDKs, vous aurez de toute façon besoin de connaître les endpoints que vous utilisez, vous évitez les surcouches et dépendances, et — selon notre expérience — vous allez plus vite.
1. Créer un compte
Allez sur legalesign sign up et suivez le processus pour créer un compte.
Vous serez invité à créer une équipe. Les équipes sont les blocs de base de Legalesign. Tout le traitement des documents se fait dans une équipe. Vous devez référencer votre équipe dans la plupart des appels API.
Une ‘équipe’ ou un ‘groupe’ est la même chose. Dans l’application web on parle d’‘équipes’, mais dans le schéma API c’est un groupe.
Paramètres API
Allez 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.
Sandbox
Dans la section Environnement, une alerte indique si vous êtes en mode sandbox ou production.
Le sandbox limite où vous pouvez envoyer vos documents. Vous verrez un formulaire pour ajouter jusqu’à 5 emails approuvés — ajoutez-en quelques-uns dès maintenant.
Quand votre intégration est prête : passez en mode production.
Créez une deuxième équipe. Utilisez votre première équipe pour le développement et d’autres équipes pour la production. 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 montrée qu’au moment de sa création.
La section Démarrage rapide contient des exemples à copier-coller pour tester votre clé.
Webhooks & Journaux
Ajoutez des webhooks (vos écouteurs pour les événements Legalesign), et consultez vos journaux.
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 changer entre cURL, Node.js, Python, C# et Go en utilisant les onglets ci-dessous.
- cURL
- Node.js
- Python
- C#
- Go
curl -H "Authorization: ApiKey username:secret" -H "Content-Type: application/json" -X GET https://eu-api.legalesign.com/api/v1/group/
import fetch from 'node-fetch';
async function getGroups() {
const response = await fetch('https://eu-api.legalesign.com/api/v1/group/', {
method: 'GET',
headers: {
'Authorization': 'ApiKey username:secret',
'Content-Type': 'application/json',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const data = await response.json();
console.log(data);
}
getGroups().catch((error) => {
console.error(error);
process.exit(1);
});
import requests
headers = {
"Authorization": "ApiKey username:secret",
"Content-Type": "application/json",
}
response = requests.get(
"https://eu-api.legalesign.com/api/v1/group/",
headers=headers,
timeout=30,
)
response.raise_for_status()
print(response.json())
using System;
using System.Net.Http;
using System.Threading.Tasks;
public class Program
{
public static async Task Main()
{
using var client = new HttpClient();
using var request = new HttpRequestMessage(
HttpMethod.Get,
"https://eu-api.legalesign.com/api/v1/group/"
);
request.Headers.TryAddWithoutValidation("Authorization", "ApiKey username:secret");
request.Headers.TryAddWithoutValidation("Content-Type", "application/json");
using var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
var body = await response.Content.ReadAsStringAsync();
Console.WriteLine(body);
}
}
package main
import (
"fmt"
"io"
"log"
"net/http"
)
func main() {
req, err := http.NewRequest(http.MethodGet, "https://eu-api.legalesign.com/api/v1/group/", nil)
if err != nil {
log.Fatal(err)
}
req.Header.Set("Authorization", "ApiKey username:secret")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
if resp.StatusCode >= 400 {
log.Fatalf("request failed: %s", resp.Status)
}
body, err := io.ReadAll(resp.Body)
if err != nil {
log.Fatal(err)
}
fmt.Println(string(body))
}
Documentation API : Référence GET group API.
Quand vous exécutez la requête ci-dessus, vous verrez vos groupes retournés au format JSON. Succès. 👏
Les données de la réponse contiennent l’‘uri de ressource’ pour votre groupe et ressemblent à /api/v1/group/:groupId/. Notez-le, vous en aurez besoin pour la plupart des appels API.
Une uri de ressource a toujours le même format. Pour un PDF ce serait ‘/api/v1/templatepdf/:pdfId/’, pour un document envoyé ce sera ‘/api/v1/document/:documentId/’. Notez que toutes les URIs se terminent par un slash. Cela vaut aussi pour les URLs de vos appels API, terminez-les toujours par un slash.
Si la requête GET échoue, vérifiez que :
- votre ApiKey est correctement formatée (commence par ‘ApiKey’),
- vous avez un header Content-Type pour application/json, et
- votre url se termine par un slash.
Voir aussi dépannage.
3. Télécharger un document via l’application web
Pour commencer, nous allons télécharger un document via l’application web et l’envoyer ensuite via l’API. Nous verrons plus tard comment télécharger un document via l’API.
Allez dans l’application web et téléchargez votre document. Ajoutez un rôle signataire unique et glissez un champ de signature. La page de l’éditeur indiquera si le document est ‘valide’ (un exemple d’‘invalide’ serait si vous ajoutez un rôle signataire sans champ de signature associé).
Dans l’éditeur de formulaire, copiez l’ID alphanumérique long depuis l’URL, décodez-le en base64 et supprimez les 3 premières lettres (qui devraient être ‘tpl’). Le reste est un UUID qui est votre ID.
En langage API REST, 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échargé est un ‘template’ et lorsqu’on envoie un, on crée un ‘document’.
Si vous voulez archiver un template au moment où le document est envoyé, ajoutez 'archive_upon_send' en attribut dans la requête de téléchargement. 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 durées de rétention courtes au niveau du groupe - en savoir plus.
4. Envoyer un document pour signature
Maintenant nous allons envoyer ceci via l’API. N’oubliez pas d’utiliser un email autorisé dans votre sandbox. Utilisez les onglets ci-dessous pour récupérer la requête dans votre langage préféré.
- cURL
- Node.js
- Python
- C#
- Go
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/
import fetch from 'node-fetch';
const payload = {
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,
};
async function sendDocument() {
const response = await fetch('https://eu-api.legalesign.com/api/v1/document/', {
method: 'POST',
headers: {
'Authorization': 'ApiKey [username]:[secret]',
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
if (response.status !== 201) {
const errorBody = await response.text();
throw new Error(`Request failed with status ${response.status}: ${errorBody}`);
}
console.log('Document sent successfully');
const location = response.headers.get('location');
if (location) {
console.log(`Location: ${location}`);
}
}
sendDocument().catch((error) => {
console.error(error);
process.exit(1);
});
import requests
payload = {
"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,
}
headers = {
"Authorization": "ApiKey [username]:[secret]",
"Content-Type": "application/json",
}
response = requests.post(
"https://eu-api.legalesign.com/api/v1/document/",
json=payload,
headers=headers,
timeout=30,
)
response.raise_for_status()
print("Document sent successfully")
print("Location:", response.headers.get("Location"))
using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;
public class Program
{
public static async Task Main()
{
var payload = new
{
group = "/api/v1/group/[:groupId]/",
name = "Name of doc",
templatepdf = "/api/v1/templatepdf/UUID/",
signers = new[]
{
new
{
firstname = "Joe",
lastname = "Bloggs",
email = "[your@email.com]",
order = 0,
},
},
do_email = true,
};
using var client = new HttpClient();
using var request = new HttpRequestMessage(
HttpMethod.Post,
"https://eu-api.legalesign.com/api/v1/document/"
);
request.Headers.TryAddWithoutValidation("Authorization", "ApiKey [username]:[secret]");
var json = JsonSerializer.Serialize(payload);
request.Content = new StringContent(json, Encoding.UTF8, "application/json");
using var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
Console.WriteLine("Document sent successfully");
if (response.Headers.Location is not null)
{
Console.WriteLine($"Location: {response.Headers.Location}");
}
}
}
package main
import (
"bytes"
"encoding/json"
"fmt"
"log"
"net/http"
)
func main() {
payload := map[string]any{
"group": "/api/v1/group/[:groupId]/",
"name": "Name of doc",
"templatepdf": "/api/v1/templatepdf/UUID/",
"signers": []map[string]any{
{
"firstname": "Joe",
"lastname": "Bloggs",
"email": "[your@email.com]",
"order": 0,
},
},
"do_email": true,
}
body, err := json.Marshal(payload)
if err != nil {
log.Fatal(err)
}
req, err := http.NewRequest(
http.MethodPost,
"https://eu-api.legalesign.com/api/v1/document/",
bytes.NewReader(body),
)
if err != nil {
log.Fatal(err)
}
req.Header.Set("Authorization", "ApiKey [username]:[secret]")
req.Header.Set("Content-Type", "application/json")
resp, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
if resp.StatusCode != http.StatusCreated {
log.Fatalf("unexpected status: %s", resp.Status)
}
fmt.Println("Document sent successfully")
fmt.Println("Location:", resp.Header.Get("Location"))
}
Mettez à jour tous les crochets. Référence API pour envoyer un document.
Quand vous visitez la documentation de référence pour l’envoi d’un document, parcourez bien tous les attributs possibles. Vous en verrez beaucoup qui aideront dans les aspects pratiques d’une intégration — tags pour vos propres références et IDs (qui vous reviennent via les webhooks), redirection pour les signataires, texte personnalisé dans le pdf, et plus.
Un appel réussi renverra un code statut 201. ✨
Obtenir le nouvel ID de document envoyé
La partie importante de la réponse est le header location. Il contient votre nouvel ID document.
Utilisez les attributs ‘tag’ du document et ajoutez vos propres références pour faciliter la liaison avec votre propre base de données.
Le header location ressemblera à /api/v1/status/:documentId/.
L’URI ‘status’ renvoie un ensemble court (et rapide à requêter) d’attributs du document.
Pour demander tout depuis un document utilisez /api/v1/document/:documentId/.
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 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 le langage de votre choix :
- cURL
- Node.js
- Python
- C#
- Go
curl -H "Authorization: ApiKey [username]:[secret]" -o download.pdf -X GET https://eu-api.legalesign.com/api/v1/pdf/:documentId/
import { writeFile } from 'node:fs/promises';
import fetch from 'node-fetch';
async function downloadPdf() {
const response = await fetch('https://eu-api.legalesign.com/api/v1/pdf/:documentId/', {
method: 'GET',
headers: {
'Authorization': 'ApiKey [username]:[secret]',
},
});
if (!response.ok) {
throw new Error(`Request failed with status ${response.status}`);
}
const buffer = await response.arrayBuffer();
await writeFile('download.pdf', Buffer.from(buffer));
console.log('Saved download.pdf');
}
downloadPdf().catch((error) => {
console.error(error);
process.exit(1);
});
import requests
headers = {"Authorization": "ApiKey [username]:[secret]"}
response = requests.get(
"https://eu-api.legalesign.com/api/v1/pdf/:documentId/",
headers=headers,
stream=True,
timeout=30,
)
response.raise_for_status()
with open("download.pdf", "wb") as file:
for chunk in response.iter_content(chunk_size=8192):
file.write(chunk)
using System;
using System.IO;
using System.Net.Http;
using System.Threading.Tasks;
public class Program
{
public static async Task Main()
{
using var client = new HttpClient();
using var request = new HttpRequestMessage(
HttpMethod.Get,
"https://eu-api.legalesign.com/api/v1/pdf/:documentId/"
);
request.Headers.TryAddWithoutValidation("Authorization", "ApiKey [username]:[secret]");
using var response = await client.SendAsync(request);
response.EnsureSuccessStatusCode();
var bytes = await response.Content.ReadAsByteArrayAsync();
await File.WriteAllBytesAsync("download.pdf", bytes);
Console.WriteLine("Saved download.pdf");
}
}
package main
import (
"io"
"log"
"net/http"
"os"
)
func main() {
req, err := http.NewRequest(
http.MethodGet,
"https://eu-api.legalesign.com/api/v1/pdf/:documentId/",
nil,
)
if err != nil {
log.Fatal(err)
}
req.Header.Set("Authorization", "ApiKey [username]:[secret]")
resp, err := http.DefaultClient.Do(req)
if err != nil {
log.Fatal(err)
}
defer resp.Body.Close()
if resp.StatusCode >= 400 {
log.Fatalf("request failed: %s", resp.Status)
}
file, err := os.Create("download.pdf")
if err != nil {
log.Fatal(err)
}
defer file.Close()
if _, err := io.Copy(file, resp.Body); err != nil {
log.Fatal(err)
}
log.Println("Saved download.pdf")
}
Référence API de téléchargement PDF.
Le binaire PDF est dans le corps de la réponse. La commande curl ‘-o’ met directement le CORPS de la réponse dans un fichier.
Beaucoup de bibliothèques REST ou HTTP traitent les objets de réponse HTTP comme des fichiers ; dans ce cas, sauvegardez simplement votre objet réponse comme un fichier normal.
Utilisez les webhooks pour être notifié d’un événement de signature puis télécharger le document. Voir webhooks.
6. Télécharger un PDF
Cliquer ici pour télécharger un PDF étiqueté en texte exemple, plus d’informations sur les champs de formulaire PDF à venir.
Pour cet appel, convertissez votre PDF en chaîne base64 encodée. Ce n’est pas bien fait dans le générateur de code de la documentation. Copiez plutôt ce pseudocode et votre IA 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': '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 de téléchargement PDF.
Comme d’habitude, une réponse POST réussie retournera un statut ‘201’ et le nouvel ID sera dans le header ‘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.
Faites la requête à nouveau et voilà, vous avez envoyé votre PDF pour signature.
Avant de commencer à coder, cependant, continuez à lire 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 lors de l’envoi ? La réponse est que notre PDF était pré-préparé avec des tags : nous avons mis une étiquette texte Legalesign dans le PDF et mis 'process_tags' à true dans la requête de téléchargement PDF.
Téléchargez un PDF étiqueté en texte exemple.
Les étiquettes texte sont du texte formaté spécialement à insérer dans un PDF. Legalesign analysera le texte dans votre fichier, remplaçant les tags par des champs de signature et formulaire. Pour un signataire, il suffit d’ajouter : <<t=signature>>. Legalesign l'identifie et place la signature à cet endroit. En savoir plus sur les étiquettes texte.
Les étiquettes texte demandent un apprentissage avec essais-erreurs. D’autres méthodes sont expliquées ci-dessous, mais vous obtenez la pleine capacité du système de formulaires Legalesign avec elles. Utilisez l’appli web pour tester des tags. Contactez le support pour de l’aide et des exemples.
Voici 4 autres méthodes pour configurer les champs :
1. Version la plus facile/rapide. Préparez votre PDF avec l’application web Legalesign.
Après avoir téléchargé 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 codé dans l’adresse web. Cela ressemblera à quelque chose comme ‘dHBsMTRlZTQ0ZWUtZGE0Ni0xMWVmLTllZmUtMDI5ZGQ0ODkzZGRk’.
Décodez cet ID en base64 et vous verrez un UUID préfixé par ‘tpl’. La partie UUID (en supprimant ‘tpl’) est votre pdfID. En savoir plus sur les IDs Legalesign.
Votre uri ressource PDF API sera - /api/v1/templatepdf/:pdfId/.
Mettez cela dans l’attribut ‘templatepdf’ de l’appel d’envoi de document.
Si vous prévoyez d’envoyer ce PDF plus d’une fois, assurez-vous que ‘Auto archive’ est désactivé. Voir comment
2. Utilisez des coordonnées x/y pour les champs.
La manière la plus simple de commencer avec des coordonnées x/y est de préparer un PDF dans l’appli web puis de faire une requête API pour ces champs (GET PDF Fields - /api/v1/templatepdf/:pdfId/fields/).
L’objet JSON que vous obtenez est exactement le même schéma JSON que vous devez utiliser pour créer des champs aussi.
Utilisez-le comme modèle. Modifiez les valeurs et POSTez-le à nouveau sur le même endpoint (en ajustant l’ID du PDF au besoin). Créer un endpoint PDF Field.
3. Intégrez notre page d’édition PDF. NOUVEAU !
Utilisez notre composant éditeur pour intégrer notre éditeur PDF directement dans votre propre 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 normaux, Legalesign peut les importer automatiquement.
Bon codage !
Dans ce tutoriel, vous avez obtenu des identifiants API, interrogé avec succès votre groupe(s), 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.
Bravo, vous êtes arrivé au bout – merci d’avoir lu ceci. Notre demande finale, et conseil, basée sur des années d’expérience de développeurs intégrant cette API, est que vous preniez un moment pour lire tous les attributs de l’endpoint de 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 à signer.