Blog

Du betrachtest gerade Zoho Books, Deluge API und Zoho Flow: Automatisierte E-Rechnung für Österreich erstellen

Zoho Books, Deluge API und Zoho Flow: Automatisierte E-Rechnung für Österreich erstellen

  • Beitrags-Autor:

E-Rechnung für Österreich mit Zoho Books: Eine praxisnahe Anleitung zur Automatisierung per API und Deluge

Die Digitalisierung von Geschäftsprozessen schreitet unaufhaltsam voran. Ein Bereich, der davon besonders betroffen ist, ist die Rechnungslegung. Insbesondere im B2G-Sektor (Business-to-Government) werden strukturierte, maschinenlesbare Rechnungsformate zunehmend zum Standard. In Österreich ist dies die sogenannte „E-Rechnung“. Für dich als Zoho-Nutzer stellt sich die Frage: Wie bilde ich diese spezifischen Anforderungen in meinem System ab? Während Zoho Books hervorragende länderspezifische Editionen anbietet, gibt es manchmal Nischen oder neue Standards, für die eine Out-of-the-Box-Lösung fehlt. Dieser Artikel zeigt dir, wie du diese Lücke mit Bordmitteln – konkret mit der Skriptsprache Deluge und den Zoho-APIs – schließt und einen automatisierten Prozess für die Erstellung österreichischer E-Rechnungen aufbaust.

Praxisbeispiel: Die Herausforderung der österreichischen E-Rechnung

Stell dir folgendes typisches Szenario vor: Du betreibst ein Dienstleistungsunternehmen in Österreich und zählst öffentliche Einrichtungen wie Ministerien, Städte oder Landesregierungen zu deinen Kunden. Diese fordern von dir, Rechnungen nicht mehr als PDF per E-Mail, sondern als strukturierte XML-Datei im „ebInterface“-Format über das Unternehmensserviceportal (USP) einzureichen.

Dein Problem: Die österreichische Edition von Zoho Books bietet aktuell keinen direkten Export in diesem speziellen XML-Format. Dein aktueller Workflow ist mühsam und fehleranfällig:

  • Du erstellst die Rechnung wie gewohnt in Zoho Books.
  • Anschließend öffnest du das Webportal der Behörde.
  • Du überträgst alle Rechnungsdaten – Kundendaten, Positionen, Beträge, Steuern – manuell per Copy-and-Paste in das Online-Formular.

Dieser Prozess kostet nicht nur wertvolle Zeit, sondern birgt auch ein hohes Risiko für Tippfehler, die zu Zahlungsverzögerungen oder Rückfragen führen können. Das Ziel ist klar: Die Erstellung der benötigten XML-Datei muss direkt aus Zoho Books heraus automatisiert werden.

Schritt-für-Schritt-Anleitung zur Lösung

Wir bauen die Lösung in mehreren Phasen auf. Zuerst schaffen wir die Datengrundlage, dann implementieren wir die Logik mit einer Custom Function und betrachten abschließend alternative Architekturen.

Phase 1: Das Fundament – Saubere Daten in Zoho CRM und Books

Jede Automatisierung ist nur so gut wie die Daten, auf denen sie basiert. Der erste und wichtigste Schritt ist daher die Sicherstellung einer exzellenten Datenqualität in deinem Zoho CRM, das idealerweise mit Zoho Books synchronisiert ist.

  • Stammdaten prüfen: Stelle sicher, dass für alle relevanten Kunden der korrekte Firmenname, die vollständige Adresse und vor allem die Umsatzsteuer-Identifikationsnummer (UID-Nummer) sauber gepflegt sind.
  • Spezifische Felder anlegen: Öffentliche Auftraggeber verlangen oft eine „Auftragsreferenz“ oder „Bestellnummer“ auf der Rechnung. Lege hierfür ein benutzerdefiniertes Feld im Modul „Kontakte“ oder „Firmen“ in Zoho CRM an (z.B. Auftragsreferenz_B2G).
  • Feld-Mapping: Sorge dafür, dass dieses neue Feld korrekt von Zoho CRM nach Zoho Books synchronisiert wird, sodass es auf dem Rechnungsdatensatz verfügbar ist.

Ohne diese saubere Datengrundlage wird deine Automatisierung später scheitern, da die XML-Datei aufgrund fehlender Pflichtfelder vom Behördenportal abgelehnt wird.

Phase 2: Die Kernlogik – XML-Generierung via Deluge Custom Function

Das Herzstück unserer Lösung ist eine „Custom Function“, geschrieben in Deluge, der Skriptsprache von Zoho. Wir verknüpfen diese Funktion mit einem „Custom Button“ auf der Rechnungsseite in Zoho Books. Ein Klick auf diesen Button löst dann die Generierung der E-Rechnung aus.

Schritt 2.1: Custom Button erstellen

Navigiere in Zoho Books zu Einstellungen > Automatisierung > Benutzerdefinierte Schaltflächen. Erstelle einen neuen Button für das Modul „Rechnungen“ und nenne ihn zum Beispiel „E-Rechnung (XML) generieren“. Wähle als Aktion „Eine neue benutzerdefinierte Funktion schreiben“.

Schritt 2.2: Daten aus der Rechnung abrufen (Deluge)

Im Deluge-Editor müssen wir zuerst alle relevanten Informationen aus der aktuellen Rechnung auslesen. Der Rechnungsdatensatz wird der Funktion automatisch übergeben.


// Die ID der Rechnung, von der aus der Button geklickt wurde
invoiceId = invoice.get("invoice_id");

// Alle Details zur Rechnung über die API abrufen
// Wichtig: 'books' ist der Name Deiner Zoho Books API-Verbindung
invoiceDetails = zoho.books.getRecordsById("invoices", organization.organization_id, invoiceId, "books");

// Kundendaten extrahieren
customerName = invoiceDetails.get("invoice").get("customer_name");
billingAddress = invoiceDetails.get("invoice").get("billing_address").get("address");
billingCity = invoiceDetails.get("invoice").get("billing_address").get("city");
billingZip = invoiceDetails.get("invoice").get("billing_address").get("zip");
vatNumber = invoiceDetails.get("invoice").get("vat_treatment"); // Beispielfeld, muss evtl. vom Kunden geholt werden

// Rechnungsdetails extrahieren
invoiceNumber = invoiceDetails.get("invoice").get("invoice_number");
invoiceDate = invoiceDetails.get("invoice").get("date");
dueDate = invoiceDetails.get("invoice").get("due_date");
total = invoiceDetails.get("invoice").get("total");
subTotal = invoiceDetails.get("invoice").get("sub_total");

// Rechnungspositionen (Line Items) durchlaufen
lineItems = invoiceDetails.get("invoice").get("line_items");
lineItemsXml = "";
for each item in lineItems
{
    itemName = item.get("name");
    quantity = item.get("quantity");
    rate = item.get("rate");
    itemTotal = item.get("item_total");
    
    // Baue einen XML-Block für jede Position
    lineItemsXml = lineItemsXml + "<LineItem><Description>" + itemName + "</Description><Quantity>" + quantity + "</Quantity><UnitPrice>" + rate + "</UnitPrice><LineItemTotal>" + itemTotal + "</LineItemTotal></LineItem>";
}

info "Daten erfolgreich abgerufen.";
Schritt 2.3: XML-Struktur aufbauen

Nun setzen wir die abgerufenen Daten zu einer XML-Struktur zusammen. Das folgende Beispiel ist eine stark vereinfachte Darstellung, um das Prinzip zu verdeutlichen. Für eine produktive Nutzung musst du die exakte Struktur des „ebInterface“-Standards recherchieren und nachbilden.


// XML-Struktur als String zusammenbauen (vereinfachtes Beispiel)
xmlContent = "<?xml version="1.0" encoding="UTF-8"?>";
xmlContent = xmlContent + "<Invoice>";
xmlContent = xmlContent + "<InvoiceNumber>" + invoiceNumber + "</InvoiceNumber>";
xmlContent = xmlContent + "<InvoiceDate>" + invoiceDate + "</InvoiceDate>";
xmlContent = xmlContent + "<Biller><Name>Dein Firmenname</Name><VATID>DeineUID</VATID></Biller>";
xmlContent = xmlContent + "<Customer><Name>" + customerName + "</Name><Address>" + billingAddress + " " + billingZip + " " + billingCity + "</Address></Customer>";
xmlContent = xmlContent + "<ItemList>" + lineItemsXml + "</ItemList>";
xmlContent = xmlContent + "<TotalGross>" + total + "</TotalGross>";
xmlContent = xmlContent + "</Invoice>";

info xmlContent;
Schritt 2.4: XML-Datei erstellen und an die Rechnung anhängen

Der letzte Schritt in unserer Funktion ist, den erzeugten XML-String als Datei zu speichern und diese Datei an den Rechnungsdatensatz in Zoho Books anzuhängen. So hast du die E-Rechnung direkt bei der Originalrechnung archiviert.


// XML-Datei erstellen
fileName = "erechnung_" + invoiceNumber + ".xml";
// Die Zoho API wird aufgerufen, um ein Dokument an die Rechnung anzuhängen
// 'document' ist der Parametername für die Datei
// 'xmlContent.toFile()' konvertiert den String in eine Datei
response = zoho.books.createRecord("invoices", organization.organization_id, {"attachement_details" : {"attachements" : {fileName : xmlContent.toFile()}}}, invoiceId, "attachdocument", "books");

info response;

// Erfolgsmeldung für den Benutzer
return "E-Rechnung wurde erfolgreich generiert und als Anhang hinzugefügt.";

Nach dem Speichern dieser Funktion kannst du auf eine beliebige Rechnung gehen, deinen neuen Button klicken und nach kurzer Zeit erscheint die generierte XML-Datei im Anhang der Rechnung. Du kannst sie herunterladen und im Behördenportal hochladen.

Phase 3 (Alternative): Entkopplung mit Zoho Flow und externen APIs

Das Erstellen komplexer XML-Strukturen direkt in Deluge kann unübersichtlich werden. Eine sauberere und flexiblere Architektur ist die Auslagerung der XML-Generierung. Hier kommt Zoho Flow ins Spiel.

  1. Trigger: Der Prozess startet in Zoho Flow mit einem Webhook-Trigger. Dein Deluge-Button in Zoho Books ruft diesen Webhook auf und übergibt die Rechnungsdaten als JSON.
  2. Logik: Zoho Flow leitet diese Daten an einen spezialisierten Dienst weiter. Das könnte eine kleine App auf Zoho Catalyst, eine AWS Lambda-Funktion oder ein externer Microservice sein, der nichts anderes tut, als JSON entgegenzunehmen und valides ebInterface-XML zurückzugeben.
  3. Aktion: Der externe Dienst sendet die fertige XML-Datei zurück an Zoho Flow.
  4. Abschluss: Zoho Flow nutzt die Zoho Books API-Aktion, um die erhaltene XML-Datei an die ursprüngliche Rechnung anzuhängen.

Dieser Ansatz ist zwar aufwändiger in der Einrichtung, aber robuster und leichter zu warten, da die komplexe Logik der XML-Erstellung von der reinen Datenorchestrierung getrennt ist.

Tipps und Best Practices

  • Fehlerbehandlung: Baue in dein Deluge-Skript eine Fehlerbehandlung ein. Was passiert, wenn die UID-Nummer beim Kunden fehlt? Informiere den Nutzer mit einer klaren Fehlermeldung, anstatt das Skript einfach abbrechen zu lassen. Nutze hierfür try...catch-Blöcke.
  • Testing: Entwickle und teste deine Funktion immer in einer Sandbox-Organisation von Zoho Books, bevor du sie in deinem produktiven System einsetzt.
  • Skalierung: Beginne mit dem manuellen Button. Wenn der Prozess stabil läuft, kannst du ihn weiter automatisieren. Erstelle eine Workflow-Regel in Zoho Books, die deine Funktion automatisch auslöst, sobald eine Rechnung für einen Kunden mit einem bestimmten Merkmal (z.B. ein Tag „Öffentlicher Sektor“) erstellt wird.
  • Versionierung: Standards wie ebInterface entwickeln sich weiter. Berücksichtige die Versionsnummer in deinem Skript und sei bereit, es bei Bedarf anzupassen.

Zusätzliche Hinweise: Das Ökosystem intelligent nutzen

Diese Lösung ist nur ein Beispiel dafür, wie du die Zoho-Plattform erweitern kannst. Denke immer daran, wie die verschiedenen Apps zusammenspielen können:

  • Bankanbindung und Zahlungs-Gateways: Verbinde deine Bankkonten (z.B. Raiffeisen) direkt mit Zoho Books für einen automatischen Abgleich. Integriere Zahlungsanbieter wie Stripe oder PayPal, um die Bezahlung deiner Rechnungen zu vereinfachen.
  • Spesenmanagement: Nutze Zoho Expense in Kombination mit Diensten wie PLEO, um die Spesenabrechnung zu digitalisieren. Die Daten fließen automatisch und korrekt verbucht in deine Buchhaltung in Zoho Books.
  • Erweitertes Reporting: Wenn die Standardberichte in Books nicht ausreichen, repliziere deine Finanzdaten nach Zoho Analytics und erstelle dort umfassende, interaktive Dashboards und KPIs.
  • Interne Kommunikation: Informiere dein Team über wichtige Ereignisse. Sende zum Beispiel eine automatische Nachricht über Zoho Cliq an die Buchhaltung, sobald eine neue E-Rechnung generiert wurde und bereit für den Upload ist.

Fazit

Auch wenn eine Standardfunktion für einen sehr spezifischen, lokalen Anwendungsfall wie die österreichische E-Rechnung in Zoho fehlt, bist du nicht blockiert. Das Beispiel zeigt eindrücklich, dass Zoho mehr ist als nur eine Sammlung von Apps – es ist eine Entwicklungsplattform. Mit den richtigen Werkzeugen wie Deluge, den APIs und Zoho Flow kannst du maßgeschneiderte Lösungen bauen, die deine Prozesse exakt abbilden, manuelle Arbeit eliminieren und Fehler reduzieren. Die Investition in das Erlernen dieser Werkzeuge zahlt sich durch eine immense Steigerung der Effizienz und eine perfekte Anpassung der Software an deine individuellen Geschäftsanforderungen aus.

Verwendete Zoho Apps in diesem Lösungsansatz: