Integra il Visualizzatore di Documenti Legalesign nel Tuo Sito Web

suggerimento

Puoi vedere questo componente in azione come Invio Rapido in Console.

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

Questo componente plug and play è progettato affinché tu possa integrare parti chiave della creazione di 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 Visualizzatore di Documenti.

Se hai bisogno di ulteriore aiuto per integrare il Visualizzatore di Documenti nel tuo stack tecnico, ti preghiamo di contattare il nostro supporto.

Puoi usare questi widget più grandi con integrazioni REST/GraphQL API per fornire processi di firma di documenti fluidi per il tuo staff e 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 al componente direttamente da npm se il tuo ambiente non consente di installarlo. Puoi provare una pagina di dimostrazione 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 tre opzioni:

SRP JWT direttamente — Se il tuo backend usa già l'autenticazione SRP, passa direttamente il token di accesso JWT al widget.
GraphQL generateComponentToken — Chiama la mutation con la tua API key o SRP JWT per generare un token componente a breve durata e limitato.
REST API — Chiama GET /templatepdf/{pdfId}/component-token/ con la tua API key.

Opzione 2 (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 3 (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 (o il tuo SRP JWT) al widget. Vedi Autorizzazione Widget per maggiori dettagli sulle opzioni di 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. Può essere un token di accesso SRP JWT oppure un token componente a breve durata generato da generateComponentToken. Vedi Autorizzazione Widget per il flusso sicuro del token.

token="eyJraWQiOiJBTkJIeT..."

templateid

L'ID API del modello che vuoi presentare agli utenti. Lo puoi trovare guardando nell'URL mentre modifichi il modello nell'App Web.

templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"

Modalità Editor

Creazione e modifica completa del modello con tutti gli strumenti disponibili. Questa modalità è pensata per flussi di lavoro dove è utile un modello altamente riutilizzabile con ruoli. Se la tua intenzione è usare il documento una sola volta (forse il tuo sistema di generazione documenti ha già popolato tutte le informazioni del cliente) potresti 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 è la funzione "Invio rapido".

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

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

Clona

Clona un modello 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 modello e caricalo poi nel uploadUrl fornito. Usa titolo [deleted] se non vuoi che il pdf rimanga nella tua libreria. Verrà cancellato entro 24 ore. Altrimenti usa un qualsiasi titolo a tua scelta:

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 un PUT del tuo file nell'uploadUrl. Il content type deve essere application/pdf.

Incorpora il visualizzatore

L'attributo principale è 'recipients'. Ti serviranno 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 i destinatari pre-generati
Nasconde il mittente nel dropdown
Nasconde le opzioni del documento
Mostra i campi richiesti di default
Rimuove mittente e campi mittente dall'editor
Favorisce la selezione rapida dei campi richiesti per ogni destinatario

Modalità Anteprima

Una utile anteprima del documento che mostra il documento con tutti i campi correnti e consente all'utente di sfogliare le pagine.

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

La modalità anteprima automaticamente:

Nasconde la toolbar
Nasconde le opzioni del 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à non filtrata e tutte le opzioni disponibili.

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

Valori di filtro disponibili:

Valore	Descrizione
`signature`	Campo firma (solo firmatario)
`auto sign`	Campo firma automatica (solo mittente)
`text`	Campo testo libero
`signing date`	Data compilata automaticamente al momento della firma (solo firmatario)
`date`	Campo selettore data
`email`	Campo email
`initials`	Campo iniziali
`number`	Campo numerico
`dropdown`	Campo menu a tendina
`checkbox`	Checkbox
`regex`	Campo con validazione regex (solo firmatario)
`image`	Upload immagine (solo firmatario)
`file`	Upload file (solo firmatario)
`drawn`	Campo disegnato/libera mano (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 il ruolo e il numero di telefono per ogni destinatario. L'omissione del ruolo significa che il destinatario sarà trattato come firmatario.

Puoi passare ruolo "WITNESS" o "APPROVER". Per il ruolo "WITNESS" aggiungi 100 al signerIndex del firmatario. Per esempio, se hai bisogno di un testimone per il firmatario 2 (signerIndex: 2), il WITNESS avrà 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 monitorare i cambiamenti:

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

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

Puoi rilevare se un modello è 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 di Gestione Eventi in React

Usando un evento in React lo si premette con il familiare on<EventName>.

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

Tipi di Eventi

Evento `update`

Scatenato quando il modello documentale viene modificato, ad esempio aggiungendo o rimuovendo campi. Fornisce non solo l'evento che l'ha causato ma anche lo stato aggiornato dell'oggetto modello in JSON.

Evento `validate`

Scatenato quando il modello documentale viene modificato, la proprietà valid nel dettaglio mostra se il modello è diventato valido o non valido.

Evento `selectFields`

Scatenato quando un campo viene selezionato nell'editor.

Evento `addParticipant`

Scatenato quando un ruolo partecipante viene aggiunto al modello.

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>

Puoi usare la mutation send GraphQL lato client se usi il token SRP JWT, altrimenti lato server usando la tua API Key con l'interfaccia GraphQL o REST.

Send mutation — invia un singolo documento
Schema Input Send — riferimento completo dell’input
REST Send - riferimento invio documento REST

Risoluzione dei Problemi

Se incontri problemi con il componente, assicurati che:

puoi accedere o hai messo in whitelist il dominio di storage del documento su https://s3.amazonaws.com/*

Supporto Browser

Il componente usa standard web moderni e supporta:

Chrome/Edge (ultime versioni)
Firefox (ultime versioni)
Safari (ultime versioni)
Browser mobili (iOS Safari, Chrome Mobile)

Risorse

Guida all'Integrazione GraphQL — come collegare il visualizzatore all’API GraphQL per l’invio
Documentazione API GraphQL
Pacchetto NPM
Pacchetto React
Supporto

Ottenere Aiuto

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

Integra il Visualizzatore di Documenti Legalesign nel Tuo Sito Web

Installazione

Installazione NPM

Per Progetti React

Integrazione Base

HTML/JavaScript

Autenticazione - Ottieni un token

Integrazione React

Attributi Richiesti

token

templateid

Modalità del Widget

Modalità Editor

Modalità Compose

Clona

Oppure Carica

Incorpora il visualizzatore

Modalità Anteprima

Configurazione Avanzata

Filtra Toolbox

Destinatari

Pulsanti Personalizzati con Slot

Gestione Eventi

Esempio di Gestione Eventi in React

Tipi di Eventi

Evento `update`

Evento `validate`

Evento `selectFields`

Evento `addParticipant`

Esempio Completo

Risoluzione dei Problemi

Supporto Browser

Risorse

Ottenere Aiuto

Export This Article

Installazione​

Installazione NPM​

Per Progetti React​

Integrazione Base​

HTML/JavaScript​

Autenticazione - Ottieni un token​

Integrazione React​

Attributi Richiesti​

token​

templateid​

Modalità del Widget​

Modalità Editor​

Modalità Compose​

Clona​

Oppure Carica​

Incorpora il visualizzatore​

Modalità Anteprima​

Configurazione Avanzata​

Filtra Toolbox​

Destinatari​

Pulsanti Personalizzati con Slot​

Gestione Eventi​

Esempio di Gestione Eventi in React​

Tipi di Eventi​

Evento update​

Evento validate​

Evento selectFields​

Evento addParticipant​

Esempio Completo​

Risoluzione dei Problemi

Supporto Browser​

Risorse​

Ottenere Aiuto​

Export This Article

Installazione

Installazione NPM

Per Progetti React

Integrazione Base

HTML/JavaScript

Autenticazione - Ottieni un token

Integrazione React

Attributi Richiesti

token

templateid

Modalità del Widget

Modalità Editor

Modalità Compose

Clona

Oppure Carica

Incorpora il visualizzatore

Modalità Anteprima

Configurazione Avanzata

Filtra Toolbox

Destinatari

Pulsanti Personalizzati con Slot

Gestione Eventi

Esempio di Gestione Eventi in React

Tipi di Eventi

Evento `update`

Evento `validate`

Evento `selectFields`

Evento `addParticipant`

Esempio Completo

Supporto Browser

Risorse

Ottenere Aiuto