Datei als Vorlage hochladen

Dieser Leitfaden führt Sie durch den kompletten Prozess der Erstellung einer Vorlage und dem Hochladen einer PDF-, Bild- oder Word-Datei, um diese als Ihre Dokumentvorlage in Legalesign zu verwenden.

Tipp

Brauchen Sie Echtzeit-Feedback zur Verarbeitung des Uploads? Siehe Upload-Fortschritt mit Subscriptions verfolgen.

Was Sie lernen werden

Am Ende dieses Leitfadens wissen Sie, wie Sie:

1. Eine neue Vorlage in Ihrer Legalesign-Gruppe erstellen
2. Die Vorlagen-ID und die Upload-URL aus der Mutationsantwort erhalten
3. Ihre Quelldatei in die Vorlage hochladen
4. Überprüfen, ob der Upload erfolgreich war

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass Sie haben:

• Ein Legalesign-Konto mit API-Zugang
• Ihre Authentifizierungsdaten (siehe unseren Authentifizierungsleitfaden)
• Eine PDF-, Bild- oder Word-Datei zum Hochladen bereit (maximal 50MB)
• Ihre Gruppen-ID (der Arbeitsbereich, in dem Sie die Vorlage erstellen möchten)

Der komplette Prozess

Schritt 1: Eine Vorlage erstellen

Erstellen Sie zuerst eine leere Vorlage in Legalesign. Dies liefert sowohl die Vorlagen-ID als auch eine vorab signierte Upload-URL für den PDF-Upload. Dazu müssen Sie eine GraphQL-Mutation ausführen. Wenn Sie dies noch nicht getan haben, sehen Sie sich die Einführung in GraphQL an.

Was ist eine Vorlage?

Eine Vorlage ist eine wiederverwendbare Dokumentenstruktur in Legalesign. Sobald Sie eine PDF in eine Vorlage hochgeladen haben, können Sie:

• Unterschriftsfelder und Formularfelder hinzufügen
• Sie an mehrere Empfänger senden
• Sie für unterschiedliche Unterzeichner wiederverwenden

GraphQL-Mutation

mutation CreateTemplate($input: templateCreateInput!) {
  createTemplate(input: $input) {
    id
    uploadUrl
  }
}

Eingabevariablen

{
  "input": {
    "groupId": "grpYourGroupAPIId",
    "title": "Employment Contract Template"
  }
}

Parameter erklärt

• groupId: Die Base64-ID Ihrer Gruppe/Ihres Arbeitsbereichs (diese können Sie aus der URL in der Console entnehmen https://console.legalesign.com/)
• title: Ein beschreibender Name für Ihre Vorlage (kann später geändert werden)

Schritt 2: Die Vorlagen-ID und Upload-URL extrahieren

Die Mutation gibt ein templateCreateOutput-Objekt zurück. Speichern Sie das Feld id und den String uploadUrl.

Beispielantwort:

{
  "data": {
    "createTemplate": {
      "id": "dHBsYjQ5YTg5NWQtYWRhMy0xMWYwLWIxZGMtMDY5NzZlZmU0MzIx",
      "uploadUrl": "https://s3.amazonaws.com/bucket/path?signature=..."
    }
  }
}

Tipp

Die Vorlagen-ID ist ein Base64-codierter String. Speichern Sie beide Werte aus der Antwort. Die uploadUrl ist nur kurz gültig und sollte zügig verwendet werden.

Schritt 3: Ihre PDF hochladen

Verwenden Sie die zurückgegebene uploadUrl, um Ihre PDF-Datei direkt an S3 hochzuladen. Dies unterscheidet sich je nach Entwicklungsstack. In unserem JavaScript-Beispiel haben wir fetch verwendet, aber Sie können auch andere Bibliotheken nutzen, z. B. aws-amplify.

Vollständige Arbeitsbeispiele

JavaScript

import fs from 'fs';

const AUTH_TOKEN = '<token-from-authentication-guide>';

const uploadPdfTemplate = async (groupId, title, pdfFilePath) => {
  const graphqlEndpoint = 'https://graphql.uk.legalesign.com/graphql';
  
  // Step 1: Create the template
  console.log('Creating template...');
  const createResponse = await fetch(graphqlEndpoint, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${AUTH_TOKEN}`
    },
    body: JSON.stringify({
      query: `
        mutation CreateTemplate($input: templateCreateInput!) {
          createTemplate(input: $input) {
            id
            uploadUrl
          }
        }
      `,
      variables: {
        input: {
          groupId: groupId,
          title: title
        }
      }
    })
  });
  
  const createResult = await createResponse.json();
  const templateId = createResult.data.createTemplate.id;
  const uploadUrl = createResult.data.createTemplate.uploadUrl;
  console.log('Template created with ID:', templateId);
  
  // Step 2: Upload the PDF
  console.log('Uploading PDF...');
  const fileData = fs.readFileSync(pdfFilePath);
  
  const uploadResponse = await fetch(uploadUrl, {
    method: 'PUT',
    body: fileData,
    headers: {
      'Content-Type': 'application/pdf'
    }
  });
  
  if (!uploadResponse.ok) {
    throw new Error(`Upload failed: ${uploadResponse.statusText}`);
  }
  
  console.log('PDF uploaded successfully!');
  
  return {
    success: true,
    templateId: templateId,
    title: title
  };
};

// Usage example
uploadPdfTemplate(
  'grpYourGroupId',
  'Employment Contract',
  './contract.pdf'
).then(result => {
  console.log('Complete!', result);
}).catch(error => {
  console.error('Error:', error);
});

Keine zusätzlichen Abhängigkeiten erforderlich — Node.js 18+ enthält fetch nativ.

Python

import requests
from gql import gql, Client
from gql.transport.requests import RequestsHTTPTransport

def upload_pdf_template(graphql_endpoint, auth_token, group_id, title, pdf_file_path):
    transport = RequestsHTTPTransport(
        url=graphql_endpoint,
        headers={'Authorization': auth_token}
    )
    client = Client(transport=transport, fetch_schema_from_transport=True)
    
    # Step 1: Create the template
    print('Creating template...')
    create_mutation = gql('''
        mutation CreateTemplate($input: templateCreateInput!) {
            createTemplate(input: $input) {
                id
                uploadUrl
            }
        }
    ''')
    
    create_result = client.execute(
        create_mutation,
        variable_values={
            'input': {
                'groupId': group_id,
                'title': title
            }
        }
    )
    
    template_id = create_result['createTemplate']['id']
    upload_url = create_result['createTemplate']['uploadUrl']
    print(f'Template created with ID: {template_id}')

    # Step 2: Upload the PDF
    print('Uploading PDF...')
    with open(pdf_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(f'Upload failed: {response.status_code}')
    
    print('PDF uploaded successfully!')
    
    return {
        'success': True,
        'templateId': template_id,
        'title': title
    }

if __name__ == '__main__':
    result = upload_pdf_template(
        'https://graphql.uk.legalesign.com/graphql',
        'Bearer YOUR_TOKEN',
        'grpYourGroupId',
        'Employment Contract',
        './contract.pdf'
    )
    print('Complete!', result)

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;
using Newtonsoft.Json.Linq;

public class PdfTemplateUploader
{
    private readonly GraphQLHttpClient graphQLClient;
    
    public PdfTemplateUploader(string graphqlEndpoint, string authToken)
    {
        graphQLClient = new GraphQLHttpClient(graphqlEndpoint, new NewtonsoftJsonSerializer());
        graphQLClient.HttpClient.DefaultRequestHeaders.Add("Authorization", authToken);
    }
    
    public async Task<UploadResult> UploadPdfTemplate(
        string groupId, 
        string title, 
        string pdfFilePath)
    {
        // Step 1: Create the template
        Console.WriteLine("Creating template...");
        var createMutation = new GraphQLRequest
        {
            Query = @"
                mutation CreateTemplate($input: templateCreateInput!) {
                    createTemplate(input: $input) {
                        id
                        uploadUrl
                    }
                }
            ",
            Variables = new
            {
                input = new
                {
                    groupId = groupId,
                    title = title
                }
            }
        };
        
        var createResponse = await graphQLClient.SendMutationAsync<dynamic>(createMutation);
        string templateId = createResponse.Data.createTemplate.id;
        string uploadUrl = createResponse.Data.createTemplate.uploadUrl;
        Console.WriteLine($"Template created with ID: {templateId}");

        // Step 2: Upload the PDF
        Console.WriteLine("Uploading PDF...");
        using var httpClient = new HttpClient();
        var fileBytes = await File.ReadAllBytesAsync(pdfFilePath);
        var content = new ByteArrayContent(fileBytes);
        content.Headers.ContentType = new System.Net.Http.Headers.MediaTypeHeaderValue("application/pdf");
        
        var putResponse = await httpClient.PutAsync(uploadUrl, content);
        
        if (!putResponse.IsSuccessStatusCode)
        {
            throw new Exception($"Upload failed: {putResponse.StatusCode}");
        }
        
        Console.WriteLine("PDF uploaded successfully!");
        
        return new UploadResult
        {
            Success = true,
            TemplateId = templateId,
            Title = title
        };
    }
}

public class UploadResult
{
    public bool Success { get; set; }
    public string TemplateId { get; set; }
    public string Title { get; set; }
}

class Program
{
    static async Task Main(string[] args)
    {
        var uploader = new PdfTemplateUploader(
            "https://graphql.uk.legalesign.com/graphql",
            "Bearer YOUR_TOKEN"
        );
        
        var result = await uploader.UploadPdfTemplate(
            "grpYourGroupId",
            "Employment Contract",
            "./contract.pdf"
        );
        
        Console.WriteLine($"Complete! Template ID: {result.TemplateId}");
    }
}

Was passiert nach dem Upload?

Sobald Ihre PDF hochgeladen ist, führt Legalesign automatisch folgende Schritte durch:

1. Virus-Scan - Stellt sicher, dass die Datei sicher ist
2. Validiert oder konvertiert die Datei - Überprüft, ob PDFs gültig sind, oder konvertiert unterstützte Dateien wie Word-Dokumente und Bilder in PDF
3. Extrahiert Seiteninformationen - Bestimmt Seitenzahl und Abmessungen
4. Verarbeitet die Datei - Optimiert sie für Ansicht und Unterzeichnung
5. Speichert sie sicher - Verschiebt sie in die permanente Speicherung

Dieser Prozess dauert normalerweise nur wenige Sekunden. Nach Abschluss ist Ihre Vorlage einsatzbereit!

Hinzufügen von Unterschriften und Feldern

Wenn Sie Teilnehmer und Feldplatzierungen automatisieren möchten, können Sie die Quelldatei vor dem Upload auf verschiedene Weise vorbereiten:

• Text-Tags - Fügen Sie Legalesign-Text-Tags in das Quelldokument ein, damit Teilnehmer, Unterschriftsfelder und Formularfelder während der Verarbeitung automatisch erstellt werden können. Siehe die REST API-Erklärung im Schnellstart-Tutorial und die Referenz zum Endpunkt Text-Tags konvertieren.
• Eingebettete PDF-Felder - Wenn Ihr PDF bereits eingebettete Formularfelder enthält, kann Legalesign diese als Teil des Upload- und Vorlagenvorbereitungs-Workflows verwenden.

Nächste Schritte

Da Sie jetzt eine Vorlage mit einer PDF haben, können Sie:

1. Unterschriftsfelder hinzufügen - Verwenden Sie die Mutation createTemplateElement, um Felder hinzuzufügen
2. Rollen erstellen - Definieren Sie, wer das Dokument unterzeichnen wird
3. Zum Unterzeichnen senden - Verwenden Sie die Mutation send, um es an Empfänger zu versenden

Häufige Probleme und Lösungen

Fehler „Keine Berechtigung“

Überprüfen Sie, ob Ihre Gruppen-ID korrekt ist und Sie mit dem richtigen Konto authentifiziert sind.

Fehler „Datei zu groß“

Komprimieren Sie Ihr PDF — die maximale Größe beträgt 50MB.

Upload-URL abgelaufen

Verwenden Sie die von createTemplate zurückgegebene uploadUrl zügig. Falls sie vor dem Upload abläuft, fordern Sie eine neue URL mit der upload-Abfrage unter Verwendung der gespeicherten Vorlagen-ID an.

Fehler „Ungültiges PDF“

Öffnen Sie die PDF in einem PDF-Reader, um zu überprüfen, ob sie gültig ist, und exportieren oder speichern Sie sie anschließend erneut.

Upload-Fortschritt verfolgen

Um Echtzeit-Feedback zum Upload-Status (Scan, Validierung, Abschluss) zu erhalten, verwenden Sie Subscriptions. Siehe Upload-Fortschritt mit Subscriptions verfolgen.