Télécharger un fichier comme modèle
Ce guide vous accompagne à travers le processus complet de création d’un modèle et de téléchargement d’un fichier PDF, image ou Word à utiliser comme modèle de document dans Legalesign.
Ce Que Vous Apprendrez
À la fin de ce guide, vous saurez comment :
- Créer un nouveau modèle dans votre groupe Legalesign
- Obtenir l'ID du modèle et l’URL de téléchargement à partir de la réponse de la mutation
- Télécharger votre fichier source dans le modèle
- Vérifier que le téléchargement a réussi
Prérequis
Avant de commencer, assurez-vous d’avoir :
- Un compte Legalesign avec accès API
- Vos identifiants d’authentification (voir notre guide d’authentification)
- Un fichier PDF, image ou Word prêt à être téléchargé (maximum 50 Mo)
- Votre ID de groupe (l’espace de travail où vous souhaitez créer le modèle)
Le Processus Complet
Étape 1 : Créer un Modèle
Commencez par créer un modèle vide dans Legalesign. Cela renvoie à la fois l’ID du modèle et une URL de téléchargement pré-signée pour le téléchargement du PDF. Pour ce faire, vous devrez exécuter une mutation GraphQL, si vous ne l’avez jamais fait auparavant, voir l’Introduction à GraphQL.
Qu’est-ce qu’un Modèle ?
Un modèle est une structure de document réutilisable dans Legalesign. Une fois que vous avez téléchargé un PDF sur un modèle, vous pouvez :
- Ajouter des champs de signature et des champs de formulaire
- L’envoyer à plusieurs destinataires
- Le réutiliser pour différents signataires
Mutation GraphQL
mutation CreateTemplate($input: templateCreateInput!) {
createTemplate(input: $input) {
id
uploadUrl
}
}
Variables d’Entrée
{
"input": {
"groupId": "grpYourGroupAPIId",
"title": "Employment Contract Template"
}
}
Paramètres Expliqués
- groupId : L’ID encodé en base 64 de votre groupe/espace de travail (vous pouvez le récupérer depuis l’URL dans la Console https://console.legalesign.com/)
- title : Un nom descriptif pour votre modèle (vous pouvez le modifier plus tard)
- uploadOptions (optionnel) : Options de traitement appliquées lors du téléchargement du PDF :
pdfFieldsImport: true— importer les champs de formulaire PDF intégrés en tant que champs de modèleprocessTags: true— traiter les balises texte Legalesign dans le document lors du téléchargement
Étape 2 : Extraire l’ID du Modèle et l’URL de Téléchargement
La mutation renvoie un objet templateCreateOutput. Enregistrez le champ id ainsi que la chaîne uploadUrl.
Exemple de réponse :
{
"data": {
"createTemplate": {
"id": "dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx",
"uploadUrl": "https://s3.amazonaws.com/bucket/path?signature=..."
}
}
}
L’ID du modèle est une chaîne encodée en Base64. Enregistrez les deux valeurs de la réponse. L’uploadUrl est de courte durée et doit être utilisée rapidement.
Étape 3 : Téléchargez Votre PDF
Utilisez l’uploadUrl retournée pour télécharger directement votre fichier PDF vers S3. Cela variera
selon votre environnement de développement. Dans notre exemple en javascript, nous avons utilisé fetch mais
vous pouvez utiliser d’autres bibliothèques comme aws-amplify.
Exemples Complets Fonctionnels
- JavaScript
- Python
- C#
import fs from 'fs';
const AUTH_TOKEN = '<token-from-authentication-guide>';
const uploadPdfTemplate = async (groupId, title, pdfFilePath) => {
const graphqlEndpoint = 'https://graphql.uk.legalesign.com/graphql';
// Step 1: Create the template
console.log('Creating template...');
const createResponse = await fetch(graphqlEndpoint, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${AUTH_TOKEN}`
},
body: JSON.stringify({
query: `
mutation CreateTemplate($input: templateCreateInput!) {
createTemplate(input: $input) {
id
uploadUrl
}
}
`,
variables: {
input: {
groupId: groupId,
title: title
}
}
})
});
const createResult = await createResponse.json();
const templateId = createResult.data.createTemplate.id;
const uploadUrl = createResult.data.createTemplate.uploadUrl;
console.log('Template created with ID:', templateId);
// Step 2: Upload the PDF
console.log('Uploading PDF...');
const fileData = fs.readFileSync(pdfFilePath);
const uploadResponse = await fetch(uploadUrl, {
method: 'PUT',
body: fileData,
headers: {
'Content-Type': 'application/pdf'
}
});
if (!uploadResponse.ok) {
throw new Error(`Upload failed: ${uploadResponse.statusText}`);
}
console.log('PDF uploaded successfully!');
return {
success: true,
templateId: templateId,
title: title
};
};
// Usage example
uploadPdfTemplate(
'grpYourGroupId',
'Employment Contract',
'./contract.pdf'
).then(result => {
console.log('Complete!', result);
}).catch(error => {
console.error('Error:', error);
});
Aucune dépendance supplémentaire nécessaire — Node.js 18+ inclut fetch nativement.
import requests
from gql import gql, Client
from gql.transport.requests import RequestsHTTPTransport
def upload_pdf_template(graphql_endpoint, auth_token, group_id, title, pdf_file_path):
transport = RequestsHTTPTransport(
url=graphql_endpoint,
headers={'Authorization': auth_token}
)
client = Client(transport=transport, fetch_schema_from_transport=True)
# Step 1: Create the template
print('Creating template...')
create_mutation = gql('''
mutation CreateTemplate($input: templateCreateInput!) {
createTemplate(input: $input) {
id
uploadUrl
}
}
''')
create_result = client.execute(
create_mutation,
variable_values={
'input': {
'groupId': group_id,
'title': title
}
}
)
template_id = create_result['createTemplate']['id']
upload_url = create_result['createTemplate']['uploadUrl']
print(f'Template created with ID: {template_id}')
# Step 2: Upload the PDF
print('Uploading PDF...')
with open(pdf_file_path, 'rb') as f:
file_data = f.read()
response = requests.put(
upload_url,
data=file_data,
headers={'Content-Type': 'application/pdf'}
)
if response.status_code != 200:
raise Exception(f'Upload failed: {response.status_code}')
print('PDF uploaded successfully!')
return {
'success': True,
'templateId': template_id,
'title': title
}
if __name__ == '__main__':
result = upload_pdf_template(
'https://graphql.uk.legalesign.com/graphql',
'Bearer YOUR_TOKEN',
'grpYourGroupId',
'Employment Contract',
'./contract.pdf'
)
print('Complete!', result)
using System;
using System.IO;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using GraphQL;
using GraphQL.Client.Http;
using GraphQL.Client.Serializer.Newtonsoft;
using Newtonsoft.Json.Linq;
public class PdfTemplateUploader
{
private readonly GraphQLHttpClient graphQLClient;
public PdfTemplateUploader(string graphqlEndpoint, string authToken)
{
graphQLClient = new GraphQLHttpClient(graphqlEndpoint, new NewtonsoftJsonSerializer());
graphQLClient.HttpClient.DefaultRequestHeaders.Add("Authorization", authToken);
}
public async Task<UploadResult> UploadPdfTemplate(
string groupId,
string title,
string pdfFilePath)
{
// Step 1: Create the template
Console.WriteLine("Creating template...");
var createMutation = new GraphQLRequest
{
Query = @"
mutation CreateTemplate($input: templateCreateInput!) {
createTemplate(input: $input) {
id
uploadUrl
}
}
",
Variables = new
{
input = new
{
groupId = groupId,
title = title
}
}
};
var createResponse = await graphQLClient.SendMutationAsync<dynamic>(createMutation);
string templateId = createResponse.Data.createTemplate.id;
string uploadUrl = createResponse.Data.createTemplate.uploadUrl;
Console.WriteLine($"Template created with ID: {templateId}");
// Step 2: Upload the PDF
Console.WriteLine("Uploading PDF...");
using var httpClient = new HttpClient();
var fileBytes = await File.ReadAllBytesAsync(pdfFilePath);
var content = new ByteArrayContent(fileBytes);
content.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/pdf");
var putResponse = await httpClient.PutAsync(uploadUrl, content);
if (!putResponse.IsSuccessStatusCode)
{
throw new Exception($"Upload failed: {putResponse.StatusCode}");
}
Console.WriteLine("PDF uploaded successfully!");
return new UploadResult
{
Success = true,
TemplateId = templateId,
Title = title
};
}
}
public class UploadResult
{
public bool Success { get; set; }
public string TemplateId { get; set; }
public string Title { get; set; }
}
class Program
{
static async Task Main(string[] args)
{
var uploader = new PdfTemplateUploader(
"https://graphql.uk.legalesign.com/graphql",
"Bearer YOUR_TOKEN"
);
var result = await uploader.UploadPdfTemplate(
"grpYourGroupId",
"Employment Contract",
"./contract.pdf"
);
Console.WriteLine($"Complete! Template ID: {result.TemplateId}");
}
}
Que Se Passe-t-il Après le Téléchargement ?
Une fois votre PDF téléchargé, Legalesign effectue automatiquement :
- Analyse antivirus - Vérifie que le fichier est sûr
- Validation ou conversion du fichier - Vérifie que les PDFs sont valides, ou convertit les fichiers supportés tels que les documents Word et images en PDF
- Extraction des informations de page - Obtient le nombre de pages et les dimensions
- Traitement du fichier - L’optimise pour la visualisation et la signature
- Stockage sécurisé - Le déplace vers un stockage permanent
Ce processus prend généralement quelques secondes. Une fois terminé, votre modèle est prêt à l’usage !
Suivre la Progression du Téléchargement
Pour obtenir un retour en temps réel sur le traitement du téléchargement (analyse, validation, finalisation), utilisez les abonnements. Voir Suivi de la progression du téléchargement avec les abonnements.
Vous pouvez également interroger le champ fileUploaded du modèle jusqu’à ce qu’il retourne true :
query CheckUploadStatus($id: ID!) {
template(id: $id) {
id
fileUploaded
}
}
Ajouter des Signatures et Champs
Si vous souhaitez automatiser les participants et le placement des champs, vous pouvez préparer le fichier source avant le téléchargement de plusieurs manières :
- Balises texte — Ajoutez des balises texte Legalesign dans le document source afin que les participants, champs de signature et champs de formulaire soient créés automatiquement lors du traitement. Passez
uploadOptions: { processTags: true }dans la mutationcreateTemplatepour activer cette fonctionnalité. Voir l’explication de l’API REST dans le tutoriel de démarrage rapide et la référence de l’endpoint Convert text tags. - Champs PDF intégrés — Si votre PDF contient déjà des champs de formulaire intégrés, passez
uploadOptions: { pdfFieldsImport: true }dans la mutationcreateTemplatepour les importer automatiquement en tant que champs de modèle.
Étapes Suivantes
Maintenant que vous avez un modèle avec un PDF, vous pouvez :
- Ajouter des champs de signature - Utilisez la mutation
createTemplateElementpour ajouter des champs - Créer des rôles - Définissez qui signera le document
- Envoyer pour signature - Utilisez la mutation
sendpour l’envoyer aux destinataires
Problèmes Courants et Solutions
Erreur « Pas de permission »
Vérifiez que votre ID de groupe est correct et que vous êtes authentifié avec le bon compte.
Erreur « Fichier trop volumineux »
Compressez votre PDF — la taille maximale est de 50 Mo.
URL de téléchargement expirée
Utilisez rapidement l’uploadUrl retournée par createTemplate. Si elle expire avant que vous ne téléchargiez, demandez une nouvelle URL avec la requête upload en utilisant l’ID du modèle enregistré.
Erreur « PDF invalide »
Ouvrez le PDF dans un lecteur PDF pour vérifier sa validité, puis réexportez ou enregistrez-le à nouveau.