Tutoriel de démarrage rapide
Pour utiliser l’API Legalesign, vous devez nous contacter pour obtenir l'autorisation d'utiliser l'API pour votre compte.
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 :
- 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éverser un document via l’application web.
- Envoyer ce document à signer via l’API.
- Le télécharger après signature.
- 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.

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 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.
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.
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é.

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 basculer entre cURL, Node.js, Python, C#, et Go avec 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 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.
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 ».
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
- 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"))
}
Modifiez toutes les crochets []. Référence API pour envoyer un document.
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.
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/.
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
- 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 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.
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']
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.
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.
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.