Sync-Szenarien

Exchange-Sync für Sage CRM
Exchange-Sync für Zoho CRM
Exchange-Sync für CAS

E-Mail-Archivierung mit CAS
E-Mails mit Graph API
Verarbeitung von E-Mails

Sync mit CleverReach
Sync mit InxMail

Zoho Kontakt-Rollen
Seriendruck
Übertragung eines Beleges
Verarbeitung von CSV
Dateien ablegen
E-Rechnung

E-Rechnung Konnektor - How-To

Dieses How-To zeigt Schritt für Schritt, wie Sie mit dem E-Rechnung Konnektor E-Rechnungen einlesen und erzeugen.
Es ergänzt die allgemeine Konnektor-Dokumentation um konkrete Anwendungsfälle.

1. E-Rechnung einlesen

Der E-Rechnung Konnektor unterstützt verschiedene Verfahren für das Lesen einer E-Rechnung.
Er erkennt automatisch, ob ihm XML-Daten direkt übergeben werden oder ob die Daten als XML-Anhang in einer PDF vorliegen.

⚠️ Wichtig:
Achten Sie darauf, dass das korrekte Schemaobjekt zum Format der E-Rechnung ausgewählt ist.
Die XML-Daten enthalten keine Format-Information.
Wird z. B. eine EN16931-Rechnung mit dem Schemaobjekt „ZUGFeRD Basic" eingelesen, stehen im Sync nicht alle Felder aus der Datei zur Verfügung.

1.1 Übersicht der Leseverfahren

Folgende Verfahren stehen zur Verfügung:

  • E-Rechnung aus einem lokalen Verzeichnis lesen (On-Premises)
  • E-Rechnung von einem FTP-Server lesen
  • E-Rechnung per Syncler-API empfangen (SaveXml)
  • E-Rechnung über andere Quellen (z. B. E-Mail, DMS) einlesen

Die eigentliche Verarbeitung erfolgt jeweils über einen Universal-Sync für geschachtelte Daten, der das gewünschte Rechnungsformat als Quellobjekt verwendet.

1.2 E-Rechnung aus einem Verzeichnis lesen (On-Premises)

Dieses Verfahren steht nur in der On-Premises-Version zur Verfügung.

Schritt 1 - Konnektor konfigurieren

  1. Öffnen Sie das System mit dem E-Rechnung Konnektor.
  2. Tragen Sie im Bereich Verzeichnisse das lokale Quellverzeichnis für eingehende Dateien ein.
  3. Optional: Konfigurieren Sie ein lokales Archivverzeichnis, in das gelesene Dateien verschoben werden sollen, statt sie zu löschen.

Schritt 2 - Universal-Sync einrichten

  1. Legen Sie einen Universal-Sync für geschachtelte Daten an.
  2. Wählen Sie den E-Rechnung Konnektor als Quellsystem.
  3. Wählen Sie unter Quellobjekt das gewünschte Rechnungsformat (z. B. ZF233_Basic oder ZF233_EN16931).
  4. Stellen Sie sicher, dass in dem konfigurierten Verzeichnis nur Rechnungen dieses Formats abgelegt werden.

Optional: Unterverzeichnisse unterscheiden

  • Im Sync kann der Filterparameter folder gesetzt werden.\
  • Tragen Sie dort den Namen des Unterverzeichnisses ein (relativ zum Quellverzeichnis im Konnektor).\
  • So können Sie ein System für mehrere Unterordner verwenden und pro Sync ein anderes Unterverzeichnis auswerten.

1.3 E-Rechnung von einem FTP lesen

Dieses Verfahren eignet sich, wenn die E-Rechnungen z. B. von einem anderen System auf einen FTP-Server exportiert werden.

Schritt 1 - Konnektor konfigurieren

  1. Öffnen Sie das System mit dem E-Rechnung Konnektor.
  2. Tragen Sie im Bereich FTP die Zugangsdaten ein:
    • Server, Port, Benutzername, Passwort
  3. Optional: Legen Sie ein FTP-Quellverzeichnis für eingehende Rechnungen fest.
  4. Optional: Konfigurieren Sie ein FTP-Archivverzeichnis, um verarbeitete Dateien zu verschieben.

Schritt 2 - Universal-Sync einrichten

  1. Legen Sie einen Universal-Sync für geschachtelte Daten an.
  2. Wählen Sie den E-Rechnung Konnektor als Quellsystem.
  3. Wählen Sie unter Quellobjekt das gewünschte Rechnungsformat.
  4. Stellen Sie sicher, dass im verwendeten Verzeichnis nur Rechnungen in diesem Format abgelegt werden.

Optional: Unterverzeichnisse unterscheiden

  • Verwenden Sie im Sync den Filterparameter folder.
  • Tragen Sie dort den Namen des Unterverzeichnisses ausgehend vom FTP-Quellverzeichnis ein.

1.4 E-Rechnung per API empfangen (SaveXml)

Bei diesem Verfahren wird die Syncler-API als Empfänger verwendet.
Der Sender übergibt die XML-Daten per HTTP POST direkt an Syncler.

1.4.1 Authentifizierung

  • Die Authentifizierung erfolgt mit Basic Auth.
  • Konfigurieren Sie im E-Rechnung Konnektor:
    • Benutzername
    • Passwort
  • Diese Daten müssen vom Sender in der Anfrage als Authorization: Basic ... übergeben werden.

1.4.2 Endpunkt-Aufruf

Der Endpunkt hat das Format:

Connection/SaveXml/{ClientID}/{TargetObject}
  • ClientID: Mandanten-ID Ihres Syncler-Accounts
  • TargetObject: Schemaname des E-Rechnungsformats (z. B. ZF233_Basic oder ZF233_EN16931)

Der Sender übergibt die XML-Daten im Request-Body (POST).
Der Konnektor übernimmt die XML-Daten und sucht nach konfigurierten Syncs, die dieses Schemaobjekt als Quelle verwenden.
Für jeden passenden Sync wird ein Eintrag im Datensatz-Speicher angelegt.
Beim nächsten Lauf des Syncs werden die Daten dort eingelesen und verarbeitet.

ℹ️ Verfügbarkeitsprüfung\

  • Ein Aufruf des Endpunktes mit GET (statt POST) und ohne Authorization liefert nur ein einfaches „OK" zurück.\
  • Damit kann die grundsätzliche Erreichbarkeit des Endpunktes getestet werden.

1.5 E-Rechnung über andere Quellen lesen (z. B. E-Mail, DMS, API)

Sie können mit dem E-Rechnung Konnektor auch Rechnungsdaten aus beliebigen anderen Quellen einlesen - etwa E-Mails, DMS, CRM oder eigene APIs.

Rahmenbedingungen

  • Es können sowohl XML-Daten als auch PDF-Daten verarbeitet werden.
  • Bei Übergabe von PDFs wird der Inhalt als Base64 erwartet.
  • Die Verarbeitung erfolgt über einen Ablauf (Workflow).

Schritt 1 - Ablauf anlegen

  1. Legen Sie einen neuen Ablauf an.
  2. Fügen Sie als ersten Schritt ein Sync hinzu, das die Datenquelle repräsentiert (z. B. E-Mail Konnektor, DMS, API).
    • Dieser Schritt liefert z. B. ein Feld FileContent mit den Datei-Inhalten (XML oder PDF als Base64).

Schritt 2 - Universal-Sync für Rechnungsdaten einfügen

  1. Fügen Sie als zweiten Schritt einen Universal-Sync für geschachtelte Daten hinzu.
  2. Verwenden Sie den E-Rechnung Konnektor als Quellsystem.
  3. Wählen Sie das gewünschte Rechnungsformat als Quellobjekt.
  4. Konfigurieren Sie den Schritt so, dass er eine gefilterte Abfrage mit den Daten des Vorgängerschritts ausführt:
    • Verwenden Sie in der Abfrage einen Platzhalter für den Dateiinhalt, z. B. #FileContent#.

Der Konnektor erkennt daraus, dass ihm Rechnungsdaten direkt übergeben werden, und stellt diese dem Sync zur Verfügung.

2. E-Rechnung erzeugen

Der Konnektor kann E-Rechnungen sowohl als reine XML-Daten als auch als PDF mit eingebettetem XML-Daten erzeugen.

2.1 Grundlagen: XML vs. PDF-Seriendruck

  • Nur XML erzeugen
    • Es werden ausschließlich die XML-Daten der E-Rechnung generiert.
  • PDF mit eingebettetem XML erzeugen
    • Es wird ein PDF-Seriendruck auf Basis einer Vorlage ausgeführt.
    • Die erzeugte XML wird als Anhang im PDF eingebettet.

Welche Variante erzeugt wird, hängt von der Konfiguration des Schemaobjekts und der Sync-Einstellungen ab.

2.2 Seriendruck konfigurieren (MailMergeFile)

Um eine PDF zu erzeugen, müssen im Schemaobjekt die Felder in der Objektgruppe MailMergeFile konfiguriert werden.

Es gibt zwei Varianten:

  1. Universal-Sync: nutzt die Zieldaten für den Seriendruck.\
  2. Spezieller Sync „E-Rechnung mit geschachtelte Daten": nutzt den Quelldatensatz, wodurch transformierte Daten verfügbar sind. Dieser Sync erlaubt die Konfiguration des Seriendrucks mit den Einstellungen vorzunehmen.

2.3 E-Rechnung erzeugen und als Datei ablegen

Konfigurieren Sie im Schemaobjekt die Felder:

  • OutputMethod
  • OutputName
  • OutputPath

OutputMethod kann sein:

  • LOCAL_FILE - nur On-Premises, lokale Ablage\
  • FTP - Ablage über den FTP-Zugang des Konnektors

Dateien werden nie überschrieben - ein fortlaufender Zähler wird automatisch angefügt.

2.4 E-Rechnung erzeugen und an ein anderes Ziel übergeben

OutputMethod = DATABASE

  • Ergebnis wird im Datensatz-Speicher abgelegt.
  • Der Eintrag wird dem aktuellen oder Nachfolgesync zugeordnet.
  • Ein Nachfolger-Sync kann die erzeugte Rechnung weiterverarbeiten
  • z.B. E-Rechnung Resultat nach Email Nachricht
    • Die Quelldaten werden automatisch für die Email-Vorlage genutzt, um Seriendruckfelder zu ersetzen.
    • Das Resultat (FileName und FileContent) können als Anhang der Email hinzugefügt werden.

OutputMethod = BASE64

  • Ergebnis wird als Base64 im Ablauf weitergereicht, z. B. zur Ablage in DMS, CRM oder zur Weitergabe an APIs.
  • Der Schritt kann dann direkt die Zieldaten des Vorgängers (E-Rechnung erstellen) verwenden.

3. Hinweise zu den Datenanforderungen

Für eine E-Rechnung müssen bestimmte Kriterien erfüllt sein, damit sie eine Validierung bestehen kann.

  • Der TypeCode in der Gruppe ExchangedDocument muss für Rechnungen den Wert "380" haben.
  • Die SellerTradeParty und BuyerTradeParty muss angegeben werden.
  • Für GuidelineSpecifiedDocumentContextParameter muss ein ID-Wert angegeben werden.
    • Für Basic kann der Wert "urn:cen.eu:en16931:2017#compliant#urn:factur-x.eu:1p0:basic" verwendet werden.
  • Je Position muss ChargeAmount, Name und LineTotalAmount zugeordnet werden.

4. Zusammenfassung

  • Der E-Rechnung Konnektor unterstützt zahlreiche Lesewege (Verzeichnis, FTP, API, andere Quellen).
  • Die korrekte Wahl des Schemaobjekts ist essenziell.
  • Dank verschiedener Output-Methoden lassen sich Rechnungen flexibel erzeugen und weiterverarbeiten.