Vai al contenuto principale

Carica un file come modello

Questa guida ti accompagna attraverso l'intero processo di creazione di un modello 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 modello nel tuo gruppo Legalesign
  2. Ottenere l'ID del modello e l'URL di caricamento dalla risposta della mutation
  3. Caricare il file sorgente nel modello
  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)
  • Il tuo ID gruppo (lo spazio di lavoro in cui vuoi creare il modello)

The Complete Process​

Step 1: Create a Template​

Per prima cosa, crea un modello vuoto in Legalesign. Questo restituisce sia l'ID del modello sia un URL di caricamento pre-firmato per caricare il PDF.
Per fare questo, dovrai eseguire una mutation GraphQL; se non l'hai mai fatto prima, consulta l'Introduzione a GraphQL.

What is a Template?​

Un template è una struttura di documento riutilizzabile in Legalesign. Una volta caricato un PDF in un modello, puoi:

  • Aggiungere campi firma e campi modulo
  • Inviarlo a più destinatari
  • Riutilizzarlo per diversi firmatari

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 in base 64 del tuo gruppo/spazio di lavoro (puoi prenderlo dall'URL nella Console https://console.legalesign.com/)
  • title: Un nome descrittivo per il tuo modello (puoi modificarlo in seguito)

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 modello è una stringa codificata in Base64. Salva entrambi i valori dalla risposta.
L'uploadUrl ha una durata limitata e deve essere usato rapidamente.

Step 3: Upload Your PDF​

Usa l'uploadUrl restituito per caricare direttamente il tuo file PDF su S3. Questo processo varierà in base alla tua stack di sviluppo.
Nel nostro esempio javascript abbiamo usato fetch ma puoi usare altre librerie incluse 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 - Verifica che i PDF siano validi, o 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 di solito richiede pochi secondi. Una volta completato, il tuo modello è pronto per l'uso!

Track Upload Progress​

Per ottenere feedback in tempo reale sull'elaborazione del caricamento (scansione, validazione, completamento), usa le subscriptions. Vedi Traccia il progresso del caricamento con le Subscription.

In alternativa, fai polling del campo fileUploaded del modello finché non torna true:

query CheckUploadStatus($id: ID!) {
  template(id: $id) {
    id
    fileUploaded
  }
}

Adding Signatures and Fields​

Se vuoi automatizzare i partecipanti e la collocazione dei campi, puoi preparare il file sorgente prima del caricamento in un paio di modi diversi:

  • Tag di testo – Aggiungi tag di testo Legalesign nel documento sorgente per permettere la creazione automatica durante l'elaborazione di partecipanti, campi firma e campi modulo. Consulta la spiegazione REST API nel tutorial quickstart e il riferimento all’endpoint Convert text tags.
  • Campi PDF incorporati – Se il tuo PDF contiene già campi modulo incorporati, Legalesign può usarli come parte del flusso di caricamento e preparazione del modello.

Next Steps​

Ora che hai un modello con un PDF, puoi:

  1. Aggiungere campi firma – Usa la mutation createTemplateElement per aggiungere 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 tuo gruppo sia corretto e che tu sia autenticato con l’account giusto.

"File too large" Error​

Comprimi il PDF — il massimo è 50MB.

Upload URL Expired​

Usa l’uploadUrl restituito da createTemplate rapidamente.
Se scade prima del caricamento, richiedi un nuovo URL con la query upload usando l’ID del modello salvato.

"Invalid PDF" Error​

Apri il PDF in un lettore PDF per verificarne la validità, poi riesportalo o risalvalo.

Export This Article

Save a copy of this page as PDF or plain text.