Intégrer Legalesign Signer dans votre site web

Activer pour votre équipe

Le composant Signer nécessite une activation. Contactez le support pour l’activer pour votre équipe.

Le Legalesign Signer est un composant web indépendant de la plateforme qui offre une expérience complète et fluide de signature de document directement depuis votre propre application. Il fonctionne avec du HTML pur, React, Vue, Angular ou tout autre framework web.

Intégrez ce composant partout où vos utilisateurs ont besoin de signer des documents — dans un CRM, un portail client ou toute application interne qui rend du HTML.

Installation

Chargez-le directement depuis le CDN (aucune installation requise) :

<script type="module" src="https://cdn.legalesign.io/signer/latest/ls-signer.esm.js"></script>

Installation React

Installer via un gestionnaire de paquets :

npm install legalesign-signer
# or
pnpm add legalesign-signer

Intégration de base

HTML & JavaScript

<ls-signer
  recipient-id="abc123"
  private-key="key"
  session-id="session"
></ls-signer>

<script>
  const signer = document.querySelector('ls-signer');
  signer.addEventListener('signingSuccess', (e) => console.log('Signed:', e.detail.eventType, e.detail.documentId));
  signer.addEventListener('signingFail', (e) => console.error('Failed:', e.detail.failureReason, e.detail.error));
  signer.addEventListener('fieldChange', (e) => console.log('Field event:', e.detail.eventType));
</script>

React

import { useEffect, useState } from 'react';
import { LsSigner } from 'legalesign-signer/react';
import 'legalesign-signer/react.css';

function SigningPage() {
  const [signerData, setSignerData] = useState(null);

  useEffect(() => {
    fetch('/your-backend/to-get-token')
      .then(res => res.json())
      .then(setSignerData);
  }, []);

  if (!signerData) return <p>Loading...</p>;

  return (
    <LsSigner
      recipientId={signerData.recipientId}
      privateKey={signerData.token}
      sessionId={signerData.sessionId}
      onSuccess={({ eventType, documentId }) => console.log(eventType, documentId)}
      onFail={({ eventType, failureReason, error }) => console.error(eventType, failureReason, error)}
      onChange={({ eventType, uuid, saved, field, document }) => console.log('Event:', eventType)}
    />
  );
}

React nécessite react et react-dom (v18 ou v19) en dépendances peer.

Vue

<template>
  <ls-signer
    ref="signer"
    :recipient-id="recipientId"
    :private-key="privateKey"
    :session-id="sessionId"
  />
</template>

<script setup>
import { ref, onMounted, onBeforeUnmount } from 'vue';

const signer = ref(null);

function handleSuccess(e) {
  console.log('Signed:', e.detail);
}
function handleFail(e) {
  console.error('Failed:', e.detail);
}

onMounted(() => {
  signer.value.addEventListener('signingSuccess', handleSuccess);
  signer.value.addEventListener('signingFail', handleFail);
});

onBeforeUnmount(() => {
  signer.value?.removeEventListener('signingSuccess', handleSuccess);
  signer.value?.removeEventListener('signingFail', handleFail);
});
</script>

astuce

Si vous utilisez Vue avec Vite, ajoutez isCustomElement: (tag) => tag.startsWith('ls-') à la configuration de votre plugin Vue pour supprimer les avertissements d’éléments inconnus.

attention

Vue 3 met en minuscules les noms d’événements sur les éléments personnalisés, donc @signingSuccess ne fonctionnera pas. Utilisez addEventListener sur la référence à l’élément comme montré ci-dessus.

Nuxt 3

Encapsulez <ls-signer> dans <ClientOnly> pour éviter les erreurs SSR. Ajoutez la configuration de l’élément personnalisé dans nuxt.config.ts :

export default defineNuxtConfig({
  vue: {
    compilerOptions: {
      isCustomElement: (tag) => tag.startsWith('ls-'),
    },
  },
});

Authentification

Le composant signer nécessite un jeton court terme depuis votre backend. Deux options s’offrent à vous :

1. GraphQL generateComponentToken — Appelez avec component: LS_SIGNER et soit un recipientId soit un sessionId dans la portée signer (fournir l’un, pas les deux).
2. API REST — Appelez GET /signer/{signerId}/component-token/ avec votre clé API.

Les deux renvoient le token et le sessionId nécessaires au composant. Voir Widget Authorization pour le flux complet côté serveur.

Option 1 : GraphQL (Node.js)

Utilisation de recipientId (le plus courant — à utiliser lorsque vous connaissez le destinataire mais pas encore la session) :

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 MintSignerToken($input: GenerateComponentTokenInput!) {
      generateComponentToken(input: $input) {
        token
        tokenType
        sessionId
        expiresIn
        expiresAt
      }
    }`,
    variables: {
      input: {
        component: 'LS_SIGNER',
        signer: { recipientId: '<recipient-id>' }
      }
    }
  })
});

const { data } = await response.json();
const { token, sessionId } = data.generateComponentToken;

Alternativement, si vous disposez déjà d’un sessionId issu d’un appel précédent :

variables: {
  input: {
    component: 'LS_SIGNER',
    signer: { sessionId: '<session-id>' }
  }
}

Option 2 : API REST

const response = await fetch(
  `https://eu-api.legalesign.com/api/v1/signer/${signerId}/component-token/`,
  {
    headers: {
      Authorization: `Bearer ${process.env.LEGALESIGN_API_KEY}`,
    },
  }
);

const { token, sessionId } = await response.json();

Passez token en tant que private-key et sessionId en tant que session-id au composant.

Attributs requis

Attribut	Type	Description
recipient-id	string	Identifiant du destinataire (base64, préfixe rec, ou UUID)
private-key	string	Jeton retourné par generateComponentToken
session-id	string	ID de session retourné par generateComponentToken

Attributs optionnels

Attribut	Type	Par défaut	Description
colour	string	blue	Nom de la couleur du thème (voir Theming)
style	string	``	Modifications de style (voir Customer CSS)
branding	boolean	true	Supprimer la marque Legalesign
language	string	—	Forcer une langue spécifique et masquer le sélecteur de langue (voir Internationalisation)

Événements

Événement du composant web	Propriété React	eventType	Quand
signingSuccess	onSuccess	"success"	Document signé avec succès
signingFail	onFail	"failure"	Signature échouée, rejetée, expirée, annulée, supprimée ou retirée
fieldChange	onChange	"ready"	Document et images entièrement chargés
fieldChange	onChange	"save"	Une valeur de champ a été sauvegardée
fieldChange	onChange	"select"	Un champ a été sélectionné ou activé

signingSuccess / onSuccess

{
  eventType: 'success';
  documentId: string;
  recipientId: string;
}

signingFail / onFail

{
  eventType: 'failure';
  failureReason: FailureReason;
  error: string;
  documentId?: string;
  recipientId: string;
}

failureReason	Cause
documentExpired	Le document est expiré ou la date d’expiration est passée
sessionExpired	L’API a renvoyé 401 ou 403
cancelled	L’état du document est "cancelled"
deleted	Le document a été supprimé
rejected	Le destinataire a rejeté le document
removed	L’API a renvoyé 404
signingError	Toute autre erreur lors du chargement ou de la signature

fieldChange / onChange

Les trois valeurs eventType partagent le même événement. Utilisez eventType pour différencier :

// eventType: 'ready' — document fully loaded
{ eventType: 'ready'; document: { documentId, name, state, recipientId, pageCount, expires?, isApprover, isWitness, canReassign, doOfferReject } }

// eventType: 'save' — field value saved
{ eventType: 'save'; uuid: string; saved: boolean; field: Record<string, any> }

// eventType: 'select' — field selected or focused
{ eventType: 'select'; uuid: string; field: Record<string, any> }

Propriétés React

Le composant React utilise des propriétés camelCase et des callback props au lieu d’événements DOM :

Propriété	Type	Obligatoire	Description
recipientId	string	✅	Identifiant du destinataire
privateKey	string	✅	Clé privée de la mutation generateComponentToken
sessionId	string	✅	Identifiant de la session
colour	LsSignerColour	❌	Couleur du thème
branding	boolean	❌	Affiche la marque Legalesign. Par défaut true.
language	string	❌	Force une langue spécifique (voir Internationalisation)
onSuccess	(data: { eventType: 'success'; documentId: string; recipientId: string }) => void	❌	Appelé quand la signature réussit
onFail	(data: { eventType: 'failure'; failureReason: FailureReason; error: string; documentId?: string; recipientId: string }) => void	❌	Appelé en cas d’échec de la signature
onChange	(data: { eventType: 'ready' | 'save' | 'select'; document?: DocumentSummary; uuid?: string; saved?: boolean; field?: Record<string, any> }) => void	❌	Appelé sur les événements de champ et quand le document est prêt

Gestionnaire universel (debugging & prototypage)

Chaque événement inclut eventType, vous pouvez donc relier une fonction unique à tous les événements :

React :

const handleSignerEvent = (e) => {
  switch (e.eventType) {
    case 'success': console.log('Signed:', e.documentId); break;
    case 'failure': console.log('Failed:', e.failureReason, e.error); break;
    case 'ready':   console.log('Ready:', e.document?.name); break;
    case 'save':    console.log('Saved field:', e.uuid, e.saved); break;
    case 'select':  console.log('Selected field:', e.uuid); break;
  }
};

<LsSigner
  onSuccess={handleSignerEvent}
  onFail={handleSignerEvent}
  onChange={handleSignerEvent}
/>

Composant web :

const handleSignerEvent = (e) => {
  switch (e.detail.eventType) {
    case 'success': console.log('Signed:', e.detail.documentId); break;
    case 'failure': console.log('Failed:', e.detail.failureReason, e.detail.error); break;
    case 'ready':   console.log('Ready:', e.detail.document?.name); break;
    case 'save':    console.log('Saved field:', e.detail.uuid, e.detail.saved); break;
    case 'select':  console.log('Selected field:', e.detail.uuid); break;
  }
};

signer.addEventListener('signingSuccess', handleSignerEvent);
signer.addEventListener('signingFail', handleSignerEvent);
signer.addEventListener('fieldChange', handleSignerEvent);

Thématisation

Définissez un thème de couleur avec la propriété colour. Toutes les nuances sont dérivées automatiquement.

Couleurs disponibles

pink · blue · purple · indigo · teal · green · lightblue · burnt · aubergine · red · yellow · cyan · lime · trueGreen

Omettez la propriété pour la couleur bleue par défaut.

<ls-signer colour="pink" ...></ls-signer>

<LsSigner colour="pink" ... />

La propriété colour ajoute un attribut data-ls-theme à la racine du composant. Des propriétés CSS personnalisées définissent une échelle de nuances de 10 à 100 pour chaque couleur :

Nuance	Usage
10	Fonds clairs, remplissages subtils
20	Bordures subtiles
30	Anneaux de focus
60	Couleur principale (boutons, liens, états actifs)
70	État au survol
80	Accents foncés/forts

CSS personnalisé

Le composant expose des propriétés CSS personnalisées qui peuvent être redéfinies pour personnaliser l’apparence au-delà du thème de couleur. Ce jeu de propriétés est limité pour le moment, contactez-nous pour en savoir plus.

<ls-signer
  style="--ls-font-family: 'Inter', sans-serif; --ls-color-primary-60: #e91e63;"
  recipient-id="abc123"
  private-key="key"
  session-id="session"
></ls-signer>

Propriétés disponibles

Propriété	Par défaut	Description
--ls-font-family	'IBM Plex Sans', sans-serif	Police principale
--ls-color-primary-10 à --ls-color-primary-100	—	Échelle complète de la couleur principale (remplace le thème)
--ls-color-error	#f64a44	Couleur état d’erreur
--ls-color-error-light	#fff0f0	Fond d’erreur
--ls-color-success	#46dbaa	Couleur état de succès
--ls-color-success-light	#effff9	Fond de succès
--ls-color-warning	#fad232	Couleur état d’alerte
--ls-color-warning-light	#fffcef	Fond d’alerte
--ls-color-border	#d8d9dc	Couleur de bordure par défaut
--ls-color-border-subtle	#e0e2e5	Couleur de bordure subtile
--ls-color-bg-subtle	#f7f8fa	Couleur de fond subtile

Remarque : Pour une injection complète de CSS personnalisé (ciblant directement les éléments internes, en remplaçant tailles de police, rayons de bordure, espacements, etc.), il s’agit d’une fonction prévue à l’avenir. Merci de nous contacter si vous êtes intéressé.

Internationalisation

Le composant supporte 17 langues avec des traductions intégrées à la build. La langue est détectée automatiquement depuis le navigateur. Un sélecteur de langue intégré dans l’interface de signature permet au destinataire de changer de langue à tout moment.

Définissez l’attribut language pour forcer une langue spécifique. Lorsqu’elle est fournie, le sélecteur intégré est masqué et la détection navigateur est contournée.

<ls-signer language="fr" recipient-id="abc123" private-key="key" session-id="session"></ls-signer>

<LsSigner language="fr" recipientId="abc123" privateKey="key" sessionId="session" />

Ordre de priorité : propriété language → langue du navigateur → anglais par défaut.

Code	Langue	Code	Langue
en	Anglais	nl	Néerlandais
fr	Français	fi	Finnois
bg	Bulgare	it	Italien
es	Espagnol	he	Hébreu
de	Allemand	sv	Suédois
gs	Gaélique écossais	cy	Gallois
ar	Arabe	is	Islandais
el	Grec	iw	Hébreu (ancien)
pt	Portugais
ro	Roumain

Version CDN

L’URL CDN supporte à la fois latest et les numéros de version figés :

<!-- Always get the most recent version (recommended) -->
<script type="module" src="https://cdn.legalesign.io/signer/latest/ls-signer.esm.js"></script>

<!-- Pin to a specific version -->
<script type="module" src="https://cdn.legalesign.io/signer/v1.1.0/ls-signer.esm.js"></script>

Nous recommandons d’utiliser latest — cela garantit que votre intégration reçoit automatiquement corrections de bugs, correctifs de sécurité et nouvelles fonctionnalités. Utilisez une version figée si vous devez bloquer sur une version stable pendant une gelée QA ou un déploiement contrôlé. Voir l’historique complet des versions sur npm pour les versions disponibles.

Exemple complet

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Document Signing</title>
    <script type="module" src="https://cdn.legalesign.io/signer/latest/ls-signer.esm.js"></script>
  </head>
  <body>
    <ls-signer
      recipient-id="abc123"
      private-key="key"
      session-id="session"
      colour="teal"
    ></ls-signer>

    <script>
      const signer = document.querySelector('ls-signer');

      signer.addEventListener('signingSuccess', (event) => {
        console.log('Document signed:', event.detail.documentId);
        window.location.href = '/thank-you';
      });

      signer.addEventListener('signingFail', (event) => {
        console.error('Signing failed:', event.detail.failureReason, event.detail.error);
      });

      signer.addEventListener('fieldChange', (event) => {
        if (event.detail.eventType === 'ready') {
          console.log('Ready to sign:', event.detail.document.name);
        }
      });
    </script>
  </body>
</html>

Support navigateur

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

Ressources

• Package NPM
• Widget Authorization
• Documentation API GraphQL
• Migration depuis la signature iframe
• Support

Vidéo : Migration de l’iframe au composant Signer