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:
- Crear una nueva plantilla en tu grupo de Legalesign
- Obtener el ID de plantilla y la URL de carga desde la respuesta de la mutación
- Subir tu archivo fuente a la plantilla
- 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 plantillaprocessTags: 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=..."
}
}
}
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
- JavaScript
- Python
- C#
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.
import requests
from gql import gql, Client
from gql.transport.requests import RequestsHTTPTransport
def upload_pdf_template(graphql_endpoint, auth_token, group_id, title, pdf_file_path):
transport = RequestsHTTPTransport(
url=graphql_endpoint,
headers={'Authorization': auth_token}
)
client = Client(transport=transport, fetch_schema_from_transport=True)
# Step 1: Create the template
print('Creating template...')
create_mutation = gql('''
mutation CreateTemplate($input: templateCreateInput!) {
createTemplate(input: $input) {
id
uploadUrl
}
}
''')
create_result = client.execute(
create_mutation,
variable_values={
'input': {
'groupId': group_id,
'title': title
}
}
)
template_id = create_result['createTemplate']['id']
upload_url = create_result['createTemplate']['uploadUrl']
print(f'Template created with ID: {template_id}')
# Step 2: Upload the PDF
print('Uploading PDF...')
with open(pdf_file_path, 'rb') as f:
file_data = f.read()
response = requests.put(
upload_url,
data=file_data,
headers={'Content-Type': 'application/pdf'}
)
if response.status_code != 200:
raise Exception(f'Upload failed: {response.status_code}')
print('PDF uploaded successfully!')
return {
'success': True,
'templateId': template_id,
'title': title
}
if __name__ == '__main__':
result = upload_pdf_template(
'https://graphql.uk.legalesign.com/graphql',
'Bearer YOUR_TOKEN',
'grpYourGroupId',
'Employment Contract',
'./contract.pdf'
)
print('Complete!', result)
using System;
using System.IO;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;
using GraphQL;
using GraphQL.Client.Http;
using GraphQL.Client.Serializer.Newtonsoft;
using Newtonsoft.Json.Linq;
public class PdfTemplateUploader
{
private readonly GraphQLHttpClient graphQLClient;
public PdfTemplateUploader(string graphqlEndpoint, string authToken)
{
graphQLClient = new GraphQLHttpClient(graphqlEndpoint, new NewtonsoftJsonSerializer());
graphQLClient.HttpClient.DefaultRequestHeaders.Add("Authorization", authToken);
}
public async Task<UploadResult> UploadPdfTemplate(
string groupId,
string title,
string pdfFilePath)
{
// Step 1: Create the template
Console.WriteLine("Creating template...");
var createMutation = new GraphQLRequest
{
Query = @"
mutation CreateTemplate($input: templateCreateInput!) {
createTemplate(input: $input) {
id
uploadUrl
}
}
",
Variables = new
{
input = new
{
groupId = groupId,
title = title
}
}
};
var createResponse = await graphQLClient.SendMutationAsync<dynamic>(createMutation);
string templateId = createResponse.Data.createTemplate.id;
string uploadUrl = createResponse.Data.createTemplate.uploadUrl;
Console.WriteLine($"Template created with ID: {templateId}");
// Step 2: Upload the PDF
Console.WriteLine("Uploading PDF...");
using var httpClient = new HttpClient();
var fileBytes = await File.ReadAllBytesAsync(pdfFilePath);
var content = new ByteArrayContent(fileBytes);
content.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/pdf");
var putResponse = await httpClient.PutAsync(uploadUrl, content);
if (!putResponse.IsSuccessStatusCode)
{
throw new Exception($"Upload failed: {putResponse.StatusCode}");
}
Console.WriteLine("PDF uploaded successfully!");
return new UploadResult
{
Success = true,
TemplateId = templateId,
Title = title
};
}
}
public class UploadResult
{
public bool Success { get; set; }
public string TemplateId { get; set; }
public string Title { get; set; }
}
class Program
{
static async Task Main(string[] args)
{
var uploader = new PdfTemplateUploader(
"https://graphql.uk.legalesign.com/graphql",
"Bearer YOUR_TOKEN"
);
var result = await uploader.UploadPdfTemplate(
"grpYourGroupId",
"Employment Contract",
"./contract.pdf"
);
Console.WriteLine($"Complete! Template ID: {result.TemplateId}");
}
}
¿Qué sucede después de la carga?
Una vez que tu PDF está cargado, Legalesign automáticamente:
- Escanea en busca de virus - Asegura que el archivo sea seguro
- Valida o convierte el archivo - Verifica que los PDFs sean válidos, o convierte archivos compatibles como documentos Word e imágenes a PDF
- Extrae información de las páginas - Obtiene el recuento y dimensiones de las páginas
- Procesa el archivo - Lo optimiza para la visualización y firma
- 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óncreateTemplatepara 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óncreateTemplatepara importarlos automáticamente como campos de plantilla.
Próximos pasos
Ahora que tienes una plantilla con un PDF, puedes:
- Agregar campos de firma - Usa la mutación
createTemplateElementpara añadir campos - Crear roles - Define quién firmará el documento
- Enviar para firma - Usa la mutación
sendpara 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.