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.

Téléchargements de modèles

Si vous souhaitez télécharger un document modèle, utilisez plutôt le guide dédié Télécharger un fichier comme modèle. Ce flux utilise désormais l’uploadUrl retournée 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 débutez avec les API ou le stockage cloud – nous expliquerons chaque étape clairement.

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

Une URL pré-signée est comme un laissez-passer temporaire. Plutôt que de vous donner un accès permanent à notre stockage, nous vous fournissons une URL spéciale qui :

• Ne fonctionne que pour une courte durée (15 minutes)
• Ne vous permet de télécharger qu’un fichier spécifique
• Garde vos fichiers sécurisés

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 de fichiers cloud d’Amazon. C’est là où nous stockons en 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.

Aperçu

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

1. Demandez une URL de téléchargement pré-signée via l’API GraphQL (demandez la permission de télécharger)
2. Téléchargez votre fichier vers S3 en utilisant l’URL fournie (envoyez 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 télécharger directement. Ce processus en deux étapes :

• Garantit 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 détecter des virus
• Permet de suivre qui a téléchargé quoi

Étape 1 : Demander une 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 les détails complets 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 d’objet encodé en Base64 (par exemple, ID modèle, ID expérience)
• uploadType : Type de fichier téléchargé (voir ci-dessous)
• extension : Extension de fichier (pdf, png, jpg)

Types de téléchargement

• TEMPLATE - Fichiers PDF pour modèles de documents
• LOGO - Images pour la marque de la page de signature
• EMAILLOGO - Images pour la marque dans les emails
• ATTACHMENT - Fichiers supplémentaires à joindre aux documents

Voir l’énumération UploadType pour la liste complète.

Étape 2 : Télécharger vers S3

La requête retourne une URL pré-signée. Envoyez votre fichier à cette URL via 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 à la recherche de virus et menaces de sécurité
2. Valide le format et le contenu du fichier
3. Traite le fichier (par exemple, extrait les dimensions des pages pour les PDF)
4. Le déplace vers son emplacement 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 sur S3, utilisez les abonnements GraphQL.

• Les événements de téléchargement sont transmis par 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 abonnements.

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 pris en charge

Modèles

• Uniquement fichiers PDF
• Taille maximale : 50Mo

Logos et logos pour email

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

Pièces jointes

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

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 : Dépasse la limite de taille maximale
• Virus détecté : Le fichier a échoué au scan de sécurité

Notes de sécurité

• Les URL pré-signées expirent après 15 minutes
• Les fichiers sont scannés pour 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 nettoyage

Meilleures pratiques

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