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 usare come modello del documento in Legalesign.

suggerimento

Hai bisogno di un feedback in tempo reale sul processo di caricamento? Vedi Traccia il progresso del caricamento con le sottoscrizioni.

Cosa Imparerai​

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 upload dalla risposta della mutation
  3. Caricare il file sorgente nel modello
  4. Verificare che il caricamento sia avvenuto con successo

Prerequisiti​

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 (l’ambiente di lavoro dove vuoi creare il modello)

Il Processo Completo​

Passo 1: Crea un Modello​

Per prima cosa, crea un modello vuoto in Legalesign. Questo restituisce sia l’ID del modello sia un URL firmato per il caricamento del PDF. Per fare questo devi eseguire una mutation GraphQL, se non l’hai mai fatto prima leggi l’Introduzione a GraphQL.

Cos’è un Modello?​

Un modello è 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 firmatari diversi

Mutation GraphQL​

mutation CreateTemplate($input: templateCreateInput!) {
  createTemplate(input: $input) {
    id
    uploadUrl
  }
}

Variabili di Input​

{
  "input": {
    "groupId": "grpYourGroupAPIId",
    "title": "Employment Contract Template"
  }
}

Parametri Spiegati​

  • groupId: L’ID base 64 del tuo gruppo/ambiente di lavoro (lo puoi prendere dall’URL nella Console https://console.legalesign.com/)
  • title: Un nome descrittivo per il tuo modello (puoi modificarlo in seguito)

Passo 2: Estrai l’ID del Modello e l’URL di Upload​

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 modello è una stringa codificata in Base64. Salva entrambi i valori della risposta. L’uploadUrl è a breve termine e deve essere usato rapidamente.

Passo 3: Carica il Tuo PDF​

Usa l’uploadUrl restituito per caricare il file PDF direttamente su S3. Questo varia a seconda del tuo stack di sviluppo. Nel nostro esempio javascript abbiamo usato fetch ma puoi usare altre librerie incluso aws-amplify.

Esempi Funzionanti Completi​

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.

Cosa Succede Dopo il Caricamento?​

Una volta caricato il PDF, Legalesign automaticamente:

  1. Scansiona per virus - Verifica che il file sia sicuro
  2. Valida o converte il file - Controlla che i PDF siano validi, o converte file supportati come documenti Word e immagini in PDF
  3. Estrae le informazioni sulle pagine - Ottiene il numero e le dimensioni delle pagine
  4. Elabora il file - Lo ottimizza per la visualizzazione e la firma
  5. Lo conserva in modo sicuro - Lo sposta in uno storage permanente

Questo processo di solito richiede pochi secondi. Una volta completato, il tuo modello è pronto all’uso!

Aggiungere Firme e Campi​

Se vuoi automatizzare partecipanti e posizionamento dei campi, puoi preparare il file sorgente prima del caricamento in diversi modi:

  • Tag di testo - Inserisci tag di testo Legalesign nel documento sorgente così partecipanti, campi firma e campi modulo possono essere creati automaticamente durante l’elaborazione. Vedi la spiegazione REST API nel tutorial quickstart e il riferimento all’endpoint Converti tag di testo.
  • Campi PDF incorporati - Se il tuo PDF contiene già campi modulo incorporati, Legalesign può usarli come parte del processo di caricamento e preparazione del modello.

Prossimi Passi​

Ora che hai un modello con un PDF, puoi:

  1. Aggiungere campi firma - Usa la mutation createTemplateElement per aggiungere campi
  2. Creare ruoli - Definire chi firmerà il documento
  3. Inviare per la firma - Usa la mutation send per spedirlo ai destinatari

Problemi Comuni e Soluzioni​

Errore “Nessun permesso”​

Verifica che il tuo ID gruppo sia corretto e che tu sia autenticato con l’account giusto.

Errore “File troppo grande”​

Comprimi il tuo PDF — il limite è 50MB.

URL di upload scaduto​

Usa subito l’uploadUrl restituito da createTemplate. Se scade prima che tu carichi, richiedi un nuovo URL con la query upload usando l’ID modello salvato.

Errore “PDF non valido”​

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

Tracciare il Progresso del Caricamento​

Per avere un feedback in tempo reale sull’elaborazione del caricamento (scansione, validazione, completamento), usa le sottoscrizioni. Vedi Traccia il progresso del caricamento con le sottoscrizioni.

Export This Article

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