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.

sugerencia

¿Necesitas retroalimentación en tiempo real sobre el procesamiento de la subida? Consulta Rastrear el progreso de la subida con suscripciones.

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 la plantilla y la URL de subida desde la respuesta de la mutación
3. Subir tu archivo fuente a la plantilla
4. Verificar que la subida 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 la plantilla como una URL de subida prefirmada para la subida 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 subas un PDF a una plantilla, podrás:

• Añadir campos de firma y campos de formulario
• Enviarla a múltiples 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 el Console https://console.legalesign.com/)
• title: Un nombre descriptivo para tu plantilla (puedes cambiarlo después)

Paso 2: Extraer el ID de la plantilla y la URL de subida

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

Respuesta de ejemplo:

{
  "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 vida 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 según tu stack de desarrollo. En nuestro ejemplo en javascript hemos utilizado fetch pero puedes usar otras librerías incluyendo aws-amplify.

Ejemplos completos y funcionales

JavaScript

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.

Python

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)

C#

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é pasa después de la subida?

Una vez que tu PDF se sube, Legalesign automáticamente:

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

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

Añadiendo firmas y campos

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

• Etiquetas de texto - Añade etiquetas de texto de Legalesign en el documento fuente para que los participantes, campos de firma y campos de formulario puedan crearse automáticamente durante el procesamiento. Consulta la explicación del API REST en el tutorial de inicio rápido y la referencia del endpoint Convertir etiquetas de texto.
• Campos PDF incrustados - Si tu PDF ya contiene campos de formulario incrustados, Legalesign puede usarlos como parte del flujo de trabajo de subida y preparación de la plantilla.

Próximos pasos

Ahora que tienes una plantilla con un PDF, puedes:

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

Problemas comunes y soluciones

Error "Sin permiso"

Verifica que tu ID de grupo es correcto y que estás autenticado con la cuenta correcta.

Error "Archivo demasiado grande"

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

URL de subida expirada

Usa la uploadUrl que devuelve createTemplate rápidamente. Si expira antes de subir, 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 es válido, luego vuelve a exportarlo o guardarlo.

Rastrear progreso de subida

Para obtener retroalimentación en tiempo real sobre el procesamiento de la subida (escaneo, validación, finalización), usa suscripciones. Consulta Rastrear el progreso de la subida con suscripciones.