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 connetterlo all'API GraphQL per costruire un flusso di lavoro completo per la 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 eventi
updateevalidatementre l'utente lavora - Inviare il documento — chiamare la mutazione
sendcon i dati del destinatario e del ruolo provenienti dal visualizzatore
Autenticazione
Il visualizzatore necessita di un token valido passato all'attributo token. Il tuo backend fornisce un token a breve durata dal generateComponentToken. Consulta Autorizzazione del Widget prima di collegare il visualizzatore alla tua applicazione.
Modalità Composizione — Inviare un Documento Pre-costruito
La modalità composizione è per flussi di lavoro in cui il tuo sistema conosce già i destinatari. L'utente si limita a posizionare i campi firma e inviare.
1. Visualizza 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. Traccia la validazione e gli ID ruolo
Mentre l'utente aggiunge campi, il visualizzatore emette eventi. Da questi eventi ti servono due informazioni:
validate— indica se il modello contiene tutti i campi richiesti (almeno una firma per destinatario)update— fornisce lo stato corrente del modello, incluso ilroleIdper ogni partecipante quando ti serve il mapping 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 propri campi nel modello. Includilo quando il flusso di invio ne ha bisogno.
3. Invia il documento
Quando l'utente clicca invia, chiama la mutazione send con i dati dei destinatari e gli ID ruolo catturati 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 mutazione send restituisce un ID attività (task ID). Invoca periodicamente la query task e monitora task.report.status finché non raggiunge COMPLETED o FAILED per confermare che la creazione del documento è terminata.
Modalità Editor — Creazione del Modello
La modalità editor offre agli utenti un'esperienza completa di modifica del modello — aggiungendo ruoli, posizionando campi, configurando 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 si attiva ogni volta che il modello cambia. Puoi usarlo per tracciare 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 devi chiamare alcuna mutazione GraphQL per salvare le modifiche.
Integrazione React
Il wrapper React offre 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 principale + 100. Per esempio, un testimone per il firmatario 2 ha 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 che viene modificato o composto |
attributo recipients | RecipientInput | Destinatari passati alla modalità composizione |
roleId dall'evento update | Role | Collega un destinatario ai suoi campi nel modello |
evento validate | — | Indica se il modello ha tutti i campi richiesti |
mutazione 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 branding, email e pagina di firma — vedi Esperienze spiegate |
Correlati
- Riferimento Visualizzatore di Documenti — riferimento completo di attributi ed eventi
- mutazione send — invia un documento
- DocumentSendSettingsInput — struttura completa dell'input di invio
- Metodi di invio spiegati — send vs sendBatch vs sendBulk
- Caricare un File come Modello — caricare modelli tramite API
- Autenticazione — scegliere una modalità di autenticazione