Télécharger des fichiers sur la plateforme

De nombreuses tâches nécessitent que vous fournissiez un fichier à la plateforme Legalesign, comme un fichier à utiliser
comme modèle ou une image à utiliser pour une signature.

La plateforme exige que vous placiez ce fichier dans le bon sous-dossier de notre système de clearing. Cela
vérifiera votre fichier pour d’éventuels problèmes de sécurité et le transmettra à l’emplacement correct pour son
usage.

Téléchargement de modèles

Si vous souhaitez télécharger un document modèle, utilisez plutôt le guide dédié Upload a File as a Template. Ce processus utilise désormais l’uploadUrl retourné par createTemplate.

Ce que vous apprendrez

Ce guide vous expliquera comment télécharger des fichiers sur Legalesign. Ne vous inquiétez pas si vous êtes novice en APIs ou en stockage cloud — nous expliquerons chaque étape clairement.

Qu’est-ce qu’une URL pré-signée ?

Une URL pré-signée est comme un pass d’accès temporaire. Au lieu de vous donner un accès permanent à notre stockage, nous vous donnons une URL spéciale qui :

• Ne fonctionne que pendant une courte période (15 minutes)
• Vous permet de télécharger un fichier spécifique uniquement
• Garde vos fichiers en sécurité

Pensez-y comme un ticket de voiturier — il donne un accès temporaire et limité pour un usage précis.

Qu’est-ce que S3 ?

S3 (Simple Storage Service) est le service de stockage cloud d’Amazon. C’est là que nous stockons en toute sécurité vos documents, logos et autres fichiers. Vous n’avez pas besoin de comprendre S3 en détail — sachez simplement que c’est un endroit sécurisé pour stocker des fichiers dans le cloud.

Vue d’ensemble

Le processus de téléchargement suit ces étapes :

1. Demander une URL de téléchargement pré-signée via l’API GraphQL (demander la permission de télécharger)
2. Télécharger votre fichier vers S3 en utilisant l’URL fournie (envoyer réellement le fichier)
3. La plateforme traite et valide automatiquement le fichier (nous vérifions qu’il est sûr)
4. Le fichier est déplacé vers sa destination finale (nous le plaçons au bon endroit)

Pourquoi ce processus en deux étapes ?

Vous vous demandez peut-être pourquoi nous ne vous laissons pas simplement télécharger directement. Ce processus en deux étapes :

• Assure que vous avez la permission de télécharger
• Empêche les téléchargements non autorisés
• Nous permet de scanner les fichiers pour les virus
• Suit qui a téléchargé quoi

Étape 1 : Demander l’URL de téléchargement

Utilisez la requête upload pour obtenir une URL pré-signée pour votre téléchargement de fichier (ici un PDF). Consultez notre guide d’authentification pour plus d’informations sur la façon de commencer à exécuter des requêtes GraphQL. Pour une description complète des arguments, voyez la référence de la requête upload.

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

Explication des paramètres

• id : ID de l’objet encodé en Base64 (ex. ID du modèle, ID de l’expérience)
• uploadType : Type de fichier téléchargé (voir ci-dessous)
• extension : Extension du fichier (pdf, png, jpg)

Types de téléchargement

• TEMPLATE - Fichiers PDF pour modèles de documents
• LOGO - Images pour le branding des pages de signature
• EMAILLOGO - Images pour le branding des emails
• ATTACHMENT - Fichiers additionnels à joindre aux documents

Voir l’enum UploadType pour la liste complète.

Étape 2 : Télécharger vers S3

La requête renvoie une URL pré-signée. Envoyez votre fichier à cette URL en utilisant une requête HTTP PUT :

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

Étape 3 : Traitement automatique

Une fois téléchargé, la plateforme :

1. Scanne le fichier pour détecter virus et menaces de sécurité
2. Valide le format et le contenu du fichier
3. Traite le fichier (ex. extrait les dimensions des pages des PDF)
4. Le déplace vers l’emplacement de stockage final avec les permissions appropriées

Suivre le traitement en temps réel

Si vous avez besoin d’un retour en temps réel après la fin du téléchargement vers S3, utilisez les souscriptions GraphQL.

• Les événements de téléchargement sont transmis via subscribeUserFeed
• Ils utilisent category: "upload"
• Les événements typiques incluent uploadScanned, uploadTypeChecked, uploadCompleted, et uploadFailed

Voir Suivre la progression du téléchargement avec les souscriptions.

Exemple complet

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

Format du chemin

Les fichiers suivent cette convention de nommage :

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

Exemple :

template/usr123abc/dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx.pdf

remarque

Vous n’avez pas besoin de créer ce chemin vous-même - l’API le gère automatiquement lorsque vous fournissez les bons paramètres.

Types de fichiers supportés

Modèles

• Fichiers PDF uniquement
• Taille maximale : 50 Mo

Logos et Logos pour Email

• PNG, JPG, JPEG
• Taille maximale : 5 Mo
• Dimensions recommandées : 200x200px (logos), 600x200px (logos emails)

Pièces jointes

• PDF, DOC, DOCX, XLS, XLSX, PNG, JPG
• Taille maximale : 25 Mo

Gestion des erreurs

• Pas de permission : L’ID de l’objet n’appartient pas à votre compte ou groupe
• Extension invalide : Type de fichier non supporté pour ce type de téléchargement
• Fichier trop volumineux : Taille dépasse la limite maximale
• Virus détecté : Le fichier a échoué au scan de sécurité

Notes de sécurité

• Les URLs pré-signées expirent après 15 minutes
• Les fichiers sont scannés pour détecter les virus avant traitement
• Seuls les utilisateurs avec les permissions appropriées peuvent télécharger des fichiers
• Les fichiers sont isolés pendant le traitement dans le bucket de clearing

Bonnes pratiques

1. Vérifiez toujours la taille du fichier avant de le télécharger
2. Utilisez le bon format de fichier
3. Gérez les erreurs avec soin
4. Ne réutilisez pas les URLs pré-signées
5. Gardez vos identifiants sécurisés — ne partagez jamais les tokens d’authentification ni ne les intégrez dans du code côté client