Subir archivos a la plataforma

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

La plataforma requiere que coloques este archivo en la subcarpeta correcta de nuestro sistema de clearing. Esto evaluará tu archivo en busca de posibles problemas de seguridad y lo enviará a la ubicación correcta para su propósito.

Cargas de plantilla

Si deseas cargar un documento plantilla, utiliza 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á en la carga de archivos a Legalesign. No te preocupes si eres nuevo en APIs o almacenamiento en la nube: explicaremos cada paso claramente.

¿Qué es una URL Pre-Firmada?

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

• Sólo funciona por un corto tiempo (15 minutos)
• Sólo permite cargar un archivo específico
• Mantiene tus archivos seguros

Piénsalo 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 almacenamiento de archivos en la nube de Amazon. Es donde guardamos de forma segura tus documentos, logos y otros archivos. No necesitas entender S3 en detalle, solo sabe que es un lugar seguro para almacenar archivos en la nube.

Visión General

El proceso de carga sigue estos pasos:

1. Solicitar una URL de carga pre-firmada 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 automáticamente y valida el archivo (verificamos que sea seguro)
4. El archivo se mueve a su destino final (lo colocamos en el lugar correcto)

¿Por qué este proceso de dos pasos?

Quizás te preguntes por qué no te dejamos subir directamente. Este proceso de dos pasos:

• Garantiza que tienes permiso para subir
• Previene cargas no autorizadas
• Nos permite escanear archivos en busca de virus
• Lleva un registro de quién subió qué

Paso 1: Solicitar URL de Carga

Usa la consulta upload para obtener una URL pre-firmada para la carga de tu archivo (en este caso un PDF). Consulta nuestra guía de autenticación para más información sobre cómo comenzar a ejecutar consultas GraphQL. Para detalles completos de 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 subirá (ver debajo)
• extension: Extensión del archivo (pdf, png, jpg)

Tipos de Carga

• TEMPLATE - Archivos PDF para plantillas de documentos
• LOGO - Imágenes para el diseño de la página de firma
• EMAILLOGO - Imágenes para el diseño de correo electrónico
• ATTACHMENT - Archivos adicionales para adjuntar a documentos

Consulta el enum UploadType para la lista completa.

Paso 2: Cargar a S3

La consulta devuelve una URL pre-firmada. Envía tu archivo a esta URL usando una solicitud 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 cargado, 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

Rastrea el Procesamiento en Tiempo Real

Si necesitas retroalimentación en tiempo real después de que la carga a S3 termine, usa suscripciones GraphQL.

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

Consulta Rastrea el progreso de la carga 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 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 lo maneja automáticamente cuando proporcionas los parámetros correctos.

Tipos de Archivo Soportados

Plantillas

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

Logos y Logos de Correo Electrónico

• PNG, JPG, JPEG
• Tamaño máximo: 5MB
• Dimensiones recomendadas: 200x200px (logos), 600x200px (logos de correo electrónico)

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 carga
• 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 en busca de virus antes del procesamiento
• Solo usuarios con permisos adecuados pueden subir archivos
• Los archivos están aislados durante el procesamiento en el bucket de clearing

Mejores Prácticas

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