Tutoriel de démarrage rapide
Vous utilisez Cursor, Claude ou un autre outil d'IA pour coder ? Connectez-le à la documentation Legalesign pour une aide contextuelle pendant que vous suivez ce tutoriel.
Dans ce tutoriel, vous compléterez les appels API clés 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 de nombreuses années. Vous pouvez l'utiliser pour un document simple avec un seul signataire, ou envoyer des documents pour témoignage ou approbation, optimisé pour les lots, avec des formulaires et plus encore. Vous pouvez intégrer pour un seul usage ou l'incorporer dans votre logiciel pour vos clients - voir intégrations.
L'API REST réalise la plupart des fonctions et est le moyen le plus simple pour débuter. Si vous avez besoin de plus, consultez l'interface GraphQL. Legalesign est d'abord une API avec GraphQL. Vous pouvez utiliser l'une ou l'autre selon votre préférence.
Nous suivrons ces étapes :
- Créer un compte + clé API (voir Obtenir une 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 API.
L'API REST de Legalesign est facile à utiliser. La référence technique inclut un éditeur de code. Vous pouvez effectuer des requêtes directement depuis la référence technique avec votre clé API, sinon copiez simplement-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 aux développeurs de travailler directement avec l'API plutôt qu'avec les SDK. Pour vous 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 utilisant le spec OpenAPI. Pourquoi ? L'API source offre plus 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—vous irez plus vite aussi.
1. Créer un compte
Allez sur inscription Legalesign et suivez le processus pour créer un compte.
Il vous sera demandé de créer une équipe. Les équipes sont les blocs de construction 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' signifie la même chose. Dans l'application web, nous parlons 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 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 à 100 appels par heure. Il n'y a pas de restrictions sur les adresses e-mail des destinataires.
Quand votre intégration est prête : passez en mode production.
Créez une seconde équipe. Utilisez votre première équipe pour le dev et d'autres équipes pour la prod. Informez le support du nom de votre équipe 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’à la création.
Le Portail Développeur contient des exemples de test à copier-coller pour tester votre clé.
Webhooks & Logs
Ajoutez des webhooks (vos écouteurs pour les événements Legalesign) et consultez vos logs.
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é depuis le Portail Développeur.
Curl est utilisé dans les exemples, 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: Bearer your_api_key" -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': 'Bearer your_api_key',
'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": "Bearer your_api_key",
"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", "Bearer your_api_key");
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", "Bearer your_api_key")
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 ceci, vous en aurez besoin pour la plupart des appels API.
Une URI ressource aura 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 URI finissent par une barre oblique. C’est aussi 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 en-tête Authorization est bien formaté (commence par
Bearer), - vous avez un en-tête Content-Type à application/json, et
- votre url se termine par une barre oblique.
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 via l’API. Nous verrons comment télécharger un document via l’API plus tard.
Allez dans l’application web et téléversez votre document. Ajoutez un rôle de signataire unique et déposez un champ de signature. La page d’édition indiquera si le document est ‘valide’ (un exemple d’‘invalide’ pourrait être si vous ajoutez un rôle signataire sans champ de signature associé).
Sur l’éditeur de formulaire, copiez la longue ID alphanumérique depuis l’URL, décodez-la en base64 et supprimez les 3 premières lettres (qui devraient être ‘tpl’). Le reste est un UUID qui est votre ID. En savoir plus sur les IDs web et API.
L’ID REST API pour ce document est /api/v1/templatepdf/UUID/.
Notre nomenclature veut qu’un document téléversé soit un ‘template’ et qu’un document envoyé soit un ‘document’.
Si vous souhaitez archiver un template lors de l’envoi du document, définissez ‘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 s’en chargeront sous 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 allons l’envoyer via l’API. 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: 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/
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': 'Bearer your_api_key',
'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": "Bearer your_api_key",
"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", "Bearer your_api_key");
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", "Bearer your_api_key")
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 toutes les parties entre crochets. Référence API pour envoyer un document.
Quand vous consultez la documentation référence pour envoyer un document, regardez bien tous les attributs possibles. Vous verrez beaucoup qui vous aideront pour les aspects pratiques d’une intégration - tags pour vos propres références et IDs (qui reviennent dans les webhooks), une redirection pour les signataires, définir un texte personnalisé dans le pdf, et plus encore.
Un appel réussi renverra un code de 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.
Utilisez les attributs ‘tag’ du document et ajoutez vos propres références pour faciliter la liaison avec votre propre base de données.
L’en-tête Location ressemblera à /api/v1/status/:documentId/.
L’URI ‘status’ retourne un petit (et rapide à interroger) ensemble d’attributs du document.
Pour récupérer tout d’un document, utilisez /api/v1/document/:documentId/.
Si une requête est infructueuse, le CORPS de la réponse contient généralement des informations d’erreur. Si vous n’avez pas un statut succès, regardez 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é reçu ci-dessus, effectuez une requête de téléchargement PDF dans le langage de votre choix :
- cURL
- Node.js
- Python
- C#
- Go
curl -H "Authorization: Bearer your_api_key" -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': 'Bearer your_api_key',
},
});
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": "Bearer your_api_key"}
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", "Bearer your_api_key");
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", "Bearer your_api_key")
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' met directement le CORPS de la réponse dans un fichier.
Beaucoup de bibliothèques REST ou HTTP traitent les objets réponse HTTP comme des fichiers, dans ce cas enregistrez 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 document via API
Cliquez ici pour télécharger un PDF exemple avec tags 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. Ceci n’est pas bien fait dans le générateur de code de la documentation. Copiez ce pseudocode et l’IA 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échargement PDF.
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.
Votre URI ressource pdf ressemblera à /api/v1/templatepdf/:pdfId/.
Autres formats de fichiers
Word, HTML, texte brut, XLSX, et fichiers image sont tous supportés. Téléversez-les en utilisant l'uploadeur de fichiers GraphQL, qui détecte automatiquement le format et convertit en PDF. Récupérez l’ID et envoyez via l’API REST comme d’habitude. Voir aussi comprendre les IDs REST et GraphQL. Les text tags seront pris en compte comme d’habitude.
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 était pré-préparé avec des tags : nous insérons un tag texte Legalesign dans le PDF et définissons 'process_tags' à true dans la requête de téléchargement PDF.
Download a sample text-tagged PDF.
Les text tags sont du texte spécialement formaté à mettre dans un PDF. Legalesign analysera le texte de votre fichier, remplaçant les tags par des champs de signature et de formulaire. Pour un signataire, il suffit d’ajouter : <<t=signature>>. Legalesign l’identifiera et placera la signature à cet endroit. En savoir plus sur les text tags.
D’autres méthodes pour localiser vos champs sont décrites ci-dessous, mais avec les text tags vous avez toute la puissance du système de formulaires Legalesign. Utilisez l’application web pour tester vos tags. Contactez le support pour assistance et exemples.
Voici 4 autres façons de configurer les champs :
1. Version la plus facile/rapide. Configurez votre PDF à l’aide de 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 les 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 cette ID en base64 et vous verrez que c’est un UUID préfixé par 'tpl'. La partie UUID (retirez '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 envoyer un document.
Si vous prévoyez d’envoyer ce PDF plus d’une fois, assurez-vous que ‘Archivage Auto’ est désactivé. Voir comment faire
2. Utilisez les coordonnées x/y pour les champs.
Le moyen le 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 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 également.
Utilisez-le comme modèle. Modifiez les valeurs et POSTez-le au même endpoint (en adaptant l’ID PDF). 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 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 en PDF, et téléchargé un document signé.
Nous sommes là pour vous aider, contactez le support pour toute assistance.
Passez en revue les options d’envoi qui s’offrent à vous. Prenez un moment pour lire tous les attributs du endpoint création document, notamment les attributs 'signers', 'pdftext' et 'signertext'. Créer un document à signer.