Intégrez le Visualiseur de Documents Legalesign à Votre Site Web

astuce

Vous pouvez voir ce composant en action sous le nom de Quick Send dans la Console.

Le Visualiseur 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 prêt à l'emploi est conçu pour que vous puissiez intégrer les 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 prendre en charge des composants HTML, vous pouvez utiliser le Visualiseur de Documents.

Si vous avez besoin d’aide supplémentaire pour intégrer le Visualiseur de Documents dans votre stack technique, veuillez contacter notre support.

Vous pouvez utiliser ces widgets plus avancés avec des intégrations API REST/GraphQL pour offrir des processus de signature de documents fluides à votre personnel et vos 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 de base

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 lier le composant directement depuis npm si votre environnement ne permet pas son installation. Vous pouvez essayer une page de démonstration depuis le dépôt d’exemple 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 jeton

Vous devrez utiliser du code côté serveur pour obtenir YOUR_AUTH_TOKEN. Il y a trois options :

SRP JWT directement — Si votre backend utilise déjà l’authentification SRP, transmettez le jeton d’accès JWT directement au widget.
GraphQL generateComponentToken — Appelez la mutation avec votre clé API ou le JWT SRP pour générer un jeton de composant à courte durée de vie et limité.
API REST — Appelez GET /templatepdf/{pdfId}/component-token/ avec votre clé API.

Option 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;

Option 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();

Transmettez le token retourné (ou votre JWT SRP) au widget. Voir Autorisation du widget pour plus de détails sur les options de jeton.

Intégration React

Nous avons aussi généré une version du composant qui s’intègre directement aux 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 jeton de sécurité pour l’authentification. Il peut être soit un jeton d’accès SRP JWT, soit un jeton de composant à courte durée de vie issu de generateComponentToken. Voir Autorisation du widget pour le flux sécurisé de jetons.

token="eyJraWQiOiJBTkJIeT..."

templateid

L’ID API du modèle que vous souhaitez présenter aux utilisateurs. Vous pouvez le trouver dans l’URL lorsque vous éditez le modèle dans l’application Web.

templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"

Mode Éditeur

Création et édition complètes de modèles avec tous les outils disponibles. Ce mode est destiné aux flux de travail où un modèle hautement réutilisable avec des 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 de documents a déjà rempli toutes les informations client), vous souhaitez peut-être considérer le mode compose à la place.

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

Mode Compose

Ce mode est une méthode "récepteur en premier" 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 pourra rapidement placer leurs 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 flux de travail typique est de cloner ou télécharger un PDF, puis d’intégrer le visualiseur où l’utilisateur peut ajouter des champs de signature et de formulaire, puis 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 Télécharger

Créez un modèle puis téléchargez-le à l’URL uploadUrl fournie. Utilisez le titre [deleted] si vous ne voulez pas que le pdf figure dans votre bibliothèque. Il sera supprimé sous 24 heures. Sinon, utilisez n’importe quel 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, envoyez en PUT votre fichier à l’uploadUrl. Le type de contenu doit être application/pdf.

Intégrer le visualiseur

L’attribut principal est 'recipients'. Vous aurez besoin de détails supplémentaires pour les approbateurs ou témoins – pour plus d’informations, voir Destinataires.

<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 fait automatiquement :

La détection des destinataires pré-générés
Cache l’expéditeur dans le menu déroulant
Cache les options du document
Affiche par défaut les champs requis
Supprime l’expéditeur et les champs de l’expéditeur dans l’éditeur
Favorise la sélection rapide des champs requis pour chaque destinataire

Mode Aperçu

Un aperçu 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 Aperçu fait 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

Filtre de la boîte à outils

Limitez les types de champs disponibles en utilisant des valeurs délimitées par des pipes. Si aucune valeur n’est fournie, on suppose que la boîte à outils ne sera pas filtrée et que toutes les options sont 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 de signature automatique (expéditeur uniquement)
`text`	Saisie de texte libre
`signing date`	Date remplie automatiquement à la signature (signataire uniquement)
`date`	Sélecteur de date
`email`	Saisie d’email
`initials`	Champ d’initiales
`number`	Saisie numérique
`dropdown`	Liste déroulante
`checkbox`	Case à cocher
`regex`	Saisie validée par expression régulière (signataire uniquement)
`image`	Téléversement d’image (signataire uniquement)
`file`	Téléversement 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 transmettre le rôle et le numéro de téléphone pour chaque destinataire. L’absence d’un rôle signifie que le destinataire sera traité comme signataire.

Vous pouvez attribuer 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), alors le témoin aura 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>

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 vérifier 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 en React

En React, un événement est préfixé par l’habituel on<EventName>.

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

Types d’événements

Événement `update`

Déclenché lorsque le modèle de document est modifié, comme l’ajout ou la suppression de champs. Fournit non seulement l’événement qui l’a déclenché, 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 change, la propriété valid dans les détails 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>

Vous pouvez utiliser la mutation send GraphQL côté client si vous utilisez le jeton SRP JWT, sinon côté serveur avec votre clé API via l’interface GraphQL ou REST.

Mutation Send — envoyer un document unique
Schéma d’entrée Send — référence complète des entrées
Envoi REST - référence d’envoi de document REST

Dépannage

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 des documents sur https://s3.amazonaws.com/*

Support Navigateur

Le composant utilise des standards web modernes et supporte :

Chrome/Edge (dernière version)
Firefox (dernière version)
Safari (dernière version)
Navigateurs mobiles (iOS Safari, Chrome Mobile)

Ressources

Guide d’intégration GraphQL — comment connecter le visualiseur à l’API GraphQL pour l’envoi
Documentation API GraphQL
Package NPM
Package React
Support

Obtenir de l’aide

Pour le support technique ou des questions d’intégration, contactez l’équipe de support Legalesign ou consultez la documentation API.

Intégrez le Visualiseur de Documents Legalesign à Votre Site Web

Installation

Installation NPM

Pour les projets React

Intégration de base

HTML/JavaScript

Authentification - Obtenir un jeton

Intégration React

Attributs requis

token

templateid

Modes du widget

Mode Éditeur

Mode Compose

Cloner

Ou Télécharger

Intégrer le visualiseur

Mode Aperçu

Configuration avancée

Filtre de la boîte à outils

Destinataires

Boutons personnalisés avec Slots

Gestion des événements

Exemple de gestion d’événements en React

Types d’événements

Événement `update`

Événement `validate`

Événement `selectFields`

Événement `addParticipant`

Exemple complet

Dépannage

Support Navigateur

Ressources

Obtenir de l’aide

Export This Article

Installation​

Installation NPM​

Pour les projets React​

Intégration de base​

HTML/JavaScript​

Authentification - Obtenir un jeton​

Intégration React​

Attributs requis​

token​

templateid​

Modes du widget​

Mode Éditeur​

Mode Compose​

Cloner​

Ou Télécharger​

Intégrer le visualiseur​

Mode Aperçu​

Configuration avancée​

Filtre de la boîte à outils​

Destinataires​

Boutons personnalisés avec Slots​

Gestion des événements​

Exemple de gestion d’événements en React​

Types d’événements​

Événement update​

Événement validate​

Événement selectFields​

Événement addParticipant​

Exemple complet​

Dépannage

Support Navigateur​

Ressources​

Obtenir de l’aide​

Export This Article

Installation

Installation NPM

Pour les projets React

Intégration de base

HTML/JavaScript

Authentification - Obtenir un jeton

Intégration React

Attributs requis

token

templateid

Modes du widget

Mode Éditeur

Mode Compose

Cloner

Ou Télécharger

Intégrer le visualiseur

Mode Aperçu

Configuration avancée

Filtre de la boîte à outils

Destinataires

Boutons personnalisés avec Slots

Gestion des événements

Exemple de gestion d’événements en React

Types d’événements

Événement `update`

Événement `validate`

Événement `selectFields`

Événement `addParticipant`

Exemple complet

Support Navigateur

Ressources

Obtenir de l’aide