Saltar al contenido principal

Integra el Visor de Documentos Legalesign en Tu Sitio Web

sugerencia

Puedes ver este componente en acción como Quick Send 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. Construido con StencilJS, funciona perfectamente con JavaScript puro, 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, tales como un CRM o una 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 soporte. Puedes usar estos widgets más grandes con integraciones API REST/GraphQL para proporcionar procesos de firma de documentos sin interrupciones para tu personal y clientes.

Instalación​

Instalación NPM​

npm install legalesign-document-viewer

Para Proyectos React​

npm install legalesign-document-viewer-react

Integración Básica​

HTML/JavaScript Puro​

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

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

Necesitarás usar código del lado servidor para obtener YOUR_AUTH_TOKEN. El token puede ser un JWT SRP o un token temporal de componente generado con generateComponentToken. Consulta Autorización de Widget.

Integración 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. Esto verifica tu identidad y acceso a la plantilla. Usa código del lado servidor para proveer ya sea un JWT SRP o un token temporal de componente. Consulta Autorización de Widget para el flujo seguro del token.

token="eyJraWQiOiJBTkJIeT..."

templateid​

El ID API de la plantilla que quieres mostrar a los usuarios. Puedes encontrarlo fácilmente mirando en la URL cuando estás editando la plantilla en la aplicación Console.

templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"

Modos del Widget​

Modo Editor​

Creación y edición completa de plantillas con todas las herramientas disponibles. Está destinado 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 llenado toda la información del cliente), entonces tal vez quieras considerar el modo crear en su lugar.

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

Modo Crear​

Modo simplificado para agregar rápidamente campos de firma a plantillas pre-generadas. Ideal para clientes integrados donde los destinatarios ya están definidos.

El flujo típico es:

  1. Tu aplicación genera un PDF
  2. Súbelo vía API para crear una plantilla:
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: "${groupId}"
          title: "${documentTitle}"
        })
      }
    `
  })
});
const { data } = await response.json();
const templateId = data.createTemplate;
  1. Sube el archivo PDF a S3 usando el ID de la plantilla
  2. Inserta el visor en modo crear con los detalles de los destinatarios
  3. Tu usuario añade campos de firma y envía

Para más información sobre destinatarios, ve 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 crear automáticamente:

  • Detecta destinatarios pre-generados
  • Oculta al remitente del menú desplegable
  • Oculta opciones del documento
  • Muestra campos requeridos por defecto
  • Elimina el remitente y campos de remitente del editor
  • Promueve la selección rápida de 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 entre las páginas.

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

El modo crear automáticamente:

  • Oculta la barra de herramientas
  • Oculta opciones del documento
  • Oculta la caja de herramientas
  • Hace que los participantes y campos sean 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 será filtrada y todas las opciones estarán disponibles.

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

endpoint​

Tu endpoint de API GraphQL, si te han dado un endpoint específico para cliente.

endpoint="https://your-api.appsync-api.region.amazonaws.com/graphql"

Destinatarios​

Define los destinatarios del documento en formato JSON. Nota que los elementos requeridos para un destinatario son firstname, lastname, email y signerIndex; opcionalmente también puedes pasar role y phonenumber para cada destinatario. Omitir un role significa que el destinatario será tratado como un firmante distinto; para cambiar esto puedes pasar role: "WITNESS" e incluir un índice de firmante especial para mostrar quién es su padre, así por ejemplo si quieres incluir un testigo para el firmante 2, ese testigo tendría un signerIndex de 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​

Agrega botones personalizados a la barra de herramientas usando slots:

<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 los eventos del componente para rastrear cambios:

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

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

Puedes rastrear 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 Eventos en React​

Usar un evento en React lo prefiere con el clásico prefijo on<EventName>.

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

Tipos de Eventos​

Evento update​

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

Evento validate​

Se dispara cuando se cambia la plantilla del documento, la propiedad valid en detail indica 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>

Solución de Problemas

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

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​

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.

Export This Article

Save a copy of this page as PDF or plain text.