Integra el Visor de Documentos Legalesign en Tu Sitio Web

sugerencia

Puedes ver este componente en acción como Envío Rápido en Console.

El Visor de Documentos Legalesign es un componente web independiente de la plataforma que te permite editar, previsualizar y personalizar plantillas para la firma de documentos. Funciona perfectamente en HTML con JavaScript, React, Vue, Angular o cualquier framework web.

Este componente plug and play está diseñado para que puedas integrar partes clave de la creación de documentos en tus sistemas internos, como un CRM o aplicación de línea de negocio.

Mientras tu sistema pueda renderizar y soportar componentes HTML, puedes usar el Visor de Documentos.

Si necesitas ayuda adicional para integrar el Visor de Documentos en tu stack técnico, por favor contacta con nuestro equipo de soporte.

Puedes usar estos widgets más grandes con integraciones REST/GraphQL API para proporcionar procesos de firma de documentos sin interrupciones para tu personal y clientes.

Instalación

Instalación NPM

npm install legalesign-document-viewer
# or
pnpm add legalesign-document-viewer

Para Proyectos React

npm install legalesign-document-viewer-react
# or
pnpm add legalesign-document-viewer-react

Integración Básica

HTML/JavaScript

La versión HTML/JavaScript de este componente puede usarse con cualquier stack de desarrollo, como PHP, ASP .Net, etc.
Puedes enlazar el componente directamente desde npm si tu entorno no permite que se instale. Puedes probar una página demostrativa del repositorio de ejemplo aquí [https://github.com/legalesign/ls-viewer-demo].

Añade los scripts del componente a tu 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>

Autenticación - Obtener un token

Necesitarás usar código del lado servidor para obtener YOUR_AUTH_TOKEN. Hay tres opciones:

SRP JWT directamente — Si tu backend ya usa autenticación SRP, pasa el token de acceso JWT directamente al widget.
GraphQL generateComponentToken — Llama a la mutación con tu clave API o JWT SRP para generar un token corto y específico para el componente.
REST API — Llama a GET /templatepdf/{pdfId}/component-token/ con tu clave API.

Opción 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;

Opción 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();

Pasa el token devuelto (o tu JWT SRP) al widget. Consulta Autorización del Widget para más detalles sobre las opciones de token.

Integración en React

También hemos generado una versión del componente que se integra directamente con frameworks React.

import { LsDocumentViewer } from 'legalesign-document-viewer-react';

function App() {
  return (
    <LsDocumentViewer
      templateid="YOUR_TEMPLATE_ID"
      token="YOUR_AUTH_TOKEN"
      mode="compose"
    />
  );
}

Atributos Requeridos

token

Tu token de seguridad para autenticación. Puede ser un token JWT SRP de acceso o un token de componente de corta duración de generateComponentToken. Consulta Autorización del Widget para el flujo seguro de tokens.

token="eyJraWQiOiJBTkJIeT..."

templateid

El ID API de la plantilla que quieres mostrar a los usuarios. Puedes encontrarlo observando la URL cuando estás editando la plantilla en la Aplicación Web.

templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"

Modo Editor

Creación y edición completa de plantillas con todas las herramientas disponibles. Esto está pensado para flujos de trabajo donde una plantilla altamente reutilizable con roles es útil. Si tu intención es usar tu documento solo una vez (quizás tu sistema de generación de documentos ya ha rellenado toda la información del cliente), entonces puede que prefieras considerar el modo compose en su lugar.

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

Modo Componer

Este modo es un método “receptor primero” para agilizar la experiencia del usuario. En la Aplicación Web Legalesign esta es la función “Envío rápido”.

Añade tus destinatarios al atributo ‘recipient’ y tu usuario puede rápidamente poner sus firmas y campos de formulario antes de enviar. Ideal para clientes integrados donde los destinatarios ya están definidos.

El flujo típico es clonar o subir un PDF, luego incrustar el visor donde el usuario puede añadir firmas y campos de formulario, después ofrecer un botón para enviar el documento.

Clonar

Clona una plantilla existente usando la mutación 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;

O Subir

Crea una plantilla y luego súbela a la uploadUrl proporcionada. Usa el título [deleted] si no quieres que el pdf esté en tu biblioteca. Se eliminará en las próximas 24 horas. De lo contrario usa cualquier título de tu preferencia:

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;

Ahora realiza PUT de tu archivo a la uploadUrl. El tipo de contenido debe ser application/pdf.

Incrustar el visor

El atributo principal es 'recipients'. Necesitarás detalles adicionales para aprobadores o testigos; para más información ve a Destinatarios.

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

El modo compose hace automáticamente:

Detecta destinatarios pre-generados
Oculta el remitente del desplegable
Oculta las opciones del documento
Muestra los campos requeridos por defecto
Elimina remitente y campos de remitente del editor
Promueve la selección rápida de los campos requeridos para cada destinatario

Modo Vista Previa

Una vista previa útil del documento que muestra el documento con todos los campos actuales y permite al usuario navegar por las páginas.

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

El modo vista previa hace automáticamente:

Oculta la barra de herramientas
Oculta las opciones del documento
Oculta la caja de herramientas
Hace que participantes y campos sean de solo lectura

Configuración Avanzada

Filtrar Caja de Herramientas

Restringe los tipos de campo disponibles usando valores delimitados por tuberías. Si no se proporciona ningún valor se asume que la caja de herramientas no estará filtrada y todas las opciones estarán disponibles.

<ls-document-viewer
  filtertoolbox="signature|initials|date|text"
  ...
></ls-document-viewer>

Valores disponibles para filtro:

Valor	Descripción
`signature`	Campo de firma (solo firmante)
`auto sign`	Campo de firma automática (solo remitente)
`text`	Entrada de texto libre
`signing date`	Fecha autocompletada en momento de firma (solo firmante)
`date`	Selector de fecha
`email`	Entrada de email
`initials`	Campo de iniciales
`number`	Entrada numérica
`dropdown`	Selección desplegable
`checkbox`	Casilla de verificación
`regex`	Entrada validada con regex (solo firmante)
`image`	Subida de imagen (solo firmante)
`file`	Subida de archivo (solo firmante)
`drawn`	Campo dibujado/a mano alzada (solo firmante)

Destinatarios

Define los destinatarios del documento en formato JSON.

Los elementos requeridos para cada destinatario son firstname, lastname, email y signerIndex;

Opcionalmente puedes pasar el role y phonenumber para cada destinatario. Omitir un role significa que el destinatario será tratado como firmante.

Puedes pasar role "WITNESS" o "APPROVER". Para el role "WITNESS" añade 100 al número signerIndex de su firmante. Por ejemplo, si necesitas un testigo para el firmante 2 (signerIndex: 2), haz que el WITNESS tenga 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>

Botones Personalizados con Slots

Añade botones personalizados a la barra de herramientas usando slots. Probablemente usarás estos para cancelar la acción o enviar el documento.

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

Manejo de Eventos

Escucha eventos del componente para rastrear cambios:

const editor = document.querySelector('ls-document-viewer');

editor.addEventListener('update', (event) => {
  console.log('Template changed:', event.detail);
});

Puedes saber si una plantilla se ha vuelto válida o inválida usando el evento validate.

const editor = document.querySelector('ls-document-viewer');

editor.addEventListener('validate', (event) => {
  console.log('Template validation changed:', event.detail.valid);
});

Ejemplo de Manejo de Evento en React

Usar un evento en react lo prefija con el habitual on<EventName>.

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

Tipos de Evento

Evento `update`

Se dispara cuando la plantilla del documento cambia, como agregar o eliminar campos. Proporciona no solo el evento que lo causó, sino también el estado actualizado del objeto plantilla en JSON.

Evento `validate`

Se dispara cuando la plantilla del documento cambia, la propiedad valid en detalle muestra si la plantilla se ha vuelto válida o inválida.

Evento `selectFields`

Se dispara cuando se selecciona un campo en el editor.

Evento `addParticipant`

Se dispara cuando se añade un rol de participante a la plantilla.

Ejemplo Completo

<!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>

Puedes usar la mutación send GraphQL del lado cliente si usas el token JWT SRP, pero de lo contrario, del lado servidor usando tu clave API con la interfaz GraphQL o REST.

Mutación Send — envía un solo documento
Esquema de Entrada Send — referencia completa de entrada
REST Send - referencia REST para envío de documentos

Solución de Problemas

Si tienes problemas con el componente, asegúrate de que:

puedas acceder o tengas en lista blanca el dominio de almacenamiento de documentos en https://s3.amazonaws.com/*

Soporte de Navegadores

El componente usa estándares web modernos y soporta:

Chrome/Edge (última versión)
Firefox (última versión)
Safari (última versión)
Navegadores móviles (iOS Safari, Chrome Mobile)

Recursos

Guía de Integración GraphQL — cómo conectar el visor a la API GraphQL para envío
Documentación API GraphQL
Paquete NPM
Paquete React
Soporte

Obtener Ayuda

Para soporte técnico o preguntas sobre integración, contacta con el equipo de soporte de Legalesign o visita la documentación API.

Integra el Visor de Documentos Legalesign en Tu Sitio Web

Instalación

Instalación NPM

Para Proyectos React

Integración Básica

HTML/JavaScript

Autenticación - Obtener un token

Integración en React

Atributos Requeridos

token

templateid

Modos del Widget

Modo Editor

Modo Componer

Clonar

O Subir

Incrustar el visor

Modo Vista Previa

Configuración Avanzada

Filtrar Caja de Herramientas

Destinatarios

Botones Personalizados con Slots

Manejo de Eventos

Ejemplo de Manejo de Evento en React

Tipos de Evento

Evento `update`

Evento `validate`

Evento `selectFields`

Evento `addParticipant`

Ejemplo Completo

Solución de Problemas

Soporte de Navegadores

Recursos

Obtener Ayuda

Export This Article

Instalación​

Instalación NPM​

Para Proyectos React​

Integración Básica​

HTML/JavaScript​

Autenticación - Obtener un token​

Integración en React​

Atributos Requeridos​

token​

templateid​

Modos del Widget​

Modo Editor​

Modo Componer​

Clonar​

O Subir​

Incrustar el visor​

Modo Vista Previa​

Configuración Avanzada​

Filtrar Caja de Herramientas​

Destinatarios​

Botones Personalizados con Slots​

Manejo de Eventos​

Ejemplo de Manejo de Evento en React​

Tipos de Evento​

Evento update​

Evento validate​

Evento selectFields​

Evento addParticipant​

Ejemplo Completo​

Solución de Problemas

Soporte de Navegadores​

Recursos​

Obtener Ayuda​

Export This Article

Instalación

Instalación NPM

Para Proyectos React

Integración Básica

HTML/JavaScript

Autenticación - Obtener un token

Integración en React

Atributos Requeridos

token

templateid

Modos del Widget

Modo Editor

Modo Componer

Clonar

O Subir

Incrustar el visor

Modo Vista Previa

Configuración Avanzada

Filtrar Caja de Herramientas

Destinatarios

Botones Personalizados con Slots

Manejo de Eventos

Ejemplo de Manejo de Evento en React

Tipos de Evento

Evento `update`

Evento `validate`

Evento `selectFields`

Evento `addParticipant`

Ejemplo Completo

Soporte de Navegadores

Recursos

Obtener Ayuda