Integrare il Visualizzatore di Documenti

Il Visualizzatore di Documenti è un componente web che permette agli utenti di modificare modelli e preparare documenti per la firma — direttamente all'interno della tua applicazione. Questa guida mostra come collegarlo all'API GraphQL per costruire un flusso completo di firma.

Panoramica

Una tipica integrazione segue questi passaggi:

Autenticarsi — ottenere un token per il visualizzatore
Caricare un modello — tramite l’API GraphQL
Visualizzare il visualizzatore — passare l’ID del modello e il token
Catturare gli eventi — il visualizzatore emette gli eventi update e validate mentre l’utente lavora
Inviare il documento — chiamare la mutation send con i dati dei destinatari e dei ruoli dal visualizzatore

Autenticazione

Il visualizzatore necessita di un token valido passato al suo attributo token. Il tuo backend può fornire un JWT SRP oppure un token a breve durata generato tramite generateComponentToken. Consulta Autorizzazione Widget prima di integrare il visualizzatore nella tua applicazione.

Modalità Composizione — Inviare un Documento Predefinito

La modalità composizione è per flussi in cui il tuo sistema conosce già i destinatari. L’utente si limita a posizionare i campi firma e a inviare.

1. Visualizzare il visualizzatore

<ls-document-viewer
  id="viewer"
  templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
  token="YOUR_ACCESS_TOKEN"
  mode="compose"
  recipients='[
    {"email": "jane@example.com", "firstname": "Jane", "lastname": "Smith", "signerIndex": 1},
    {"email": "john@example.com", "firstname": "John", "lastname": "Doe", "signerIndex": 2}
  ]'
  filtertoolbox="signature|initials|date|text"
>
  <span slot="right-button">
    <button id="send-btn" disabled>Send</button>
  </span>
</ls-document-viewer>

2. Monitorare la validazione e gli ID dei ruoli

Quando l’utente aggiunge campi, il visualizzatore emette eventi. Ti servono due informazioni da questi eventi:

validate — indica se il modello ha tutti i campi obbligatori (al minimo, una firma per ogni destinatario)
update — fornisce lo stato corrente del modello, inclusi roleId per ogni partecipante quando serve la mappatura dei ruoli del modello

const viewer = document.getElementById('viewer');
const sendBtn = document.getElementById('send-btn');

let isValid = false;
const recipientRoles = {};

viewer.addEventListener('validate', (e) => {
  isValid = e.detail.valid;
  sendBtn.disabled = !isValid;
});

viewer.addEventListener('update', (e) => {
  const roles = e.detail.template.roles;
  roles.forEach((role) => {
    recipientRoles[role.signerIndex] = role.id;
  });
});

Il roleId dall’evento update collega ogni destinatario ai suoi campi nel modello. Includilo quando il flusso di invio richiede tale mappatura.

3. Inviare il documento

Quando l’utente clicca invia, chiama la mutation send con i dati dei destinatari e gli ID dei ruoli raccolti dal visualizzatore:

sendBtn.addEventListener('click', async () => {
  const token = '<token-from-authentication-guide>';

  const recipients = [
    {
      firstName: 'Jane',
      lastName: 'Smith',
      email: 'jane@example.com',
      role: 'Signer',
      roleId: recipientRoles[1],
      signerIndex: 1,
      order: 1,
    },
    {
      firstName: 'John',
      lastName: 'Doe',
      email: 'john@example.com',
      role: 'Signer',
      roleId: recipientRoles[2],
      signerIndex: 2,
      order: 2,
    },
  ];

  const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      Authorization: `Bearer ${token}`,
    },
    body: JSON.stringify({
      query: `mutation SendDocument {
        send(input: {
          groupId: "YOUR_GROUP_ID"
          templateId: "dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
          title: "Contract - Jane Smith & John Doe"
          recipients: ${JSON.stringify(recipients).replace(/"(\w+)":/g, '$1:')}
          sequentialSigning: true
        })
      }`,
    }),
  });

  const result = await response.json();
  const taskId = result.data.send;

  // Poll for completion
  console.log('Task started:', taskId);
});

La mutation send restituisce un ID di task. Interroga la query task e monitora task.report.status finché non raggiunge COMPLETED o FAILED per confermare il completamento della creazione del documento.

Modalità Editor — Creazione del Modello

La modalità editor offre agli utenti un’esperienza completa di modifica del modello — aggiunta di ruoli, posizionamento di campi, configurazione opzioni. Usala quando vuoi che gli utenti costruiscano modelli riutilizzabili.

<ls-document-viewer
  id="editor"
  templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
  token="YOUR_ACCESS_TOKEN"
  mode="editor"
></ls-document-viewer>

In modalità editor, l’evento update viene emesso ogni volta che il modello cambia. Puoi usarlo per monitorare lo stato del modello o mostrare un indicatore di salvataggio:

const editor = document.getElementById('editor');

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

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

Le modifiche al modello vengono salvate automaticamente dal visualizzatore — non serve chiamare nessuna mutation GraphQL per persistere le modifiche.

Integrazione React

Il wrapper React fornisce la stessa funzionalità con gestione eventi in stile React:

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

const DocumentCompose = ({ templateId, recipients, token }) => {
  const [isValid, setIsValid] = useState(false);
  const [roleMap, setRoleMap] = useState({});

  const handleValidate = (e) => {
    setIsValid(e.detail.valid);
  };

  const handleUpdate = (e) => {
    const roles = e.detail.template.roles;
    const map = {};
    roles.forEach((role) => {
      map[role.signerIndex] = role.id;
    });
    setRoleMap(map);
  };

  const handleSend = async () => {
    const mappedRecipients = recipients.map((r, i) => ({
      ...r,
      roleId: roleMap[r.signerIndex],
      order: i + 1,
    }));

    const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        Authorization: `Bearer ${token}`,
      },
      body: JSON.stringify({
        query: `mutation SendDocument {
          send(input: {
            groupId: "YOUR_GROUP_ID"
            templateId: "${templateId}"
            title: "Document"
            recipients: ${JSON.stringify(mappedRecipients).replace(/"(\w+)":/g, '$1:')}
          })
        }`,
      }),
    });

    const result = await response.json();
    console.log('Task ID:', result.data.send);
  };

  if (!token) return null;

  return (
    <LsDocumentViewer
      templateid={templateId}
      token={token}
      mode="compose"
      recipients={JSON.stringify(recipients)}
      onValidate={handleValidate}
      onUpdate={handleUpdate}
    >
      <div slot="right-button">
        <button onClick={handleSend} disabled={!isValid}>
          Send
        </button>
      </div>
    </LsDocumentViewer>
  );
};

Testimoni

Per aggiungere un testimone per un firmatario, imposta roleType: "WITNESS" e usa un signerIndex pari all’indice del firmatario padre + 100. Per esempio, un testimone per il firmatario 2 avrà signerIndex: 102:

<ls-document-viewer
  mode="compose"
  recipients='[
    {"email": "signer@example.com", "firstname": "Alice", "lastname": "Jones", "signerIndex": 1},
    {"email": "signer2@example.com", "firstname": "Bob", "lastname": "Brown", "signerIndex": 2},
    {"email": "witness@example.com", "firstname": "Carol", "lastname": "White", "signerIndex": 102, "roleType": "WITNESS"}
  ]'
  ...
></ls-document-viewer>

Concetti Chiave

Concetto del visualizzatore	Tipo GraphQL	Descrizione
attributo `templateid`	`Template`	Il modello in modifica o composizione
attributo `recipients`	`RecipientInput`	Destinatari passati alla modalità composizione
`roleId` dall’evento `update`	`Role`	Collega un destinatario ai propri campi nel modello
evento `validate`	—	Se il modello ha tutti i campi obbligatori
mutation `send`	`send`	Invia il documento dopo la composizione
attributo `token`	—	Token da autenticazione
`mode="compose"`	—	Modalità semplificata per posizionare campi e inviare
`mode="editor"`	—	Modalità completa di modifica del modello
`experience` nell’input di invio	`Experience`	Controlla brand, email e pagina di firma — vedi Spiegazione delle Esperienze

Riferimento Visualizzatore di Documenti — riferimento completo a attributi ed eventi
Mutation send — inviare un documento
DocumentSendSettingsInput — struttura completa dell’input di invio
Spiegazione dei metodi di invio — send vs sendBatch vs sendBulk
Caricare un File come Modello — caricare modelli tramite API
Autenticazione — scegliere una modalità di autenticazione

Panoramica​

Autenticazione​

Modalità Composizione — Inviare un Documento Predefinito​

1. Visualizzare il visualizzatore​

2. Monitorare la validazione e gli ID dei ruoli​

3. Inviare il documento​

Modalità Editor — Creazione del Modello​

Integrazione React​

Testimoni​

Concetti Chiave​

Correlati​

Export This Article