Aller au contenu principal

Intégrer le Visualiseur de Documents

Le Visualiseur de Documents est un composant web qui permet aux utilisateurs de modifier des modèles et de préparer des documents pour la signature — directement dans votre application. Ce guide montre comment le connecter à l’API GraphQL pour construire un flux de travail de signature complet.

Vue d’ensemble​

Une intégration typique suit ces étapes :

  1. S’authentifier — obtenir un jeton pour le visualiseur
  2. Télécharger un modèle — via l’API GraphQL
  3. Afficher le visualiseur — passer l’ID du modèle et le jeton
  4. Capturer les événements — le visualiseur émet les événements update et validate pendant que l’utilisateur travaille
  5. Envoyer le document — appeler la mutation send avec les données des destinataires et des rôles issues du visualiseur

Authentification​

Le visualiseur nécessite un jeton valide passé via son attribut token. Votre backend fournit un jeton de composant à courte durée via generateComponentToken. Consultez Autorisation des Widgets avant de connecter le visualiseur à votre application.

Mode Composition — Envoyer un Document Pré-construit​

Le mode composition est destiné aux flux de travail où votre système connaît déjà les destinataires. L’utilisateur place simplement les champs de signature et envoie.

1. Afficher le visualiseur​

<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. Suivre la validation et les IDs de rôle​

Lorsque l’utilisateur ajoute des champs, le visualiseur émet des événements. Vous avez besoin de deux informations issues de ces événements :

  • validate — indique si le modèle contient tous les champs obligatoires (au minimum, une signature par destinataire)
  • update — fournit l’état actuel du modèle, incluant le roleId pour chaque participant lorsque vous avez besoin d’un mappage des rôles modèle
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;
});
});

Le roleId issu de l’événement update associe chaque destinataire à ses champs sur le modèle. Incluez-le lorsque votre flux d’envoi nécessite ce mappage.

3. Envoyer le document​

Quand l’utilisateur clique sur envoyer, appelez la mutation send avec les données des destinataires et les IDs de rôle capturés depuis le visualiseur :

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 renvoie un ID de tâche. Interrogez la requête task et suivez le champ task.report.status jusqu’à ce qu’il atteigne COMPLETED ou FAILED pour confirmer que la création du document est terminée.

Mode Éditeur — Création de Modèles​

Le mode éditeur offre aux utilisateurs l’expérience complète de modification de modèle — ajout des rôles, placement des champs, configuration des options. Utilisez-le lorsque vous souhaitez que les utilisateurs créent des modèles réutilisables.

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

En mode éditeur, l’événement update est déclenché à chaque modification du modèle. Vous pouvez l’utiliser pour suivre l’état du modèle ou afficher un indicateur de sauvegarde :

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);
});

Les modifications du modèle sont enregistrées automatiquement par le visualiseur — vous n’avez pas besoin d’appeler une mutation GraphQL pour sauvegarder les modifications.

Intégration React​

Le wrapper React fournit la même fonctionnalité avec une gestion des événements à la manière de 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>
);
};

Témoins​

Pour ajouter un témoin pour un signataire, définissez roleType: "WITNESS" et utilisez un signerIndex égal à l’index du signataire principal + 100. Par exemple, un témoin pour le signataire 2 aura 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>

Concepts Clés​

Concept du visualiseurType GraphQLDescription
attribut templateidTemplateLe modèle en cours d’édition ou de composition
attribut recipientsRecipientInputDestinataires passés au mode composition
roleId issu de l’événement updateRoleLie un destinataire à ses champs sur le modèle
événement validate—Indique si le modèle comporte tous les champs requis
mutation sendsendEnvoie le document après composition
attribut token—Jeton provenant de l’authentification
mode="compose"—Mode simplifié pour placer les champs et envoyer
mode="editor"—Mode complet d’édition de modèle
experience dans l’input sendExperienceContrôle la marque, les emails et la page de signature — voir Explications sur les expériences