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.

Versión actual: v1.0.27 — changelog

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. Funciona perfectamente en HTML con JavaScript, 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 pila técnica, póngase en contacto con nuestro servicio 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
# 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 se puede usar con cualquier pila de desarrollo, como PHP, ASP .Net, etc. Puede enlazar al componente directamente desde npm si su entorno no permite instalarlo. Puede probar una página de demostración del repositorio de ejemplo aquí [https://github.com/legalesign/ls-viewer-demo].

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>

Autenticación - Obtener un token​

Necesitará usar código del lado del servidor para obtener YOUR_AUTH_TOKEN. Hay dos opciones, y ambas usan su clave API:

  1. GraphQL generateComponentToken — Llame a la mutación con su clave API para emitir un token de componente temporal y con alcance específico.
  2. REST API — Llame a GET /templatepdf/{pdfId}/component-token/ con su clave API.

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

Pase el token devuelto al widget. Vea Widget Authorization para más detalles sobre las opciones de token.

Integración con 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: un token de componente temporal obtenido de generateComponentToken o del endpoint REST component-token. Vea Widget Authorization para el flujo seguro del token.

token="eyJraWQiOiJBTkJIeT..."

templateid​

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

templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"

Modos del Widget​

Modo Editor​

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

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

Modo Compose​

Este modo es un método 'centrado en el destinatario' para agilizar la experiencia del usuario. En la aplicación web Legalesign esta es la función 'Quick send'.

Agregue sus destinatarios al atributo 'recipient' y su usuario podrá colocar rápidamente 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 agregar firmas y campos de formulario, y luego ofrecer un botón para enviar el documento.

Clonar​

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

Cree una plantilla y luego súbala a la uploadUrl proporcionada. Use el título [deleted] si no quiere el pdf en su biblioteca. Será eliminado en las próximas 24 horas. De lo contrario, use cualquier título de su elección:

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 haga PUT de su archivo a la uploadUrl. El tipo de contenido debe ser application/pdf.

Incrustar el visor​

El atributo principal es 'recipients'. Necesitará detalles adicionales para los aprobadores o testigos: para más información 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 al remitente del desplegable
  • Oculta opciones del documento
  • Muestra los campos requeridos por defecto
  • Elimina al remitente y campos del remitente del editor
  • Promueve la selección rápida de los campos requeridos para cada destinatario

Modo Previsualización​

Una previsualización ú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 previsualización automáticamente:

  • Oculta la barra de herramientas
  • Oculta las opciones de documento
  • Oculta la caja de herramientas
  • Hace que los 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 entonces se asume que la caja de herramientas no estará filtrada y todas las opciones están disponibles.

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

Valores de filtro disponibles:

ValorDescripción
signatureCampo de firma (solo firmante)
auto signCampo de auto-firma (solo remitente)
textEntrada de texto libre
signing dateFecha auto-llenada al firmar (solo firmante)
dateSelector de fecha
emailEntrada de correo electrónico
initialsCampo de iniciales
numberEntrada numérica
dropdownSelección desplegable
checkboxCasilla de verificación
regexEntrada validada por regex (solo firmante)
imageCarga de imagen (solo firmante)
fileCarga de archivo (solo firmante)
drawnCampo dibujado/a mano alzada (solo firmante)

Destinatarios​

Defina los destinatarios del documento en formato JSON.

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

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

Puede pasar los roles "WITNESS" o "APPROVER". Para el rol "WITNESS" sume 100 al número signerIndex de su firmante. Por ejemplo, si necesita un testigo para el firmante 2 (signerIndex: 2), haga 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 Ranuras​

Agregue botones personalizados a la barra de herramientas usando slots. Probablemente los usará 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​

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 prefiere con el 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 en formato JSON.

Evento validate​

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

Envíe el documento del lado del servidor usando su clave API, con la interfaz GraphQL o REST.

Solució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)

Historial de Cambios​

VersiónFechaResumen
v1.0.2719 Oct 2026Mejoras en la colocación de campos
v1.0.263 Sep 2026Correcciones de desplazamiento; renderizado diferido en carga
v1.0.2112 Ago 2026Opciones de modo vista previa; mejoras en evento update
v1.0.1817 Jul 2026Panel de campo regex; múltiples propiedades avanzadas; mejoras en desplegables; renombramiento de testigos
v1.0.1210 Jul 2026Propiedad de campo excludeFromPdf
v1.0.99 Jul 2026Campos de fecha auto y regex; propiedades avanzadas; orden de campos
v1.0.62 Jul 2026Corrección de fuente que prevenía fallos en firmas; márgenes en vista previa
v1.0.529 Jun 2026Atajos de teclado para deshacer/rehacer
v1.0.426 Jun 2026Mejoras en eventos; actualizaciones optimistas; deshacer/rehacer
v1.0.024 Jun 2026Versión estable inicial

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.