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 usare per una firma.

La piattaforma richiede di posizionare questo file nella sotto-cartella corretta del nostro sistema di clearing. Questo
verifica il file per possibili problemi di sicurezza e lo inoltra alla destinazione corretta per il suo
scopo.

Caricamenti di modelli

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

Cosa Imparerai

Questa guida ti accompagnerà nel caricamento dei 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 un 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 sicuri

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

Cos’è S3?

S3 (Simple Storage Service) è lo storage file cloud di Amazon. È dove conserviamo in modo sicuro i tuoi documenti, loghi e altri file. Non è necessario comprendere S3 in dettaglio - basta sapere che è un posto sicuro dove archiviare i file nel cloud.

Panoramica

Il processo di caricamento segue questi passaggi:

Richiedere un URL di caricamento pre-firmato dall’API GraphQL (chiedere il permesso di caricare)
Caricare il file su S3 utilizzando l’URL fornito (inviare effettivamente il file)
La piattaforma processa automaticamente e convalida il file (verifichiamo che sia sicuro)
Il file viene spostato alla destinazione finale (lo mettiamo nel posto giusto)

Perché questo processo in due passaggi?

Ti potresti chiedere perché non lasciamo caricare direttamente. Questo processo in due passaggi:

Garantisce che tu abbia il permesso di caricare
Previene caricamenti non autorizzati
Ci permette di scansionare i file per virus
Tiene traccia di chi ha caricato cosa

Passo 1: Richiedere l’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 sugli argomenti, vedi il riferimento alla query upload.

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

Parametri Spiegati

id: ID oggetto codificato in Base64 (es. ID modello, ID esperienza)
uploadType: Tipo di file che si sta 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 l’enum UploadType per l’elenco completo.

Passo 2: Caricare 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:

Scansiona il file per virus e minacce di sicurezza
Convalida il formato e il contenuto del file
Elabora il file (es. estrae le dimensioni della pagina per i PDF)
Lo sposta alla destinazione finale di archiviazione con le autorizzazioni appropriate

Segui l’Elaborazione in Tempo Reale

Se hai bisogno di un feedback in tempo reale dopo il completamento del caricamento su S3, usa le subscriptions GraphQL.

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

Vedi Seguire il Progresso del Caricamento con le Subscriptions.

Esempio Completo

JavaScript
Python
C#

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 };
};

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}

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 è necessario creare questo percorso manualmente - 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 dell’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 sulla Sicurezza

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

Migliori Pratiche

Controlla sempre la dimensione del file prima di caricarlo
Usa il formato di file corretto
Gestisci gli errori in modo appropriato
Non riutilizzare gli URL pre-firmati
Tieni le tue credenziali al sicuro — non condividere mai i token di autenticazione o inserirli nel codice lato client

Cosa Imparerai​

Cos’è un URL Pre-Firmato?​

Cos’è S3?​

Panoramica​

Perché questo processo in due passaggi?​

Passo 1: Richiedere l’URL di Caricamento​

Parametri Spiegati​

Tipi di Caricamento​

Passo 2: Caricare su S3​

Passo 3: Elaborazione Automatica​

Segui l’Elaborazione in Tempo Reale​

Esempio Completo​

Formato del Percorso​

Tipi di File Supportati​

Modelli​

Loghi e Loghi Email​

Allegati​

Gestione degli Errori​

Note sulla Sicurezza​

Migliori Pratiche​

Export This Article