Datei als Vorlage hochladen

Dieser Leitfaden führt Sie durch den vollständigen Prozess der Erstellung einer Vorlage und das Hochladen einer PDF-, Bild- oder Word-Datei zur Verwendung als Ihre Dokumentvorlage in Legalesign.

Was Sie Lernen Werden

Am Ende dieses Leitfadens wissen Sie, wie Sie:

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

Voraussetzungen

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

• Ein Legalesign-Konto mit API-Zugriff
• 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 vollständige Prozess

Schritt 1: Erstellen einer Vorlage

Zuerst erstellen Sie eine leere Vorlage in Legalesign. Dies gibt sowohl die Template-ID als auch eine vorab signierte Upload-URL für den PDF-Upload zurück. Dafür müssen Sie eine GraphQL-Mutation ausführen; falls Sie dies noch nicht gemacht haben, sehen Sie sich die Einführung in GraphQL an.

Was ist eine Vorlage?

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

• Signaturfelder und Formularfelder hinzufügen
• Sie an mehrere Empfänger senden
• Für verschiedene 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-kodierte ID Ihrer Gruppe/Ihres Arbeitsbereichs (diese finden Sie in der URL in der Console https://console.legalesign.com/)
• title: Ein beschreibender Name für Ihre Vorlage (kann später geändert werden)

Schritt 2: Extrahieren der Template-ID und Upload-URL

Die Mutation liefert ein templateCreateOutput-Objekt zurück. Speichern Sie das Feld id und die Zeichenkette uploadUrl.

Beispielantwort:

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

Tipp

Die Template-ID ist eine Base64-codierte Zeichenfolge. Speichern Sie beide Werte aus der Antwort. Die uploadUrl ist zeitlich begrenzt und sollte zeitnah genutzt werden.

Schritt 3: Hochladen Ihrer PDF

Verwenden Sie die zurückgegebene uploadUrl, um Ihre PDF-Datei direkt auf S3 hochzuladen. Dies variiert je nach Ihrer Entwicklungsumgebung. In unserem JavaScript-Beispiel haben wir fetch verwendet, aber Sie können auch andere Bibliotheken wie aws-amplify nutzen.

Vollständige funktionierende Beispiele

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. Scannt nach Viren – stellt sicher, dass die Datei sicher ist
2. Validiert oder konvertiert die Datei – prüft, ob PDFs gültig sind, oder konvertiert unterstützte Dateien wie Word-Dokumente und Bilder in PDF
3. Extrahiert Seiteninformationen – ermittelt Seitenanzahl und Dimensionen
4. Verarbeitet die Datei – optimiert sie für Anzeige 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!

Upload-Fortschritt verfolgen

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

Alternativ können Sie das Feld fileUploaded der Vorlage abfragen, bis es true zurückgibt:

query CheckUploadStatus($id: ID!) {
  template(id: $id) {
    id
    fileUploaded
  }
}

Hinzufügen von Signaturen und Feldern

Wenn Sie Teilnehmer und Feldplatzierung 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, Signaturfelder und Formularfelder automatisch während der Verarbeitung erstellt werden können. Siehe die REST-API-Erklärung im Quickstart-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 Vorlagenvorbereitungsprozesses verwenden.

Nächste Schritte

Jetzt, da Sie eine Vorlage mit einer PDF haben, können Sie:

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

Häufige Probleme und Lösungen

"Keine Berechtigung" Fehler

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

"Datei zu groß" Fehler

Komprimieren Sie Ihre PDF – das Maximum beträgt 50MB.

Upload-URL abgelaufen

Verwenden Sie die uploadUrl, die von createTemplate zurückgegeben wird, zeitnah. Wenn sie vor dem Upload abläuft, fordern Sie eine neue URL mit der upload Anfrage unter Verwendung der gespeicherten Template-ID an.

"Ungültige PDF" Fehler

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