Saltar al contenido principal

Subir un archivo como plantilla

Esta guía te guía a través del proceso completo de crear una plantilla y subir un archivo PDF, imagen o Word para usar como tu plantilla de documento en Legalesign.

Lo que aprenderás​

Al final de esta guía, sabrás cómo:

  1. Crear una nueva plantilla en tu grupo de Legalesign
  2. Obtener el ID de plantilla y la URL de carga desde la respuesta de la mutación
  3. Subir tu archivo fuente a la plantilla
  4. Verificar que la carga fue exitosa

Requisitos previos​

Antes de comenzar, asegúrate de tener:

  • Una cuenta de Legalesign con acceso a la API
  • Tus credenciales de autenticación (consulta nuestra guía de autenticación)
  • Un archivo PDF, imagen o Word listo para subir (máximo 50MB)
  • Tu ID de grupo (el espacio de trabajo donde quieres crear la plantilla)

El proceso completo​

Paso 1: Crear una plantilla​

Primero, crea una plantilla vacía en Legalesign. Esto devuelve tanto el ID de plantilla como una URL de carga pre-firmada para la carga del PDF. Para hacer esto, necesitarás ejecutar una mutación GraphQL; si no lo has hecho antes, consulta la Introducción a GraphQL.

¿Qué es una plantilla?​

Una plantilla es una estructura de documento reutilizable en Legalesign. Una vez que subes un PDF a una plantilla, puedes:

  • Agregar campos de firma y campos de formulario
  • Enviarla a varios destinatarios
  • Reutilizarla para diferentes firmantes

Mutación GraphQL​

mutation CreateTemplate($input: templateCreateInput!) {
createTemplate(input: $input) {
id
uploadUrl
}
}

Variables de entrada​

{
"input": {
"groupId": "grpYourGroupAPIId",
"title": "Employment Contract Template"
}
}

Parámetros explicados​

  • groupId: El ID en base 64 de tu grupo/espacio de trabajo (puedes obtenerlo desde la URL en la Console https://console.legalesign.com/)
  • title: Un nombre descriptivo para tu plantilla (puedes cambiarlo más tarde)
  • uploadOptions (opcional): Opciones de procesamiento aplicadas al subir el PDF:
    • pdfFieldsImport: true — importa campos de formularios PDF embebidos como campos de plantilla
    • processTags: true — procesa etiquetas de texto Legalesign en el documento al subirlo

Paso 2: Extraer el ID de plantilla y la URL de carga​

La mutación devuelve un objeto templateCreateOutput. Guarda el campo id y la cadena uploadUrl.

Ejemplo de respuesta:

{
"data": {
"createTemplate": {
"id": "dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx",
"uploadUrl": "https://s3.amazonaws.com/bucket/path?signature=..."
}
}
}
sugerencia

El ID de la plantilla es una cadena codificada en Base64. Guarda ambos valores de la respuesta. La uploadUrl tiene una duración corta y debe usarse rápidamente.

Paso 3: Subir tu PDF​

Usa la uploadUrl devuelta para subir tu archivo PDF directamente a S3. Esto será diferente dependiendo de tu stack de desarrollo. En nuestro ejemplo en javascript hemos usado fetch pero puedes usar otras bibliotecas incluyendo aws-amplify.

Ejemplos de trabajo completos​

import fs from 'fs';

const AUTH_TOKEN = '<token-from-authentication-guide>';

const uploadPdfTemplate = async (groupId, title, pdfFilePath) => {
const graphqlEndpoint = 'https://graphql.uk.legalesign.com/graphql';

// Step 1: Create the template
console.log('Creating template...');
const createResponse = await fetch(graphqlEndpoint, {
method: 'POST',
headers: {
'Content-Type': 'application/json',
'Authorization': `Bearer ${AUTH_TOKEN}`
},
body: JSON.stringify({
query: `
mutation CreateTemplate($input: templateCreateInput!) {
createTemplate(input: $input) {
id
uploadUrl
}
}
`,
variables: {
input: {
groupId: groupId,
title: title
}
}
})
});

const createResult = await createResponse.json();
const templateId = createResult.data.createTemplate.id;
const uploadUrl = createResult.data.createTemplate.uploadUrl;
console.log('Template created with ID:', templateId);

// Step 2: Upload the PDF
console.log('Uploading PDF...');
const fileData = fs.readFileSync(pdfFilePath);

const uploadResponse = await fetch(uploadUrl, {
method: 'PUT',
body: fileData,
headers: {
'Content-Type': 'application/pdf'
}
});

if (!uploadResponse.ok) {
throw new Error(`Upload failed: ${uploadResponse.statusText}`);
}

console.log('PDF uploaded successfully!');

return {
success: true,
templateId: templateId,
title: title
};
};

// Usage example
uploadPdfTemplate(
'grpYourGroupId',
'Employment Contract',
'./contract.pdf'
).then(result => {
console.log('Complete!', result);
}).catch(error => {
console.error('Error:', error);
});

No se necesitan dependencias adicionales — Node.js 18+ incluye fetch de forma nativa.

¿Qué sucede después de la carga?​

Una vez que tu PDF está cargado, Legalesign automáticamente:

  1. Escanea en busca de virus - Asegura que el archivo sea seguro
  2. Valida o convierte el archivo - Verifica que los PDFs sean válidos, o convierte archivos compatibles como documentos Word e imágenes a PDF
  3. Extrae información de las páginas - Obtiene el recuento y dimensiones de las páginas
  4. Procesa el archivo - Lo optimiza para la visualización y firma
  5. Lo almacena de forma segura - Lo mueve a almacenamiento permanente

Este proceso usualmente toma unos segundos. ¡Una vez completado, tu plantilla está lista para usar!

Seguimiento del progreso de carga​

Para recibir retroalimentación en tiempo real sobre el procesamiento de la carga (escaneo, validación, finalización), usa suscripciones. Consulta Seguimiento del progreso de carga con suscripciones.

Alternativamente, realiza sondeos al campo fileUploaded de la plantilla hasta que devuelva true:

query CheckUploadStatus($id: ID!) {
template(id: $id) {
id
fileUploaded
}
}

Añadir firmas y campos​

Si quieres automatizar los participantes y la colocación de campos, puedes preparar el archivo fuente antes de subir de un par de formas diferentes:

  • Etiquetas de texto — Añade etiquetas de texto Legalesign al documento fuente para que los participantes, campos de firma y campos de formulario puedan crearse automáticamente durante el procesamiento. Pasa uploadOptions: { processTags: true } en la mutación createTemplate para habilitar esto. Consulta la explicación de la API REST en el tutorial rápido y la referencia del endpoint Convertir etiquetas de texto.
  • Campos PDF embebidos — Si tu PDF ya contiene campos de formulario embebidos, pasa uploadOptions: { pdfFieldsImport: true } en la mutación createTemplate para importarlos automáticamente como campos de plantilla.

Próximos pasos​

Ahora que tienes una plantilla con un PDF, puedes:

  1. Agregar campos de firma - Usa la mutación createTemplateElement para añadir campos
  2. Crear roles - Define quién firmará el documento
  3. Enviar para firma - Usa la mutación send para enviar a los destinatarios

Problemas comunes y soluciones​

Error "Sin permiso"​

Verifica que tu ID de grupo sea correcto y que estés autenticado con la cuenta adecuada.

Error "Archivo demasiado grande"​

Comprime tu PDF — el máximo es 50MB.

URL de carga expirada​

Usa la uploadUrl devuelta por createTemplate rápidamente. Si expira antes de la carga, solicita una URL nueva con la consulta upload usando el ID de plantilla guardado.

Error "PDF inválido"​

Abre el PDF en un lector para verificar que sea válido, luego reexporta o guarda nuevamente.