Vai al contenuto principale

Integra Legalesign Document Viewer nel Tuo Sito Web

suggerimento

Puoi vedere questo componente in azione come Quick Send nella Console.

Versione corrente: v1.0.27 — changelog

Il Legalesign Document Viewer è un componente web indipendente dalla piattaforma che ti permette di modificare, visualizzare in anteprima e personalizzare i modelli per la firma dei documenti. Funziona perfettamente in HTML con JavaScript, React, Vue, Angular o qualsiasi framework web.

Questo componente plug and play è progettato per permetterti di integrare parti chiave della creazione dei documenti nei tuoi sistemi interni, come un CRM o un'applicazione di business.

Finché il tuo sistema può renderizzare e supportare componenti HTML, puoi usare il Document Viewer.

Se hai bisogno di ulteriore assistenza per integrare il Document Viewer nel tuo stack tecnico, contatta il nostro supporto.

Puoi usare questi widget più grandi con integrazioni API REST/GraphQL per fornire processi di firma documenti senza soluzione di continuità per il tuo staff e i tuoi clienti.

Installazione​

Installazione NPM​

npm install legalesign-document-viewer
# or
pnpm add legalesign-document-viewer

Per Progetti React​

npm install legalesign-document-viewer-react
# or
pnpm add legalesign-document-viewer-react

Integrazione Base​

HTML/JavaScript​

La versione HTML/JavaScript di questo componente può essere usata con qualsiasi stack di sviluppo, come PHP, ASP .Net ecc. Puoi collegarti direttamente al componente da npm se il tuo ambiente non permette di installarlo. Puoi provare una pagina dimostrativa dal repository di esempio qui [https://github.com/legalesign/ls-viewer-demo].

Aggiungi gli script del componente al tuo HTML:

<!DOCTYPE html>
<html>
<head>
<link rel="stylesheet" href="node_modules/legalesign-document-viewer/dist/ls-document-viewer/ls-document-viewer.css" />
<script type="module" src="node_modules/legalesign-document-viewer/dist/ls-document-viewer/ls-document-viewer.esm.js"></script>
<script nomodule src="node_modules/legalesign-document-viewer/dist/ls-document-viewer/ls-document-viewer.js"></script>
</head>
<body>
<ls-document-viewer
id="my-editor"
templateid="YOUR_TEMPLATE_ID"
token="YOUR_AUTH_TOKEN"
></ls-document-viewer>
</body>
</html>

Autenticazione - Ottieni un token​

Dovrai usare codice lato server per ottenere YOUR_AUTH_TOKEN. Ci sono due opzioni, entrambe usano la tua API key:

  1. GraphQL generateComponentToken — Chiama la mutation con la tua API key per generare un token componente a breve durata e con ambito definito.
  2. REST API — Chiama GET /templatepdf/{pdfId}/component-token/ con la tua API key.

Opzione 1 (GraphQL):

const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${process.env.LEGALESIGN_API_KEY}`,
},
body: JSON.stringify({
query: `mutation {
generateComponentToken(input: { component: LS_DOCUMENT_VIEWER }) {
token
expiresIn
expiresAt
}
}`,
}),
});

const { data } = await response.json();
const token = data.generateComponentToken.token;

Opzione 2 (REST):

const response = await fetch(
`https://eu-api.legalesign.com/api/v1/templatepdf/${pdfId}/component-token/`,
{
headers: {
Authorization: `Bearer ${process.env.LEGALESIGN_API_KEY}`,
},
}
);

const { token } = await response.json();

Passa il token restituito al widget. Consulta Autorizzazione del Widget per maggiori dettagli sulle opzioni token.

Integrazione React​

Abbiamo anche generato una versione del componente che si integra direttamente con i framework React.

import { LsDocumentViewer } from 'legalesign-document-viewer-react';

function App() {
return (
<LsDocumentViewer
templateid="YOUR_TEMPLATE_ID"
token="YOUR_AUTH_TOKEN"
mode="compose"
/>
);
}

Attributi Richiesti​

token​

Il tuo token di sicurezza per l'autenticazione: un token componente a breve durata ottenuto da generateComponentToken o dall’endpoint REST component-token. Vedi Autorizzazione del Widget per il flusso token sicuro.

token="eyJraWQiOiJBTkJIeT..."

templateid​

L'ID API del template che vuoi presentare agli utenti. Puoi trovarlo guardando l’URL quando modifichi il template nell’App Web.

templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"

Modalità del Widget​

Modalità Editor​

Creazione e modifica completa dei template con tutti gli strumenti disponibili. È pensata per flussi di lavoro dove un template altamente riutilizzabile con ruoli è utile. Se la tua intenzione è usare il documento solo una volta (forse il tuo sistema di generazione documenti ha già compilato tutte le informazioni del cliente) potresti voler considerare invece la modalità compose.

<ls-document-viewer mode="editor" ...></ls-document-viewer>

Modalità Compose​

Questa modalità è un metodo "recipient-first" per semplificare l'esperienza utente. Nell’App Web Legalesign questa è la funzione "Quick send".

Aggiungi i tuoi destinatari all’attributo 'recipient' e l’utente potrà rapidamente posizionare le firme e i campi del modulo, prima di inviare. Ideale per clienti integrati dove i destinatari sono già definiti.

Il flusso tipico è clonare o caricare un PDF, poi incorporare il viewer dove l’utente può aggiungere campi firma e moduli, quindi offrire un pulsante per inviare il documento.

Clona​

Clona un template esistente usando la mutation copyTemplate:

const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: `
mutation CopyTemplate {
copyTemplate(input: {
groupId: "yourGroupId",
templateId: "yourTemplateId",
newTitle: "new document title",
copyFields: true|false
})
}
`
})
});
const { data } = await response.json();
const templateId = data.copyTemplate;

Oppure Carica​

Crea un template e poi caricalo all’uploadUrl fornito. Usa titolo [deleted] se non vuoi il PDF nella tua libreria. Verrà cancellato nelle successive 24 ore. Altrimenti usa qualsiasi titolo preferisci:

const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json'
},
body: JSON.stringify({
query: `
mutation CreateTemplate {
createTemplate(input: {groupId: "yourGroupid", title: "[deleted]"}) {
id
uploadUrl
}
}
`
})
});
const { data } = await response.json();
const templateId = data.createTemplate.id;
const uploadUrl = data.createTemplate.uploadUrl;

Ora fai PUT del tuo file all’uploadUrl. Il tipo contenuto deve essere application/pdf.

Incorpora il viewer​

L’attributo principale è 'recipients'. Avrai bisogno di dettagli aggiuntivi per approvatori o testimoni - per maggiori informazioni vedi Destinatari.

<ls-document-viewer 
mode="compose"
recipients='[
{"email": "user@example.com", "firstname": "John", "lastname": "Doe", "signerIndex": 1},
{"email": "user2@example.com", "firstname": "Jane", "lastname": "Smith", "signerIndex": 2}
]'
...></ls-document-viewer>

La modalità compose automaticamente:

  • Rileva destinatari pre-generati
  • Nasconde il mittente nel dropdown
  • Nasconde le opzioni documento
  • Mostra i campi obbligatori di default
  • Rimuove il mittente e i campi mittente dall’editor
  • Promuove la selezione rapida dei campi richiesti per ogni destinatario

Modalità Anteprima​

Un’anteprima utile del documento che mostra il documento con tutti i campi correnti e permette all’utente di sfogliare le pagine.

<ls-document-viewer mode="preview" ...></ls-document-viewer>

La modalità anteprima automaticamente:

  • Nasconde la toolbar
  • Nasconde le opzioni documento
  • Nasconde la toolbox
  • Rende partecipanti e campi in sola lettura

Configurazione Avanzata​

Filtra Toolbox​

Restringi i tipi di campo disponibili usando valori separati da pipe. Se non viene fornito alcun valore, si assume che la toolbox sarà senza filtri e tutte le opzioni saranno disponibili.

<ls-document-viewer
filtertoolbox="signature|initials|date|text"
...
></ls-document-viewer>

Valori filtro disponibili:

ValoreDescrizione
signatureCampo firma (solo firmatario)
auto signCampo firma automatica (solo mittente)
textInput testo libero
signing dateData compilata automaticamente al momento della firma (solo firmatario)
dateCampo selezione data
emailInput email
initialsCampo iniziali
numberInput numerico
dropdownSelezione a discesa
checkboxCheckbox
regexInput con validazione regex (solo firmatario)
imageUpload immagine (solo firmatario)
fileUpload file (solo firmatario)
drawnCampo disegnato/libero (solo firmatario)

Destinatari​

Definisci i destinatari del documento in formato JSON.

Gli elementi richiesti per ogni destinatario sono firstname, lastname, email e signerIndex;

Opzionalmente puoi passare ruolo e numero di telefono per ogni destinatario. Omettere il ruolo significa che il destinatario sarà considerato un firmatario.

Puoi passare ruolo "WITNESS" o "APPROVER". Per il ruolo "WITNESS" aggiungi 100 al numero signerIndex del suo firmatario. Ad esempio, se serve un testimone per il firmatario 2 (signerIndex: 2), fai che il WITNESS abbia signerIndex: 102.

<ls-document-viewer
recipients='[
{"email": "user@example.com", "firstname": "John", "lastname": "Doe", "signerIndex": 1},
{"email": "user2@example.com", "firstname": "Jane", "lastname": "Smith", "signerIndex": 2}
{"email": "user3@example.com", "firstname": "Joan", "lastname": "Mitchell", "signerIndex": 102, roleType: "WITNESS"}
]'
...
></ls-document-viewer>

Pulsanti Personalizzati con Slot​

Aggiungi pulsanti personalizzati alla toolbar usando gli slot. Probabilmente li userai per annullare l’azione o inviare il documento.

<ls-document-viewer ...>
<style>
.custom-button {
padding: 2px 12px;
border-radius: 1rem;
background-color: #9df5d4;
color: #125241;
font-weight: 500;
}
</style>
<span slot="left-button">
<button class="custom-button">Cancel</button>
</span>
<span slot="right-button">
<button class="custom-button">Send Document</button>
</span>
</ls-document-viewer>

Gestione Eventi​

Ascolta gli eventi del componente per tracciare i cambiamenti:

const editor = document.querySelector('ls-document-viewer');

editor.addEventListener('update', (event) => {
console.log('Template changed:', event.detail);
});

Puoi tracciare se un template è diventato valido o non valido usando l’evento validate.

const editor = document.querySelector('ls-document-viewer');

editor.addEventListener('validate', (event) => {
console.log('Template validation changed:', event.detail.valid);
});

Esempio Gestione Eventi React​

Usando un evento in react si antepone il prefisso familiare on<EventName>.

<LsDocumentViewer
onUpdate={(event) => {
console.log('Template changed:', event.detail);
}}
...
/>

Tipi di Evento​

Evento update​

Scatena quando il template del documento viene modificato, ad esempio aggiungendo o rimuovendo campi. Fornisce non solo l’evento che lo ha causato ma anche lo stato aggiornato dell’oggetto template come JSON.

Evento validate​

Scatena quando il template del documento viene modificato, la proprietà valid in detail indica se il template è diventato valido o non valido.

Evento selectFields​

Scatena quando un campo viene selezionato nell’editor.

Evento addParticipant​

Scatena quando un ruolo partecipante viene aggiunto al template.

Esempio Completo​

<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Document Editor</title>
<link rel="stylesheet" href="https://unpkg.com/legalesign-document-viewer/ls-document-viewer.css" />
<script type="module" src="https://unpkg.com/legalesign-document-viewer"></script>
</head>
<body style="padding: 0; margin: 0">
<ls-document-viewer
id="my-editor"
templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
token="YOUR_TOKEN_HERE"
mode="compose"
recipients='[
{"email": "signer@example.com", "firstname": "John", "lastname": "Doe", "signerIndex": 1}
]'
filtertoolbox="signature|initials|date"
>
<span slot="left-button">
<button onclick="handleCancel()">Cancel</button>
</span>
<span slot="right-button">
<button onclick="handleSend()">Send</button>
</span>
</ls-document-viewer>

<script>
const editor = document.querySelector('ls-document-viewer');

editor.addEventListener('update', (event) => {
// shows the change event and the template details
console.log('Document updated:', event.detail);
});

function handleCancel() {
// Implement the cancel logic, e.g. go to a home page
window.location.href = '/cancelpage';
}

function handleSend() {
// Implement send logic if required.
console.log('Sending document...');
}
</script>
</body>
</html>

Invia il documento lato server usando la tua API key, con l’interfaccia GraphQL o REST.

Risoluzione Problemi

Se incontri problemi con il componente, assicurati che:

Supporto Browser​

Il componente usa standard web moderni e supporta:

  • Chrome/Edge (ultima versione)
  • Firefox (ultima versione)
  • Safari (ultima versione)
  • Browser mobile (iOS Safari, Chrome Mobile)

Cronologia delle Versioni​

VersioneDataSommario
v1.0.2719 Ott 2026Miglioramenti nel posizionamento dei campi
v1.0.263 Set 2026Correzioni di scroll; rendering differito al caricamento
v1.0.2112 Ago 2026Opzioni modalità anteprima; miglioramento evento update
v1.0.1817 Lug 2026Pannello campo regex; proprietà avanzate multi-campo; miglioramenti dropdown; rinomina testimone
v1.0.1210 Lug 2026Proprietà campo excludeFromPdf
v1.0.99 Lug 2026Campi data automatica e regex; proprietà avanzate; ordine campi
v1.0.62 Lug 2026Correzione font per evitare errori di firma; margini anteprima
v1.0.529 Giu 2026Scorciatoie tastiera per annulla/ripristina
v1.0.426 Giu 2026Miglioramenti eventi; aggiornamenti ottimistici; annulla/ripristina
v1.0.024 Giu 2026Prima versione stabile

Risorse​

Ottenere Aiuto​

Per supporto tecnico o domande sull’integrazione, contatta il team di supporto Legalesign o visita la documentazione API.