So erstellst Du Deine erste eigene Vorlage für AGYNAMIX® Invoicer

AGYNAMIX® Invoicer 1.7.2 führt experimentelle Vorlagenpakete für Verkaufsdokumente und Zeitnachweise ein. Als kleiner Vorgeschmack auf die kommende Version zeigt dieser Leitfaden den kürzesten praktischen Weg vom Starterpaket zu Deinem ersten eigenen Rechnungslayout.

Die Funktion richtet sich an Menschen, die mit Quelldateien arbeiten können. Eine eigene Vorlage entsteht nicht in einem visuellen Drag-and-drop-Editor. Sie ist ein validiertes ZIP-Paket aus Manifest, Pebble/XHTML-Vorlage, CSS und optional eigenen Bildern und Schriften. Invoicer prüft das Paket und rendert vor der Installation mehrere PDF-Vorschauen.

Hier ist der professionelle Starter für Verkaufsdokumente auf ein kompaktes Rechnungsszenario angewendet. Daten, Summen, Beschriftungen und Steuerdarstellung stammen aus Invoicer; das Paket bestimmt die visuelle Komposition.

Mit dem richtigen Paket beginnen

Für ein erstes echtes Design ist ein gepflegtes Starterpaket der bessere Ausgangspunkt als ein leeres Verzeichnis:

• Template-API-v1-Starter für Verkaufsdokumente herunterladen
• Template-API-v1-Starter für Zeitnachweise herunterladen

Die Pakete bleiben getrennt, weil ein Paket genau eine Vorlagenart und einen Einstiegspunkt besitzt. Dieser Artikel folgt dem Weg für Verkaufsdokumente. Damit lassen sich Angebote, Lieferscheine, Rechnungen, Rechnungskorrekturen und Mahnungen abdecken.

Entpacke den Starter für Verkaufsdokumente in ein Arbeitsverzeichnis. Seine wesentliche Struktur sieht so aus:

manifest.json
document.peb
styles.css
images/
fonts/

Die Verzeichnisse images/ und fonts/ sind optional. Das kleinste Lernbeispiel benötigt nur manifest.json, document.peb und styles.css.

Zuerst das Manifest verstehen

manifest.json beschreibt das Paket, bevor Invoicer Vorlagenmarkup liest. Es deklariert unter anderem:

• eine stabile packageId in umgekehrter DNS-Schreibweise für die Designlinie
• einen lesbaren displayName
• sales_document als Vorlagenart
• document.peb als Einstiegspunkt
• Version 1 der Template API
• die unterstützten Verkaufsdokumentfamilien
• jede im Paket enthaltene CSS-, Bild- und Schriftressource

Gib Deinem Design eine eigene Paket-ID und einen eigenen Namen. Halte die deklarierten Ressourcenpfade mit den Dateien im ZIP synchron: Eine nicht deklarierte oder fehlende Datei ist ein Kompatibilitätsfehler und wird vom Renderer nicht stillschweigend übergangen.

Geschäftsdaten bleiben Aufgabe von Invoicer

Die Pebble-Vorlage steuert Struktur und Darstellung, soll aber keine Rechnungslogik nachbauen. Invoicer liefert vorbereitete Anzeigewerte für Dokumentnummern, Datumsangaben, Mengen, Geldbeträge, lokalisierte Beschriftungen, Steuerdarstellung und Summen.

Die zentralen Wurzeln haben klar getrennte Aufgaben:

• common enthält gemeinsame Werte wie Sprache, Empfänger, Mandant, Beschriftungen und vorbereitete Ressourcen
• document enthält das aktuelle Verkaufsdokument und seine vorbereiteten Positionen
• settings enthält die Layouteinstellungen, die das Paket laut Manifest berücksichtigt
• components stellt anwendungseigene Bereiche wie die Finanzübersicht bereit

Eine Vorlage durchläuft zum Beispiel document.items und zeigt item.lineTotal an; sie berechnet den Positionsbetrag nicht erneut. Die Finanzübersicht wird über die reservierte Anwendungskomponente eingebunden:

{% if components.financialSummary.available %}
  {% include "invoicer/components/v1/financial-summary.peb" %}
{% endif %}

Diese Trennung ist wichtig. Dein Paket verantwortet Aussehen, Formulierungen und Anordnung. Invoicer bleibt für Finanzberechnungen, Steuerentscheidungen, Lokalisierung, striktes Rendering, PDF/A-Verarbeitung und die Erzeugung eingebetteter E-Rechnungen zuständig.

Die ersten visuellen Änderungen gehören ins CSS

Lass die Vorlagenstruktur für den ersten Durchlauf stehen und ändere zunächst die Bereiche, die sich leicht prüfen lassen:

1. Farben und Linien
2. Abstände und Seitenränder
3. Schriftgrößen und Überschriften
4. die Anordnung vorbereiteter Felder
5. paketlokale Bilder

Der professionelle Starter zeigt eine auf jeder Seite wiederholte Informationsspalte, einen Seitenzähler, das von der Anwendung bereitgestellte Mandantenlogo und paketlokale Schriften. Seine Beispielsignatur lautet gut erkennbar M. Mustermann; sie ist fiktiv und sollte ersetzt oder entfernt werden, bevor das Paket für Kundendokumente verwendet wird.

Wenn Du ein Bild hinzufügst, deklarierst Du seinen normalisierten relativen Pfad in manifest.json und referenzierst die Datei aus XHTML oder CSS. Für Schriften verwendest Du deklarierte statische TrueType-Varianten, deren Lizenz die Einbettung und Weitergabe erlaubt. Netzwerkressourcen, lokale Datei-URLs, JavaScript und vom Paket erzeugte Inline-Ressourcen mit data: gehören nicht zum Autorenvertrag.

Die Erste-Schritte-Anleitung enthält außerdem ein bewusst kleines Beispiel. Es hilft dabei, den Mindestvertrag zu verstehen, bevor Du zum umfangreicheren Starterdesign zurückkehrst:

Das ZIP richtig erstellen

Erstelle das ZIP aus dem Paketverzeichnis heraus. manifest.json muss direkt im Archivstamm liegen; packe nicht das umgebende Verzeichnis ein.

deine-vorlage.zip
├── manifest.json
├── document.peb
├── styles.css
├── images/
└── fonts/

Eintragsreihenfolge, Zeitstempel, Komprimierung und Berechtigungen des ZIPs bestimmen nicht die installierte Revision. Invoicer validiert die logischen Paketinhalte und speichert eine unveränderliche, inhaltsadressierte Revision. Veröffentlichte Dokumente verweisen weiterhin auf genau die Revision, mit der sie erzeugt wurden.

Vor der Installation prüfen

Öffne in Invoicer den passenden Editor für Layoutvorlagen und wähle den Import eines eigenen Pakets. Die Prüfung validiert das ZIP und rendert vor der Installation die zutreffenden Vorschauszenarien. Fehlende Variablen, fehlende Ressourcen, nicht unterstütztes Markup und unsichere Quellkonstrukte werden ausdrücklich gemeldet.

Beende die Prüfung nicht nach einer einzigen ansprechenden Rechnung. Kontrolliere vor der Übernahme jede Dokumentfamilie, die Du unterstützen möchtest, beide relevanten Sprachen, lange Adressen und Beschreibungen, optionale Werte und mehrseitige Ausgaben. Erfolgreiches Rendering belegt die Vertragskompatibilität, ist aber keine rechtliche oder visuelle Freigabe des erzeugten Kundendokuments.

Das Material für Version 1 griffbereit halten

Die vollständige Anleitung und die generierte Feldreferenz stehen als versionierte PDFs bereit:

• Template API v1: Erste Schritte (PDF)
• Template API v1: API-Referenz (PDF)
• Starter-ZIP für Verkaufsdokumente
• Starter-ZIP für Zeitnachweise

Eigene Vorlagenpakete sind in der kommenden Version AGYNAMIX® Invoicer 1.7.2 sowohl für den Einzelplatz- als auch für den Client-Server-Betrieb enthalten. Die Template API v1 bleibt in dieser Version experimentell. Teste Dein Paket deshalb vor der Übernahme jeder neuen Anwendungsversion erneut.

Wenn Du AGYNAMIX® Invoicer praktisch ausprobieren willst, findest Du die Anwendung hier: AGYNAMIX® Invoicer.