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:
- Eine neue Vorlage in Ihrer Legalesign-Gruppe erstellen
- Die Template-ID und Upload-URL aus der Mutationsantwort erhalten
- Ihre Quelldatei in die Vorlage hochladen
- Ü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 importierenprocessTags: 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=..."
}
}
}
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
- JavaScript
- Python
- C#
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.
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)
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}");
}
}
What Happens After Upload?
Sobald Ihre PDF hochgeladen ist, führt Legalesign automatisch folgende Schritte aus:
- Scannt nach Viren – stellt sicher, dass die Datei sicher ist
- Validiert oder konvertiert die Datei – prüft PDFs auf Gültigkeit oder konvertiert unterstützte Dateien wie Word-Dokumente und Bilder in PDF
- Extrahiert Seiteninformationen – ermittelt Seitenanzahl und Abmessungen
- Verarbeitet die Datei – optimiert sie für die Anzeige und das Signieren
- 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 dercreateTemplate-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 dercreateTemplate-Mutation, um diese automatisch als Vorlagenfelder zu importieren.
Next Steps
Jetzt, wo Sie eine Vorlage mit PDF haben, können Sie:
- Signaturfelder hinzufügen – Verwenden Sie die
createTemplateElement-Mutation, um Felder hinzuzufügen - Rollen erstellen – Definieren Sie, wer das Dokument unterzeichnen wird
- 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.