Subir Archivos a la Plataforma

Muchas tareas requieren que proporciones un archivo para que la plataforma Legalesign lo use, como un archivo para usar como plantilla o una imagen para usar en una firma.

Subidas de plantillas

Si quieres subir un documento plantilla, usa la guía dedicada Subir un archivo como plantilla en su lugar. Ese flujo ahora usa el uploadUrl devuelto por createTemplate.

Lo Que Aprenderás

Esta guía te guiará a través del proceso de subir archivos a Legalesign. No te preocupes si eres nuevo en APIs o almacenamiento en la nube, explicaremos cada paso con claridad.

¿Qué es una URL Pre-firmada?

Una URL pre-firmada es como un pase temporal de acceso. En lugar de darte acceso permanente a nuestro almacenamiento, te damos una URL especial que:

• Solo funciona por un corto tiempo (15 minutos)
• Solo te permite subir un archivo específico
• Mantiene tus archivos seguros

Piensa en ello como un ticket de valet parking: da acceso temporal y limitado para un propósito específico.

¿Qué es S3?

S3 (Simple Storage Service) es el servicio de almacenamiento en la nube de Amazon. Es donde guardamos de forma segura tus documentos, logotipos y otros archivos. No necesitas entender S3 en detalle, solo saber que es un lugar seguro para guardar archivos en la nube.

Resumen

El proceso de subida sigue estos pasos:

1. Solicitar una URL pre-firmada de subida desde la API GraphQL (pedir permiso para subir)
2. Subir tu archivo a S3 usando la URL proporcionada (enviar realmente el archivo)
3. La plataforma procesa y valida automáticamente el archivo (verificamos que sea seguro)
4. El archivo es movido a su destino final (lo ponemos en el lugar correcto)

¿Por qué este proceso en dos pasos?

Podrías preguntarte por qué no simplemente permitimos que subas directamente. Este proceso en dos pasos:

• Asegura que tienes permiso para subir
• Previene subidas de archivos no autorizados
• Nos permite escanear los archivos en busca de virus
• Lleva registro de quién subió qué

Paso 1: Solicitar URL de Subida

Usa la consulta upload para obtener una URL pre-firmada para subir tu archivo (en este caso un PDF). Consulta nuestra guía de autenticación para más información sobre cómo empezar a ejecutar consultas GraphQL. Para detalles completos de los argumentos, ve la referencia de la consulta upload.

query {
  upload(
    id: "<BASE64_OBJECT_ID>",
    uploadType: TEMPLATE,
    extension: "pdf"
  ) {
    url
  }
}

Parámetros Explicados

• id: ID del objeto codificado en Base64 (por ejemplo, ID de plantilla, ID de experiencia)
• uploadType: El tipo de archivo que se está subiendo (ver más abajo)
• extension: Extensión del archivo (pdf, png, jpg)

Tipos de Subida

• TEMPLATE - Archivos PDF para plantillas de documentos
• LOGO - Imágenes para la marca en la página de firma
• EMAILLOGO - Imágenes para la marca en correos electrónicos
• ATTACHMENT - Archivos adicionales para adjuntar a documentos

Consulta el enum UploadType para la lista completa.

Paso 2: Subir a S3

La consulta devuelve una URL pre-firmada. Envía tu archivo a esta URL usando una petición HTTP PUT:

const response = await fetch(url, {
  method: 'PUT',
  body: fileData,
  headers: {
    'Content-Type': 'application/pdf' // or appropriate MIME type
  }
});

Paso 3: Procesamiento Automático

Una vez subido, la plataforma:

1. Escanea el archivo en busca de virus y amenazas de seguridad
2. Valida el formato y contenido del archivo
3. Procesa el archivo (por ejemplo, extrae dimensiones de página para PDFs)
4. Lo mueve a la ubicación final de almacenamiento con los permisos apropiados

Seguimiento del Procesamiento en Tiempo Real

Si necesitas retroalimentación en tiempo real tras completar la subida a S3, usa suscripciones GraphQL.

• Los eventos de subida se entregan en subscribeUserFeed
• Usan category: "upload"
• Eventos típicos incluyen uploadScanned, uploadTypeChecked, uploadCompleted y uploadFailed

Consulta Seguimiento del progreso de subida con suscripciones.

Ejemplo Completo

JavaScript

import { generateClient } from 'aws-amplify/api';

const uploadFile = async (objectId, file) => {
  const client = generateClient();
  const extension = file.name.split('.').pop();
  
  // Step 1: Get upload URL
  const result = await client.graphql({
    query: `
      query {
        upload(
          id: "${objectId}",
          uploadType: TEMPLATE,
          extension: "${extension}"
        ) {
          url
        }
      }
    `
  });
  
  const uploadUrl = result.data.upload.url;
  
  // Step 2: Upload file
  const response = await fetch(uploadUrl, {
    method: 'PUT',
    body: file,
    headers: {
      'Content-Type': file.type
    }
  });
  
  if (!response.ok) {
    throw new Error('Upload failed');
  }
  
  return { success: true };
};

Python

import requests
from gql import gql, Client
from gql.transport.requests import RequestsHTTPTransport

def upload_file(graphql_endpoint, auth_token, object_id, file_path):
    extension = file_path.split('.')[-1]
    
    transport = RequestsHTTPTransport(
        url=graphql_endpoint,
        headers={'Authorization': auth_token}
    )
    client = Client(transport=transport, fetch_schema_from_transport=True)
    
    query = gql(f'''
        query {{
            upload(
                id: "{object_id}",
                uploadType: TEMPLATE,
                extension: "{extension}"
            ) {{
                url
            }}
        }}
    ''')
    
    result = client.execute(query)
    upload_url = result['upload']['url']
    
    with open(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('Upload failed')
    
    return {'success': True}

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;

public class FileUploader
{
    public async Task<bool> UploadFile(string graphqlEndpoint, string authToken, 
                                       string objectId, string filePath)
    {
        var extension = Path.GetExtension(filePath).TrimStart('.');
        
        var graphQLClient = new GraphQLHttpClient(
            graphqlEndpoint, 
            new NewtonsoftJsonSerializer()
        );
        graphQLClient.HttpClient.DefaultRequestHeaders.Add("Authorization", authToken);
        
        var query = new GraphQLRequest
        {
            Query = $@"
                query {{
                    upload(
                        id: ""{objectId}"",
                        uploadType: TEMPLATE,
                        extension: ""{extension}""
                    ) {{
                        url
                    }}
                }}
            "
        };
        
        var response = await graphQLClient.SendQueryAsync<dynamic>(query);
        string uploadUrl = response.Data.upload.url;
        
        using var httpClient = new HttpClient();
        var fileBytes = await File.ReadAllBytesAsync(filePath);
        var content = new ByteArrayContent(fileBytes);
        content.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/pdf");
        
        var uploadResponse = await httpClient.PutAsync(uploadUrl, content);
        
        if (!uploadResponse.IsSuccessStatusCode)
        {
            throw new Exception("Upload failed");
        }
        
        return true;
    }
}

Formato de la Ruta

Los archivos siguen esta convención de nombres:

<uploadType>/<userId>/<base64ObjectId>.<extension>

Ejemplo:

template/usr123abc/dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx.pdf

nota

No necesitas crear esta ruta tú mismo: la API la maneja automáticamente cuando proporcionas los parámetros correctos.

Tipos de Archivos Soportados

Plantillas

• Solo archivos PDF
• Tamaño máximo: 50MB

Logotipos y Logotipos de Email

• PNG, JPG, JPEG
• Tamaño máximo: 5MB
• Dimensiones recomendadas: 200x200px (logotipos), 600x200px (logotipos de email)

Archivos Adjuntos

• PDF, DOC, DOCX, XLS, XLSX, PNG, JPG
• Tamaño máximo: 25MB

Manejo de Errores

• Sin permiso: El ID del objeto no pertenece a tu cuenta o grupo
• Extensión inválida: Tipo de archivo no soportado para este tipo de subida
• Archivo demasiado grande: Excede el límite máximo de tamaño
• Virus detectado: El archivo falló el escaneo de seguridad

Notas de Seguridad

• Las URLs pre-firmadas expiran después de 15 minutos
• Los archivos son escaneados para virus antes de ser procesados
• Solo usuarios con permisos adecuados pueden subir archivos
• Los archivos están aislados durante el procesamiento en el bucket de limpieza

Buenas Prácticas

1. Siempre revisa el tamaño del archivo antes de subirlo
2. Usa el formato de archivo correcto
3. Maneja los errores con cuidado
4. No reutilices URLs pre-firmadas
5. Mantén tus credenciales seguras: nunca compartas tokens de autenticación ni los incluyas en código del lado cliente