Saltar al contenido principal

Integrar el Visor de Documentos

El Visor de Documentos es un componente web que permite a los usuarios editar plantillas y preparar documentos para firmar — directamente dentro de tu aplicación. Esta guía muestra cómo conectarlo a la API GraphQL para construir un flujo completo de firma.

Vista General​

Una integración típica sigue estos pasos:

  1. Autenticar — obtener un token para el visor
  2. Subir una plantilla — a través de la API GraphQL
  3. Renderizar el visor — pasar el ID de la plantilla y el token
  4. Capturar eventos — el visor emite eventos update y validate mientras el usuario trabaja
  5. Enviar el documento — llamar a la mutación send con los datos del destinatario y rol desde el visor

Autenticación​

El visor necesita un token válido pasado a su atributo token. Tu backend proporciona un token de componente de corta duración desde generateComponentToken. Consulta Autorización del Widget antes de conectar el visor en tu aplicación.

Modo Composición — Enviar un Documento Preconstruido​

El modo composición es para flujos donde tu sistema ya conoce a los destinatarios. El usuario sólo coloca campos de firma y envía.

1. Renderizar el visor​

<ls-document-viewer
id="viewer"
templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
token="YOUR_ACCESS_TOKEN"
mode="compose"
recipients='[
{"email": "jane@example.com", "firstname": "Jane", "lastname": "Smith", "signerIndex": 1},
{"email": "john@example.com", "firstname": "John", "lastname": "Doe", "signerIndex": 2}
]'
filtertoolbox="signature|initials|date|text"
>
<span slot="right-button">
<button id="send-btn" disabled>Send</button>
</span>
</ls-document-viewer>

2. Rastrear validación y IDs de rol​

Mientras el usuario agrega campos, el visor emite eventos. Necesitas dos cosas de estos eventos:

  • validate — indica si la plantilla tiene todos los campos requeridos (mínimo, una firma por destinatario)
  • update — proporciona el estado actual de la plantilla, incluyendo roleId para cada participante cuando necesitas el mapeo de roles de la plantilla
const viewer = document.getElementById('viewer');
const sendBtn = document.getElementById('send-btn');

let isValid = false;
const recipientRoles = {};

viewer.addEventListener('validate', (e) => {
isValid = e.detail.valid;
sendBtn.disabled = !isValid;
});

viewer.addEventListener('update', (e) => {
const roles = e.detail.template.roles;
roles.forEach((role) => {
recipientRoles[role.signerIndex] = role.id;
});
});

El roleId del evento update mapea cada destinatario con sus campos en la plantilla. Inclúyelo cuando tu flujo de envío necesite ese mapeo.

3. Enviar el documento​

Cuando el usuario hace clic en enviar, llama a la mutación send con los datos del destinatario y los IDs de rol capturados del visor:

sendBtn.addEventListener('click', async () => {
const token = '<token-from-authentication-guide>';

const recipients = [
{
firstName: 'Jane',
lastName: 'Smith',
email: 'jane@example.com',
role: 'Signer',
roleId: recipientRoles[1],
signerIndex: 1,
order: 1,
},
{
firstName: 'John',
lastName: 'Doe',
email: 'john@example.com',
role: 'Signer',
roleId: recipientRoles[2],
signerIndex: 2,
order: 2,
},
];

const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${token}`,
},
body: JSON.stringify({
query: `mutation SendDocument {
send(input: {
groupId: "YOUR_GROUP_ID"
templateId: "dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
title: "Contract - Jane Smith & John Doe"
recipients: ${JSON.stringify(recipients).replace(/"(\w+)":/g, '$1:')}
sequentialSigning: true
})
}`,
}),
});

const result = await response.json();
const taskId = result.data.send;

// Poll for completion
console.log('Task started:', taskId);
});

La mutación send devuelve un ID de tarea. Consulta repetidamente la query task y monitorea task.report.status hasta que alcance COMPLETED o FAILED para confirmar que la creación del documento ha finalizado.

Modo Editor — Creación de Plantillas​

El modo editor ofrece a los usuarios la experiencia completa de edición de plantilla — agregar roles, colocar campos, configurar opciones. Usalo cuando quieras que los usuarios construyan plantillas reutilizables.

<ls-document-viewer
id="editor"
templateid="dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx"
token="YOUR_ACCESS_TOKEN"
mode="editor"
></ls-document-viewer>

En modo editor, el evento update se dispara cada vez que la plantilla cambia. Puedes usar esto para rastrear el estado de la plantilla o mostrar un indicador de guardado:

const editor = document.getElementById('editor');

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

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

Los cambios en la plantilla se guardan automáticamente por el visor — no necesitas llamar a ninguna mutación de GraphQL para persistir las ediciones.

Integración con React​

El wrapper de React proporciona la misma funcionalidad con manejo de eventos al estilo React:

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

const DocumentCompose = ({ templateId, recipients, token }) => {
const [isValid, setIsValid] = useState(false);
const [roleMap, setRoleMap] = useState({});

const handleValidate = (e) => {
setIsValid(e.detail.valid);
};

const handleUpdate = (e) => {
const roles = e.detail.template.roles;
const map = {};
roles.forEach((role) => {
map[role.signerIndex] = role.id;
});
setRoleMap(map);
};

const handleSend = async () => {
const mappedRecipients = recipients.map((r, i) => ({
...r,
roleId: roleMap[r.signerIndex],
order: i + 1,
}));

const response = await fetch('https://graphql.uk.legalesign.com/graphql', {
method: 'POST',
headers: {
'Content-Type': 'application/json',
Authorization: `Bearer ${token}`,
},
body: JSON.stringify({
query: `mutation SendDocument {
send(input: {
groupId: "YOUR_GROUP_ID"
templateId: "${templateId}"
title: "Document"
recipients: ${JSON.stringify(mappedRecipients).replace(/"(\w+)":/g, '$1:')}
})
}`,
}),
});

const result = await response.json();
console.log('Task ID:', result.data.send);
};

if (!token) return null;

return (
<LsDocumentViewer
templateid={templateId}
token={token}
mode="compose"
recipients={JSON.stringify(recipients)}
onValidate={handleValidate}
onUpdate={handleUpdate}
>
<div slot="right-button">
<button onClick={handleSend} disabled={!isValid}>
Send
</button>
</div>
</LsDocumentViewer>
);
};

Testigos​

Para agregar un testigo para un firmante, establece roleType: "WITNESS" y usa un signerIndex que sea el índice del firmante principal + 100. Por ejemplo, un testigo para el firmante 2 tiene signerIndex: 102:

<ls-document-viewer
mode="compose"
recipients='[
{"email": "signer@example.com", "firstname": "Alice", "lastname": "Jones", "signerIndex": 1},
{"email": "signer2@example.com", "firstname": "Bob", "lastname": "Brown", "signerIndex": 2},
{"email": "witness@example.com", "firstname": "Carol", "lastname": "White", "signerIndex": 102, "roleType": "WITNESS"}
]'
...
></ls-document-viewer>

Conceptos Clave​

Concepto del visorTipo GraphQLDescripción
Atributo templateidTemplateLa plantilla que se está editando o componiendo
Atributo recipientsRecipientInputDestinatarios pasados en modo composición
roleId del evento updateRoleVincula un destinatario con sus campos en la plantilla
Evento validate—Indica si la plantilla tiene todos los campos requeridos
Mutación sendsendEnvía el documento después de componerlo
Atributo token—Token desde autenticación
mode="compose"—Modo simplificado para colocar campos y enviar
mode="editor"—Modo completo de edición de plantilla
experience en input de sendExperienceControla la marca, emails y página de firma — ver Experiencias explicadas