Saltar al contenido principal

Integrar el Visor de Documentos Legalesign en su Sitio Web

sugerencia

Puede 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 le permite editar, previsualizar y personalizar plantillas para la firma de documentos. Construido con StencilJS, funciona sin problemas con JavaScript puro, React, Vue, Angular o cualquier framework web.

Este componente plug and play está diseñado para que pueda integrar partes clave de la creación de documentos en sus sistemas internos, como un CRM o una aplicación de línea de negocio. Mientras su sistema pueda renderizar y soportar componentes HTML, puede usar el Visor de Documentos. Si necesita ayuda adicional para integrar el Visor de Documentos en su stack técnico, póngase en contacto con nuestro equipo de soporte. Puede usar estos widgets más grandes con integraciones API REST/GraphQL para proporcionar procesos de firma de documentos sin interrupciones para su 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 Vanilla​

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

Agregue los scripts del componente a su 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á usar código del lado del servidor para obtener el token para la cuenta que desea usar.

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​

Su token de seguridad para autenticación. Esto verifica su identidad y acceso a la plantilla. Para más información sobre cómo obtener un token de forma segura sin exponer sus credenciales, vea los ejemplos en la guía de autenticación.

token="eyJraWQiOiJBTkJIeT..."

templateid​

El ID API de la plantilla que desea presentar a los usuarios. Puede encontrarlo fácilmente mirando en la URL cuando está editando la plantilla en la aplicación Console.

templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"

Modos del Widget​

Modo Editor​

Creación y edición de plantillas con todas las herramientas disponibles. Esto está destinado a flujos de trabajo donde una plantilla altamente reutilizable con roles es útil. Si su intención es usar su documento una sola vez (quizás su sistema de generación de documentos ya haya llenado toda la información del cliente), entonces podría considerar el modo compose en su lugar.

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

Modo Compose​

Modo simplificado para añadir rápidamente cajas de firmas a plantillas pre-generadas. Ideal para clientes integrados donde los destinatarios ya están definidos.

El flujo de trabajo típico es:

  1. Su aplicación genera un PDF
  2. Súbalo mediante la 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. Suba el archivo PDF a S3 usando el ID de la plantilla
  2. Incruste el visor en modo compose con los detalles del destinatario
  3. Su usuario añade campos de firma y envía

Para más información sobre destinatarios vea Recipients.

<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 automáticamente:

  • Detecta destinatarios pre-generados
  • Oculta el remitente en el desplegable
  • Oculta opciones del documento
  • Muestra campos obligatorios por defecto
  • Elimina el remitente y campos de remitente del editor
  • Facilita 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 por las páginas.

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

El modo compose automáticamente:

  • Oculta la barra de herramientas
  • Oculta opciones del documento
  • Oculta la caja de herramientas
  • Hace que participantes y campos sean sólo lectura

Configuración Avanzada​

Filtrar Caja de Herramientas​

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

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

endpoint​

Su endpoint API GraphQL, si le han dado un endpoint específico para cliente.

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

Destinatarios​

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

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

Escuche eventos del componente para rastrear cambios:

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

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

Puede 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 prefija con el familiar 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 al 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>

Resolución de Problemas

Si encuentra problemas con el componente, asegúrese 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, contacte al equipo de soporte de Legalesign o visite la documentación API.

Export This Article

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