Zum Hauptinhalt springen

Datei als Vorlage hochladen

Dieser Leitfaden führt Sie durch den vollständigen Prozess, eine Vorlage zu erstellen und eine PDF-, Bild- oder Word-Datei hochzuladen, die Sie als Dokumentvorlage in Legalesign verwenden können.

What You'll Learn​

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, ob der Upload erfolgreich war

Prerequisites​

Bevor Sie beginnen, stellen Sie sicher, dass Sie:

  • Ein Legalesign-Konto mit API-Zugriff haben
  • 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)

The Complete Process​

Step 1: Create a Template​

Erstellen Sie zuerst 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. Dazu müssen Sie eine GraphQL-Mutation ausführen; wenn Sie das noch nicht getan haben, sehen Sie sich die Einführung in GraphQL an.

What is a Template?​

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

  • Signaturfelder und Formularfelder hinzufügen
  • Diese an mehrere Empfänger senden
  • Sie für verschiedene Unterzeichner wiederverwenden

GraphQL Mutation​

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

Input Variables​

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

Parameters Explained​

  • groupId: Die Base64-codierte ID Ihrer Gruppe/Ihres Arbeitsbereichs (Sie finden diese in der URL in der Console https://console.legalesign.com/)
  • title: Ein beschreibender Name für Ihre Vorlage (kann später geändert werden)
  • uploadOptions (optional): Verarbeitungsoptionen, die beim Hochladen der PDF angewendet werden:
    • pdfFieldsImport: true — eingebettete PDF-Formularfelder als Vorlagenfelder importieren
    • processTags: true — Legalesign-Text-Tags im Dokument beim Hochladen verarbeiten

Step 2: Extract the Template ID and Upload URL​

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

Beispielantwort:

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

Die Template-ID ist eine Base64-kodierte Zeichenfolge. Speichern Sie beide Werte aus der Antwort. Die uploadUrl ist nur kurz gültig und sollte schnell genutzt werden.

Step 3: Upload Your PDF​

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

Complete Working Examples​

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.

What Happens After Upload?​

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

  1. Scannt nach Viren – stellt sicher, dass die Datei sicher ist
  2. Validiert oder konvertiert die Datei – prüft PDFs auf Gültigkeit oder konvertiert unterstützte Dateien wie Word-Dokumente und Bilder in PDF
  3. Extrahiert Seiteninformationen – ermittelt Seitenanzahl und Abmessungen
  4. Verarbeitet die Datei – optimiert sie für die Anzeige und das Signieren
  5. Speichert sie sicher – verschiebt sie in die dauerhafte Speicherung

Dieser Prozess dauert in der Regel nur wenige Sekunden. Nach Abschluss ist Ihre Vorlage einsatzbereit!

Track Upload Progress​

Um Feedback in Echtzeit zum Upload-Prozess (Scanning, Validierung, Abschluss) zu erhalten, verwenden Sie Subscriptions. Siehe Track Upload Progress with Subscriptions.

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

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

Adding Signatures and Fields​

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 bei der Verarbeitung automatisch erstellt werden. Übergeben Sie uploadOptions: { processTags: true } in der createTemplate-Mutation, um dies zu aktivieren. Siehe die REST-API-Erklärung im Schnelleinstieg-Tutorial und den Endpunkt-Referenztext Convert text tags.
  • Eingebettete PDF-Felder — Wenn Ihre PDF bereits eingebettete Formularfelder enthält, übergeben Sie uploadOptions: { pdfFieldsImport: true } in der createTemplate-Mutation, um diese automatisch als Vorlagenfelder zu importieren.

Next Steps​

Jetzt, wo Sie eine Vorlage mit 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 Signieren senden – Verwenden Sie die send-Mutation, um es an Empfänger zu senden

Common Issues and Solutions​

"No permission" Error​

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

"File too large" Error​

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

Upload URL Expired​

Verwenden Sie die von createTemplate zurückgegebene uploadUrl zeitnah. Wenn sie vor dem Upload abläuft, fordern Sie mit der gespeicherten Template-ID eine neue URL über die upload-Abfrage an.

"Invalid PDF" Error​

Öffnen Sie die PDF in einem PDF-Reader, um ihre Gültigkeit zu prüfen; exportieren oder speichern Sie sie dann erneut.