Vai al contenuto principale

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:

  1. Creare un nuovo template nel tuo gruppo Legalesign
  2. Ottenere l'ID del template e l'URL di upload dalla risposta della mutation
  3. Caricare il file sorgente nel template
  4. 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 template
    • processTags: 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=..."
}
}
}
suggerimento

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​

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.

What Happens After Upload?​

Una volta caricato il PDF, Legalesign automaticamente:

  1. Scansiona per virus - Assicura che il file sia sicuro
  2. Valida o converte il file - Controlla che i PDF siano validi, oppure converte file supportati come documenti Word e immagini in PDF
  3. Estrae informazioni sulle pagine - Ottiene il numero di pagine e le dimensioni
  4. Elabora il file - Lo ottimizza per la visualizzazione e la firma
  5. 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 mutation createTemplate per 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 mutation createTemplate per importarli automaticamente come campi del template.

Next Steps​

Ora che hai un template con un PDF, puoi:

  1. Aggiungere campi firma - Usa la mutation createTemplateElement per aggiungere i campi
  2. Creare ruoli - Definisci chi firmerà il documento
  3. Inviare per la firma - Usa la mutation send per 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.