Intégrer le Visionneur de Documents

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

Présentation

Une intégration typique suit ces étapes :

Authentifier — obtenir un jeton pour le visionneur
Uploader un modèle — via l’API GraphQL
Afficher le visionneur — transmettre l’ID du modèle et le jeton
Capturer les événements — le visionneur émet des événements update et validate pendant que l'utilisateur travaille
Envoyer le document — appeler la mutation send avec les données des destinataires et rôles du visionneur

Authentification

Le visionneur nécessite un jeton valide passé à son attribut token. Votre backend peut fournir soit un JWT SRP, soit un jeton de composant à courte durée provenant de generateComponentToken. Voir Autorisation des widgets avant de connecter le visionneur à votre application.

Mode Compose — Envoyer un Document Pré-construit

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

1. Afficher le visionneur

<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 ID de rôle

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

validate — vous indique si le modèle contient tous les champs requis (au minimum, une signature par destinataire)
update — fournit l’état actuel du modèle, incluant le roleId pour chaque participant lorsqu’il faut gérer le mapping des rôles du 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 relie chaque destinataire à ses champs sur le modèle. Incluez-le lorsque votre flux d’envoi nécessite ce mapping.

3. Envoyer le document

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

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 retourne un ID de tâche. Interrogez la requête task et surveillez 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èle

Le mode Éditeur offre aux utilisateurs une expérience complète d’édition de modèle — ajouter des rôles, placer des champs, configurer 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 se déclenche à 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 sauvegardées automatiquement par le visionneur — vous n’avez pas besoin d’appeler une mutation GraphQL pour enregistrer les modifications.

Intégration React

Le wrapper React fournit la même fonctionnalité avec une gestion d’événements de style 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 parent + 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 visionneur	Type GraphQL	Description
attribut `templateid`	`Template`	Le modèle en cours d’édition ou de composition
attribut `recipients`	`RecipientInput`	Destinataires passés en mode compose
`roleId` issu de l’événement `update`	`Role`	Relie un destinataire à ses champs sur le modèle
événement `validate`	—	Si le modèle contient tous les champs requis
mutation `send`	`send`	Envoie le document après composition
attribut `token`	—	Jeton issu 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’entrée send	`Experience`	Contrôle la marque, les emails, et la page de signature — voir Explications sur les expériences

Référence du Visionneur de Documents — référence complète des attributs et événements
mutation send — envoyer un document
DocumentSendSettingsInput — structure complète des entrées envoyer
Explications sur les méthodes d’envoi — envoyer vs sendBatch vs sendBulk
Uploader un fichier en tant que modèle — uploader des modèles via l’API
Authentification — choisir un mode d’authentification

Présentation​

Authentification​

Mode Compose — Envoyer un Document Pré-construit​

1. Afficher le visionneur​

2. Suivre la validation et les ID de rôle​

3. Envoyer le document​

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

Intégration React​

Témoins​

Concepts Clés​

Liens connexes​

Export This Article