Carica un file come modello
Questa guida ti accompagna attraverso il processo completo di creazione di un template e caricamento di un file PDF, immagine o Word da utilizzare come modello di documento in Legalesign.
What You'll Learn
Al termine di questa guida, saprai come:
- Creare un nuovo template nel tuo gruppo Legalesign
- Ottenere l'ID del template e l'URL di upload dalla risposta della mutation
- Caricare il file sorgente nel template
- Verificare che il caricamento sia avvenuto con successo
Prerequisites
Prima di iniziare, assicurati di avere:
- Un account Legalesign con accesso API
- Le tue credenziali di autenticazione (vedi la nostra guida all'autenticazione)
- Un file PDF, immagine o Word pronto per il caricamento (massimo 50MB)
- L'ID del tuo gruppo (lo spazio di lavoro in cui desideri creare il template)
The Complete Process
Step 1: Create a Template
Per prima cosa, crea un template vuoto in Legalesign. Questo restituisce sia l'ID del template sia un URL di upload pre-firmato per il caricamento del PDF. Per farlo dovrai eseguire una mutation GraphQL, se non l’hai mai fatto vedi l’Introduzione a GraphQL.
What is a Template?
Un template è una struttura di documento riutilizzabile in Legalesign. Una volta caricato un PDF in un template, puoi:
- Aggiungere campi firma e campi modulo
- Inviarlo a più destinatari
- Riutilizzarlo per firmatari diversi
GraphQL Mutation
mutation CreateTemplate($input: templateCreateInput!) {
createTemplate(input: $input) {
id
uploadUrl
}
}
Input Variables
{
"input": {
"groupId": "grpYourGroupAPIId",
"title": "Employment Contract Template"
}
}
Parameters Explained
- groupId: L'ID Base64 del tuo gruppo/spazio di lavoro (puoi recuperarlo dall’URL nella Console https://console.legalesign.com/)
- title: Un nome descrittivo per il tuo template (puoi cambiarlo in seguito)
- uploadOptions (opzionale): Opzioni di elaborazione applicate quando il PDF viene caricato:
pdfFieldsImport: true— importa i campi modulo PDF incorporati come campi del templateprocessTags: true— elabora i tag di testo Legalesign nel documento durante il caricamento
Step 2: Extract the Template ID and Upload URL
La mutation restituisce un oggetto templateCreateOutput. Salva il campo id e la stringa uploadUrl.
Esempio di risposta:
{
"data": {
"createTemplate": {
"id": "dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx",
"uploadUrl": "https://s3.amazonaws.com/bucket/path?signature=..."
}
}
}
L'ID del template è una stringa codificata in Base64. Salva entrambi i valori dalla risposta. L’uploadUrl ha una durata breve e deve essere utilizzato rapidamente.
Step 3: Upload Your PDF
Usa l’uploadUrl restituito per caricare direttamente il file PDF su S3. Questo varierà a seconda dello stack di sviluppo. Nel nostro esempio in javascript abbiamo usato fetch ma puoi usare altre librerie incluso aws-amplify.
Complete Working Examples
- 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);
});
Nessuna dipendenza aggiuntiva necessaria — Node.js 18+ include fetch nativamente.
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}");
}
}
What Happens After Upload?
Una volta caricato il PDF, Legalesign automaticamente:
- Scansiona per virus - Assicura che il file sia sicuro
- Valida o converte il file - Controlla che i PDF siano validi, oppure converte file supportati come documenti Word e immagini in PDF
- Estrae informazioni sulle pagine - Ottiene il numero di pagine e le dimensioni
- Elabora il file - Lo ottimizza per la visualizzazione e la firma
- Lo archivia in modo sicuro - Lo sposta in uno storage permanente
Questo processo dura di solito pochi secondi. Una volta completato, il tuo template è pronto all’uso!
Track Upload Progress
Per avere un feedback in tempo reale sull’elaborazione del caricamento (scansione, validazione, completamento), usa le subscription. Vedi Track Upload Progress with Subscriptions.
In alternativa, puoi interrogare ripetutamente il campo fileUploaded del template finché non restituisce true:
query CheckUploadStatus($id: ID!) {
template(id: $id) {
id
fileUploaded
}
}
Adding Signatures and Fields
Se vuoi automatizzare la partecipazione e il posizionamento dei campi, puoi preparare il file sorgente prima del caricamento in un paio di modi diversi:
- Text tags — Aggiungi tag di testo Legalesign nel documento sorgente così che partecipanti, campi firma e campi modulo possano essere creati automaticamente durante l’elaborazione. Passa
uploadOptions: { processTags: true }nella mutationcreateTemplateper attivare questa funzione. Vedi la spiegazione REST API nel tutorial rapido e la referenza endpoint Convert text tags. - Embedded PDF fields — Se il tuo PDF contiene già campi modulo incorporati, passa
uploadOptions: { pdfFieldsImport: true }nella mutationcreateTemplateper importarli automaticamente come campi del template.
Next Steps
Ora che hai un template con un PDF, puoi:
- Aggiungere campi firma - Usa la mutation
createTemplateElementper aggiungere i campi - Creare ruoli - Definisci chi firmerà il documento
- Inviare per la firma - Usa la mutation
sendper inviare ai destinatari
Common Issues and Solutions
"No permission" Error
Verifica che l'ID del gruppo sia corretto e che tu sia autenticato con l’account giusto.
"File too large" Error
Comprimi il tuo PDF — il massimo è 50MB.
Upload URL Expired
Usa rapidamente l’uploadUrl restituito da createTemplate. Se scade prima del caricamento, richiedi un nuovo URL con la query upload usando l’ID del template salvato.
"Invalid PDF" Error
Apri il PDF in un lettore PDF per verificarne la validità, quindi riesportalo o salvalo nuovamente.