Workflows für DocuWare E-Invoicing Service einrichten

Der DocuWare E-Invoicing Service verbindet Ihre juristische Person, beispielsweise ein Unternehmen, mit länderspezifischen E-Rechnungsnetzwerken und Steuerbehörden, um konforme E-Rechnungen zu senden und zu empfangen.

Der DocuWare Workflow Designer automatisiert und steuert die Verarbeitung von E-Rechnungen innerhalb von DocuWare. Zusammen mit dem E-Invoicing Service decken Workflows die folgenden Szenarien ab:

• Versand von E-Rechnungen an Empfänger über das konfigurierte Netzwerk

• Validierung technischer und geschäftlicher Regeln für E-Rechnungen

• Verarbeitung eingehender E-Rechnungen

• Steuerbericht aus E-Rechnungsdaten oder -datei übermitteln; die direkte Übermittlung von E-Reports wird nicht unterstützt

• Verzeichnissuche nach einer Firmenadresse in Peppol Registry & Annuaire

Sie konfigurieren und verwenden diese Funktionen unter DocuWare Konfigurationen > Zusammenarbeit > Workflow Designer. Eine allgemeine Einführung in den Workflow Designer finden Sie in der Workflow Designer-Hilfe.

Voraussetzungen

• Stellen Sie vor dem Einrichten von Workflows für den E-Invoicing Service sicher, dass der E-Invoicing Service für die betreffende juristische Person konfiguriert wurde und dass der Workflow-Benutzer über die Berechtigung Verwenden für die E-Invoicing Service-Konfiguration verfügt. Siehe DocuWare E-Invoicing Service konfigurieren.

• ConfigurationName: Während der Einrichtung des E-Invoicing Service vergeben Sie jeder Konfiguration einen eindeutigen Namen. Dieser Name steht als Workflow-Variable ConfigurationName zur Verfügung und wird in der Web Service-Aktivität verwendet, um auf die korrekte E-Invoicing Service-Konfiguration zu verweisen. Stellen Sie sicher, dass der Wert exakt mit dem Konfigurationsnamen übereinstimmt, der unter DocuWare Konfigurationen > Integrationen > E-Invoicing definiert ist.

• Indexfelder: Es wird empfohlen, im Archiv, das für die Verarbeitung von E-Rechnungen verwendet wird, die folgenden Indexfelder einzurichten:

• TaxReportID

• Network_ID

• Invoice_Status

• Validation_Status

Funktionen des E-Invoicing Service im Workflow Designer

Die Funktionen des E-Invoicing Service werden innerhalb eines DocuWare-Workflows über die Aktivität Web Service aufgerufen. Der E-Invoicing Service ist im Workflow Designer als DocuWare E-Invoicing vorregistriert, sodass keine manuelle URL-Konfiguration erforderlich ist.

Um eine Funktion zu nutzen, fügen Sie eine Web Service-Aktivität hinzu, wählen Sie unter Definierter Web Service die Option DocuWare E-Invoicing und wählen Sie den gewünschten Endpunkt aus. Konfigurieren Sie die Registerkarten Request, HTTP-Header und HTTP Request Body wie für jeden Endpunkt unten beschrieben. Optional können Sie über Datenzuordnung Antwortwerte auf Dokument-Indexfelder abbilden und über Statuscodes festlegen, wie HTTP-Antwortcodes behandelt werden.

Die Web Service-Aktivität verarbeitet jeweils ein Dokument. Jeder Workflow-Lauf behandelt eine einzelne E-Rechnung und alle zugehörigen Aktionen für dieses Dokument.

Hinweis: Verarbeitungs- und Synchronisationslogik

Der DocuWare E-Invoicing Service verarbeitet E-Rechnungen asynchron. Wenn eine E-Rechnung an das Netzwerk übermittelt wird, gibt der Service sofort eine Task-ID zurück, die eigentliche Zustellung erfolgt jedoch im Hintergrund. Der Workflow kann das Ergebnis nicht unmittelbar prüfen. Er muss stattdessen warten und den aktuellen Status über einen dedizierten Status-Endpunkt abfragen.

Dieses asynchrone Verhalten gilt auch für Fehlermeldungen, die möglicherweise erst verfügbar sind, nachdem das Netzwerk die Anfrage verarbeitet hat.

Die folgenden Endpunkte stehen unter dem Webservice DocuWare E-Invoicing im Workflow Designer zur Verfügung. Verwenden Sie sie, um E-Invoicing-Aktionen direkt aus Ihren DocuWare Workflows zu automatisieren.

Endpunkte im Workflow Designer für E-Invoicing

Die folgenden Endpunkte stehen unter dem Webservice DocuWare E-Invoicing zur Verfügung:

1. E-Rechnung senden

Endpunkt: Post /v1/invoices/

Übermittelt eine in DocuWare gespeicherte E-Rechnung an das konfigurierte Netzwerk zur Zustellung an den Empfänger.

HTTP Request Body-Parameter:

JSON HTTP Request Body:

{
  "documentId": "Index field DocumentID",
  "fileCabinetId": "System variables File Cabinet GUID",
  "configuration": "ConfigurationName",
  "statusField": "Index field Invoice_Status",
  "validateInvoice": true,
  "networkIdField": "(Optional) Index field Network ID",
  "transportTypeCode": "(Optional) Index field TransportTypeCode"
}

JSON HTTP Response Body (200):

{
  "taskId": "{id}"
}

Der Wert configuration muss exakt mit dem Konfigurationsnamen übereinstimmen, wie er unter DocuWare Konfigurationen > Integrationen > E-Invoicing festgelegt ist. Siehe So konfigurieren Sie den DocuWare E-Invoicing Service.

2. Statusaktualisierung abrufen

Endpunkt: Get /v1/tasks/{id}/status

Ruft den aktuellen Verarbeitungsstatus einer übermittelten E-Rechnung aus dem Netzwerk ab. Das {id} in der Route ist die Task-ID, die in der Antwort einer vorherigen HTTP-Anfrage in diesem Workflow zurückgegeben wurde. Speichern Sie diesen Wert in einer globalen Workflow-Variable, um ihn an diesen Endpunkt zu übergeben.

HTTP-Header: Accept: application/json (vorkonfiguriert)

HTTP Request Body: keiner

Routenkonfiguration:

JSON HTTP Response Body (200):

{
  "taskId": "{id}"
}

3. Rechnungsstatus aktualisieren

Endpunkt: Put /v1/invoices/status/

Aktualisiert den Status einer empfangenen, in DocuWare gespeicherten E-Rechnung. Verwenden Sie diesen Endpunkt, um den Rechnungsstatus auf Grundlage von Geschäftsereignissen wie einer Zahlungsbestätigung oder einer Genehmigung zu setzen.

Dieser Endpunkt gilt nur für empfangene Rechnungen, also von einem Lieferanten ausgestellte Rechnungen, die empfangen wurden und eine Aktion erfordern. Für diesen Endpunkt sind nur die unten aufgeführten Statuswerte gültig.

Der Rechnungsstatus für ausgestellte (ausgehende) Rechnungen wird automatisch über das Netzwerk aktualisiert. Der Status einer gesendeten Rechnung muss nicht aus dem Workflow heraus aktualisiert werden. Sie können die Statuswerte für ausgestellte Rechnungen im DocuWare Workflow zur Prozesssteuerung verwenden, jedoch nicht dazu, einen Rechnungsstatus innerhalb des Netzwerks zu aktualisieren.

Weitere Informationen sowie eine Referenz der E-Rechnungsstatus finden Sie unter Die Status des DocuWare E-Invoicing Service verstehen.

HTTP-Header: Accept: application/json + Content-Type: application/json (vorkonfiguriert)

HTTP Request Body-Parameter:

JSON HTTP Request Body:

{
  "documentId": "Index field DocumentID",
  "fileCabinetId": "System variables File Cabinet GUID",
  "statusValue": "Paid"
}

JSON HTTP Response Body (200):

{
  "taskId": "{id}"
}

Statuswerte, die in statusValue geschrieben werden:

4. Validierungsbericht erstellen

Endpunkt: Post /v1/invoices/validation/report

Führt eine technische und geschäftliche Regelprüfung für eine in DocuWare gespeicherte E-Rechnung durch und erstellt einen Validierungsbericht. Das Ergebnis wird in ein dafür vorgesehenes Indexfeld geschrieben und ein Validierungsbericht wird an die E-Rechnung angehängt.

Diese Funktion ist derzeit nur für Deutschland verfügbar.

HTTP-Header: Accept: application/json + Content-Type: application/json (vorkonfiguriert)

HTTP Request Body-Parameter:

JSON HTTP Request Body:

{
  "documentId": "Index field DocumentID",
  "fileCabinetId": "System variables File Cabinet GUID",
  "configuration": "ConfigurationName",
  "validationStatusField": "Index field Validation_Status"
}

JSON HTTP Response Body (200):

{
  "taskId": "{id}"
}

Validierungsergebnis-Werte, die in validationStatusField geschrieben werden:

5. Steuerbericht aus E-Rechnungsdatei oder -daten übermitteln

Endpunkt: Post /v1/tax-reports/create

Übermittelt einen Steuerbericht an die DGFiP zur Erfüllung der verpflichtenden E-Reporting-Vorgaben. Der E-Report kann aus in DocuWare gespeicherten Indexdaten erzeugt oder direkt aus einer vorhandenen, konformen E-Rechnungsdatei übermittelt werden.

Information: Diese Funktion ist derzeit nur für Frankreich verfügbar.

HTTP-Header: Accept: application/json + Content-Type: application/json (vorkonfiguriert)

HTTP Request Body-Parameter:

JSON HTTP Request Body:

{
  "documentId": "Index field DocumentID",
  "fileCabinetId": "System variables File Cabinet GUID",
  "configuration": "ConfigurationName",
  "statusField": "Index field Invoice_Status",
  "invoiceSource": "Data", //Data or File
  "invoiceType": "Received", //Received or Issued
  "taxReportStatusField": "(Optional) Tax_Report_Status",
  "taxReportIdentifierField": "(Optional) Tax_Report_Identifier"
}

JSON HTTP Response Body (200):

{
  "taskId": "{id}"
}

Weitere Informationen sowie eine Referenz der E-Report-Status finden Sie unter Die Status des DocuWare E-Invoicing Service verstehen.
Weitere Informationen zum Ablauf des E-Reportings finden Sie unter „E-Reporting mit dem DocuWare E-Invoicing Service verstehen" (in Kürze verfügbar).

6. Verzeichnissuche in Peppol/Annuaire

Endpunkt: Get /v1/directory

Schlägt die Adresse und die Routing-Informationen eines Unternehmens in der Peppol Registry oder in Annuaire nach. Dieser Endpunkt ist synchron; das Ergebnis wird direkt in der Antwort zurückgegeben. Es wird keine Task-ID ausgegeben und kein Polling benötigt.

HTTP-Header: Accept: application/json + Content-Type: application/json (vorkonfiguriert)

HTTP Request Body-Parameter: keine

JSON HTTP Response Body (200):

Dies ist ein Beispiel für den Response Body, wenn Sie über diesen Endpunkt DocuWare mit fr und 505184754 nachschlagen.

{
  "name": "DocuWare SARL",
  "email": "orders@docuware.com",
  "website": null,
  "address": "17 rue du Colisée",
  "address2": null,
  "city": "Paris",
  "postalcode": "75008",
  "province": "Paris",
  "country": "fr",
  "language": "en",
  "currency": "EUR",
  "tin_scheme": null,
  "tin_value": null,
  "cin_scheme": "0002",
  "cin_value": "505184754",
  "pin_scheme": "0225",
  "pin_value": "505184754"
}

Referenz der Antwortfelder:

Fehlerbehandlung

Bei der Verarbeitung von E-Rechnungen über den DocuWare E-Invoicing Service können in verschiedenen Phasen des Workflows Fehler auftreten. Bevor darauf eingegangen wird, wie Fehler behandelt werden, ist es hilfreich zu verstehen, wo Fehler gemeldet werden und welche Fehlertypen auftreten können.

Fehler werden auf eine der folgenden Arten gemeldet:

• Workflow-Historie – protokolliert die Workflow-Ausführung und alle fehlgeschlagenen Aktivitäten

• Task Viewer – zeigt den Verarbeitungsverlauf und die Fehlerdetails für gesendete und empfangene E-Rechnungen an. Siehe So konfigurieren Sie den DocuWare E-Invoicing Service – Verlauf

• Webservice-Antwort – gibt eine Fehlermeldung direkt von der API des E-Invoicing Service zurück, die einem Dokument-Indexfeld zugeordnet werden kann

Fehlertypen und Lösungen

Die folgenden Fehlertypen können auftreten. Welche Schritte zur Behebung eines Fehlers erforderlich sind, hängt vom konkreten Fehler und seiner Ursache ab:

Konfiguration und Einrichtung

• Ungültiger oder nicht übereinstimmender ConfigurationName

• Keine aktive Lizenz oder gekündigter Vertrag für den Rechtsträger

• Dem Workflow-Benutzer fehlt die Berechtigung Verwenden für die Konfiguration des E-Invoicing Service

• Falsche Umgebung ausgewählt (Staging vs. Produktion)

Lösung: Überprüfen und korrigieren Sie die Konfiguration des E-Invoicing Service und versuchen Sie es erneut.

Zertifikat und Authentifizierung

• Abgelaufenes oder ungültiges elektronisches Zertifikat (Polen/KSeF)

• Falsche Zertifikats-PIN (Polen/KSeF)

Lösung: Erneuern Sie Ihr elektronisches Zertifikat über das polnische Finanzministerium und aktualisieren Sie es in der Konfiguration des E-Invoicing Service.

• Peppol-ID nicht aktiv oder nicht für Ihr Konto registriert

Lösung: Wenden Sie sich an den DocuWare Support.

Empfänger

• Peppol-ID des Empfängers nicht im Netzwerk gefunden

Lösung: Überprüfen Sie die Empfängerdaten auf der E-Rechnung und kontaktieren Sie den Empfänger, um dessen Peppol-ID zu bestätigen.

Dokument

• Dokument nicht im Archiv gefunden

• Doppelte Übermittlung – die Rechnung wurde bereits gesendet

• Ungültiger Statusübergang

Lösung: Prüfen Sie die Daten der E-Rechnung und stellen Sie sicher, dass die Workflow-Konfiguration korrekt ist.

Netzwerk und Konnektivität

• Access Point nicht erreichbar

• Peppol-Netzwerk vorübergehend nicht verfügbar

• KSeF-Dienst vorübergehend nicht verfügbar

• System der Steuerbehörde in Wartung

Lösung: Prüfen Sie den Status auf der öffentlichen Statusseite des jeweiligen Netzwerks.

Wie der Workflow Fehler behandelt

Wenn eine E-Rechnung über den Endpunkt E-Rechnung senden übermittelt wird, gibt der E-Invoicing Service sofort eine Task-ID zurück. Die eigentliche Zustellung an das Netzwerk erfolgt im Hintergrund und ist in der Regel innerhalb von 1–3 Minuten abgeschlossen. Der Workflow muss das Ergebnis über den Endpunkt Statusaktualisierung abrufen abfragen.

Für die Fehlerbehandlung im ausgehenden Workflow wird das folgende Muster empfohlen:

1. Übermitteln und Task-ID speichern

Speichern Sie nach dem Aufruf von Post /v1/invoices/ die zurückgegebene Task-ID in einer globalen Workflow-Variable. Diese Task-ID ist für alle nachfolgenden Statusprüfungen erforderlich.

2. Warten und Status abfragen

Fügen Sie vor dem Aufruf von Get /v1/tasks/{id}/status eine Aktivität Zeitverzögerung von 1–3 Minuten ein. Prüfen Sie das Ergebnis der Task:

• Completed → fahren Sie mit der Prüfung des Indexfelds für den Rechnungsstatus fort:

  • Status = sent → E-Rechnung erfolgreich zugestellt, Workflow fortsetzen

  • Status = error → Zustellung fehlgeschlagen, mit der Fehlerbehandlung fortfahren

• Retry → der E-Invoicing Service versucht die Zustellung automatisch erneut. Fügen Sie eine Aktivität Zeitverzögerung von etwa 40 Minuten ein und fragen Sie den Status erneut über Get /v1/tasks/{id}/status ab. Der Service wiederholt den Versuch bis zu 24 Stunden lang.

3. Fehler behandeln

Wenn ein endgültiger Fehler bestätigt ist:

• Verwenden Sie die Konfiguration Datenzuweisung der Webservice-Aktivität, um die Fehlermeldung aus der API-Antwort in ein dafür vorgesehenes Indexfeld im Archiv zu schreiben (zum Beispiel Errors).

• Erstellen Sie eine Workflow-Aufgabe für den zuständigen Benutzer, damit dieser den Fehler prüft und gemäß der definierten Aufgabenkonfiguration handelt.

Information

Die vom E-Invoicing Service zurückgegebene Fehlermeldung kann über den JSON-Pfad $errorMessage im Tab Datenzuweisung der Webservice-Aktivität einem Dokument-Indexfeld zugeordnet werden. Dadurch wird der Fehler direkt am Dokument sichtbar, ohne dass ein Zugriff auf den Task Viewer erforderlich ist.

Empfehlungen für die Fehlerbehandlung

• Richten Sie im Archiv ein dafür vorgesehenes Fehler-Indexfeld ein (zum Beispiel Errors als Stichwort), um Fehlermeldungen des E-Invoicing Service zu erfassen.

• Gestalten Sie die Workflow-Aufgabe für Fehlerfälle mit klaren Anweisungen für den Benutzer zum weiteren Vorgehen.

• Verwenden Sie den Task Viewer unter DocuWare Konfigurationen > Integrationen > E-Invoicing, um den vollständigen Verarbeitungsverlauf und detaillierte Fehlermeldungen für alle gesendeten und empfangenen E-Rechnungen einzusehen. In bestimmten Fällen kann im Task Viewer ein erneuter Versuch für die E-Rechnungs-Task angestoßen werden.

• Bei Netzwerk- oder Verbindungsfehlern wiederholt der E-Invoicing Service den Versuch bis zu 24 Stunden lang automatisch. Vermeiden Sie in diesem Zeitraum eine manuelle erneute Übermittlung, um ein doppeltes Senden zu verhindern.

Referenz der Rechnungsstatus

Für E-Rechnungen werden die folgenden Statuswerte verwendet. Einige Statuswerte werden automatisch vom Hintergrundprozess mit dem Peppol-Netzwerk oder anderen Netzwerken wie KSeF in Polen gesetzt.

Ausgestellte Rechnung

Empfangene Rechnung

Ausgestellte vereinfachte Rechnung

Unterstützte Versionen: DocuWare Cloud