Intégrez le Visionneur de Documents Legalesign à votre Site Web
Vous pouvez voir ce composant en action sous le nom de Quick Send dans Console.
Version actuelle : v1.0.27 — changelog
Le Visionneur de Documents Legalesign est un composant web indépendant de la plateforme qui vous permet d’éditer, prévisualiser et personnaliser des modèles pour la signature de documents. Il fonctionne parfaitement en HTML avec JavaScript, React, Vue, Angular ou tout autre framework web.
Ce composant plug and play est conçu pour que vous puissiez intégrer des parties clés de la création de documents dans vos systèmes internes, tels qu’un CRM ou une application métier.
Tant que votre système peut afficher et supporter des composants HTML, vous pouvez utiliser le Visionneur de Documents.
Si vous avez besoin d’aide supplémentaire pour intégrer le Visionneur de Documents dans votre stack technique, veuillez contacter notre support.
Vous pouvez utiliser ces widgets de grande taille avec des intégrations API REST/GraphQL pour offrir des processus de signature de documents sans couture à vos employés et clients.
Installation
Installation NPM
npm install legalesign-document-viewer
# or
pnpm add legalesign-document-viewer
Pour les projets React
npm install legalesign-document-viewer-react
# or
pnpm add legalesign-document-viewer-react
Intégration Basique
HTML/JavaScript
La version HTML/JavaScript de ce composant peut être utilisée avec n’importe quelle stack de développement, comme PHP, ASP .Net, etc. Vous pouvez linker directement vers le composant depuis npm si votre environnement ne permet pas son installation. Vous pouvez essayer une page de démonstration à partir du dépôt d’exemples ici [https://github.com/legalesign/ls-viewer-demo].
Ajoutez les scripts du composant à votre 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>
Authentification - Obtenir un token
Vous devrez utiliser du code côté serveur pour obtenir YOUR_AUTH_TOKEN. Deux options existent, les deux utilisant votre clé API :
- GraphQL
generateComponentToken— Appelez la mutation avec votre clé API pour générer un token de composant à durée limitée et avec scope. - API REST — Appelez
GET /templatepdf/{pdfId}/component-token/avec votre clé API.
Option 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;
Option 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();
Passez le token retourné au widget. Voir Widget Authorization pour plus de détails sur les options de token.
Intégration React
Nous avons également créé une version du composant qui s’intègre directement avec les frameworks React.
import { LsDocumentViewer } from 'legalesign-document-viewer-react';
function App() {
return (
<LsDocumentViewer
templateid="YOUR_TEMPLATE_ID"
token="YOUR_AUTH_TOKEN"
mode="compose"
/>
);
}
Attributs Requis
token
Votre token de sécurité pour l’authentification : un token de composant à courte durée de vie issu de generateComponentToken ou de l’endpoint REST component-token. Voir Widget Authorization pour le flux sécurisé des tokens.
token="eyJraWQiOiJBTkJIeT..."
templateid
L’ID API du modèle que vous souhaitez présenter aux utilisateurs. Vous pouvez le trouver dans l’URL quand vous modifiez le modèle dans l’application web.
templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
Modes du Widget
Mode Éditeur
Création et édition complète de modèles avec tous les outils disponibles. Ce mode est destiné aux workflows où un modèle réutilisable avec rôles est utile. Si votre intention est d’utiliser votre document une seule fois (peut-être que votre système de génération a déjà rempli toutes les informations client), vous pouvez préférer le mode compose.
<ls-document-viewer mode="editor" ...></ls-document-viewer>
Mode Compose
Ce mode est une méthode "recipient-first" pour simplifier l’expérience utilisateur. Dans l’application web Legalesign c’est la fonction "Quick send".
Ajoutez vos destinataires à l’attribut ‘recipient’ et votre utilisateur peut rapidement placer ses signatures et champs de formulaire avant d’envoyer. Idéal pour les clients intégrés où les destinataires sont déjà définis.
Le workflow typique est de cloner ou uploader un PDF, puis d’intégrer le visionneur où l’utilisateur peut ajouter des champs de signature et de formulaire, et proposer un bouton pour envoyer le document.
Cloner
Clonez un modèle existant en utilisant 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;
Ou Uploader
Créez un modèle puis uploadez-le à l’uploadUrl fourni. Utilisez le titre [deleted] si vous ne voulez pas que le pdf soit dans votre bibliothèque. Il sera supprimé dans les 24 heures suivantes. Sinon, utilisez le titre de votre choix :
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;
Maintenant PUTtez votre fichier à l’uploadUrl. Le type de contenu doit être application/pdf.
Intégrer le visionneur
L’attribut principal est ‘recipients’. Vous aurez besoin de détails supplémentaires pour les approbateurs ou témoins – pour plus d’informations voir Recipients.
<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>
Le mode Compose effectue automatiquement :
- La détection des destinataires pré-générés
- Masque l’expéditeur dans le menu déroulant
- Cache les options du document
- Affiche par défaut les champs obligatoires
- Supprime l’expéditeur et les champs d’expéditeur dans l’éditeur
- Favorise la sélection rapide des champs requis pour chaque destinataire
Mode Prévisualisation
Une prévisualisation utile du document qui montre le document avec tous les champs actuels et permet à l’utilisateur de parcourir les pages.
<ls-document-viewer mode="preview" ...></ls-document-viewer>
Le mode Prévisualisation effectue automatiquement :
- Cache la barre d’outils
- Cache les options du document
- Cache la boîte à outils
- Rend les participants et champs en lecture seule
Configuration Avancée
Filtrer la Boîte à Outils
Restreignez les types de champs disponibles en utilisant des valeurs séparées par des pipes. Si aucune valeur n’est fournie, il est supposé que la boîte à outils ne sera pas filtrée et toutes les options seront disponibles.
<ls-document-viewer
filtertoolbox="signature|initials|date|text"
...
></ls-document-viewer>
Valeurs de filtre disponibles :
| Valeur | Description |
|---|---|
signature | Champ de signature (signataire uniquement) |
auto sign | Champ d’auto-signature (expéditeur uniquement) |
text | Saisie de texte libre |
signing date | Date auto-remplie au moment de la signature (signataire uniquement) |
date | Sélecteur de date |
email | Saisie d’email |
initials | Champ d’initiales |
number | Saisie numérique |
dropdown | Sélecteur déroulant |
checkbox | Case à cocher |
regex | Saisie validée par regex (signataire uniquement) |
image | Téléchargement d’image (signataire uniquement) |
file | Téléchargement de fichier (signataire uniquement) |
drawn | Champ dessiné/libre (signataire uniquement) |
Destinataires
Définissez les destinataires du document au format JSON.
Les éléments requis pour chaque destinataire sont firstname, lastname, email et signerIndex ;
Optionnellement, vous pouvez passer le rôle et le numéro de téléphone pour chaque destinataire. Omettre un rôle signifie que le destinataire sera traité comme un signataire.
Vous pouvez passer le rôle "WITNESS" ou "APPROVER". Pour le rôle "WITNESS" ajoutez 100 au numéro signerIndex de leur signataire. Par exemple, si vous avez besoin d’un témoin pour le signataire 2 (signerIndex : 2), faites signerIndex du TÉMOIN : 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>
Boutons Personnalisés avec Slots
Ajoutez des boutons personnalisés à la barre d’outils en utilisant des slots. Vous les utiliserez probablement pour annuler l’action ou envoyer le document.
<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>
Gestion des Événements
Écoutez les événements du composant pour suivre les changements :
const editor = document.querySelector('ls-document-viewer');
editor.addEventListener('update', (event) => {
console.log('Template changed:', event.detail);
});
Vous pouvez suivre si un modèle est devenu valide ou invalide en utilisant l’événement validate.
const editor = document.querySelector('ls-document-viewer');
editor.addEventListener('validate', (event) => {
console.log('Template validation changed:', event.detail.valid);
});
Exemple de gestion d’événements React
L’utilisation d’un événement en React le préfixe avec le familier on<EventName>.
<LsDocumentViewer
onUpdate={(event) => {
console.log('Template changed:', event.detail);
}}
...
/>
Types d’événements
Événement update
Déclenché quand le modèle de document est modifié, comme l’ajout ou la suppression de champs. Fournit non seulement l’événement qui l’a causé mais aussi l’état mis à jour de l’objet modèle au format JSON.
Événement validate
Déclenché lorsque le modèle de document est modifié, la propriété valid dans le détail indique si le
modèle est devenu valide ou invalide.
Événement selectFields
Déclenché lorsqu’un champ est sélectionné dans l’éditeur.
Événement addParticipant
Déclenché lorsqu’un rôle de participant est ajouté au modèle.
Exemple Complet
<!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>
Envoyez le document côté serveur en utilisant votre clé API, avec l’interface GraphQL ou REST.
- Send mutation — envoyer un document unique
- Send Input Schema — référence complète des inputs
- REST Send - référence REST pour envoyer un document
Résolution de Problèmes
Si vous rencontrez des problèmes avec le composant, assurez-vous que :
- vous pouvez accéder ou avez mis en liste blanche le domaine de stockage de documents à https://s3.amazonaws.com/*
Support des Navigateurs
Le composant utilise les standards web modernes et supporte :
- Chrome/Edge (dernières versions)
- Firefox (dernières versions)
- Safari (dernières versions)
- Navigateurs mobiles (iOS Safari, Chrome Mobile)
Changelog
| Version | Date | Résumé |
|---|---|---|
| v1.0.27 | 19 Oct 2026 | Améliorations de positionnement des champs |
| v1.0.26 | 3 Sep 2026 | Corrections de scroll ; rendu différé au chargement |
| v1.0.21 | 12 Août 2026 | Options du mode preview ; améliorations événement update |
| v1.0.18 | 17 Juil 2026 | Panneau de champ regex ; propriétés avancées multi-champs ; améliorations des dropdowns ; renommage des témoins |
| v1.0.12 | 10 Juil 2026 | Propriété de champ excludeFromPdf |
| v1.0.9 | 9 Juil 2026 | Champs auto date et regex ; propriétés avancées ; ordre des champs |
| v1.0.6 | 2 Juil 2026 | Correction de police empêchant les échecs de signature ; marges preview |
| v1.0.5 | 29 Juin 2026 | Raccourcis clavier annuler/refaire |
| v1.0.4 | 26 Juin 2026 | Améliorations d’événements ; mises à jour optimistes ; annuler/refaire |
| v1.0.0 | 24 Juin 2026 | Première version stable |
Ressources
- Guide d’Intégration GraphQL — comment connecter le visionneur à l’API GraphQL pour l’envoi
- Documentation API GraphQL
- Package NPM
- Package React
- Support
Obtenir de l’Aide
Pour un support technique ou des questions sur l’intégration, contactez l’équipe support Legalesign ou consultez la documentation API.