Carica file sulla piattaforma

Molti compiti richiedono di fornire un file da utilizzare sulla piattaforma Legalesign, come un file da usare come modello o un'immagine da utilizzare per una firma.

Caricamenti di modelli

Se desideri caricare un documento modello, usa la guida dedicata Carica un file come modello. Questo flusso ora utilizza uploadUrl restituito da createTemplate.

Cosa Imparerai

Questa guida ti accompagnerà nel caricamento di file su Legalesign. Non preoccuparti se sei nuovo alle API o allo storage cloud - spiegheremo ogni passaggio chiaramente.

Cos'è un URL Pre-Firmato?

Un URL pre-firmato è come un pass temporaneo di accesso. Invece di darti accesso permanente al nostro storage, ti forniamo un URL speciale che:

• Funziona solo per un breve periodo (15 minuti)
• Ti permette di caricare un solo file specifico
• Mantiene i tuoi file al sicuro

Pensalo come un biglietto per il parcheggio valet - fornisce accesso temporaneo e limitato per uno scopo specifico.

Cos'è S3?

S3 (Simple Storage Service) è lo storage file cloud di Amazon. È il luogo dove conserviamo in sicurezza i tuoi documenti, loghi e altri file. Non devi conoscere i dettagli di S3 - sappi solo che è un posto sicuro per archiviare file nel cloud.

Panoramica

Il processo di caricamento segue questi passaggi:

1. Richiedi un URL di caricamento pre-firmato dall'API GraphQL (chiedi il permesso di caricare)
2. Carica il tuo file su S3 usando l'URL fornito (invia effettivamente il file)
3. La piattaforma elabora e valida automaticamente il file (verifichiamo che sia sicuro)
4. Il file viene spostato nella sua destinazione finale (lo mettiamo nel posto giusto)

Perché questo processo in due fasi?

Potresti chiederti perché non permettiamo il caricamento diretto. Questo processo in due fasi:

• Ti assicura il permesso di caricare
• Previene caricamenti non autorizzati
• Ci consente di scansionare i file per virus
• Tiene traccia di chi ha caricato cosa

Passo 1: Richiedi URL di Caricamento

Usa la query upload per ottenere un URL pre-firmato per il caricamento del tuo file (in questo caso un PDF). Consulta la nostra guida all'autenticazione per maggiori informazioni su come iniziare a eseguire query GraphQL. Per i dettagli completi degli argomenti, vedi la riferimento query upload.

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

Spiegazione dei Parametri

• id: ID dell'oggetto codificato in Base64 (es. ID modello, ID esperienza)
• uploadType: Il tipo di file che stai caricando (vedi sotto)
• extension: Estensione del file (pdf, png, jpg)

Tipi di Caricamento

• TEMPLATE - File PDF per modelli di documento
• LOGO - Immagini per il branding della pagina di firma
• EMAILLOGO - Immagini per il branding delle email
• ATTACHMENT - File aggiuntivi da allegare ai documenti

Vedi UploadType enum per l'elenco completo.

Passo 2: Carica su S3

La query restituisce un URL pre-firmato. Invia il tuo file a questo URL usando una richiesta HTTP PUT:

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

Passo 3: Elaborazione Automatica

Una volta caricato, la piattaforma:

1. Scansiona il file per virus e minacce alla sicurezza
2. Valida il formato e il contenuto del file
3. Elabora il file (es. estrae le dimensioni delle pagine per i PDF)
4. Lo sposta nella posizione di storage finale con i permessi appropriati

Segui l'Elaborazione in Tempo Reale

Se ti serve un feedback in tempo reale dopo il completamento del caricamento su S3, usa le subscription GraphQL.

• Gli eventi di caricamento sono consegnati su subscribeUserFeed
• Usano category: "upload"
• Gli eventi tipici includono uploadScanned, uploadTypeChecked, uploadCompleted e uploadFailed

Vedi Traccia il progresso del caricamento con le subscription.

Esempio 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 del Percorso

I file seguono questa convenzione di denominazione:

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

Esempio:

template/usr123abc/dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx.pdf

nota

Non devi creare questo percorso da solo - l'API lo gestisce automaticamente quando fornisci i parametri corretti.

Tipi di File Supportati

Modelli

• Solo file PDF
• Dimensione massima: 50MB

Loghi e Loghi Email

• PNG, JPG, JPEG
• Dimensione massima: 5MB
• Dimensioni consigliate: 200x200px (loghi), 600x200px (loghi email)

Allegati

• PDF, DOC, DOCX, XLS, XLSX, PNG, JPG
• Dimensione massima: 25MB

Gestione degli Errori

• Nessun permesso: L'ID oggetto non appartiene al tuo account o gruppo
• Estensione non valida: Tipo di file non supportato per questo tipo di caricamento
• File troppo grande: Supera il limite massimo di dimensione
• Virus rilevato: Il file non ha superato la scansione di sicurezza

Note di Sicurezza

• Gli URL pre-firmati scadono dopo 15 minuti
• I file sono scansionati per virus prima dell'elaborazione
• Solo gli utenti con permessi adeguati possono caricare file
• I file sono isolati durante l'elaborazione nel bucket di clearing

Best Practice

1. Controlla sempre la dimensione del file prima di caricare
2. Usa il formato file corretto
3. Gestisci gli errori con attenzione
4. Non riutilizzare gli URL pre-firmati
5. Mantieni sicure le tue credenziali — non condividere mai i token di autenticazione o incorporarli nel codice client-side