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

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.

E-Invoicing Service-Funktionen 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.

Endpunkte im Workflow Designer für E-Invoicing

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

1. E-Rechnung senden

Endpunkt: Post /v1/invoices/

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

Parameter des HTTP Request Body:

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, der unter DocuWare Konfigurationen > Integrationen > E-Invoicing definiert ist. Siehe DocuWare E-Invoicing Service konfigurieren.

2. Statusaktualisierung abrufen

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

Ruft den aktuellen Verarbeitungsstatus einer übermittelten E-Rechnung vom Netzwerk ab. Die {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 in DocuWare gespeicherten empfangenen E-Rechnung. Verwenden Sie diesen Endpunkt, um den Rechnungsstatus auf Basis geschäftlicher Ereignisse wie Zahlungsbestätigung oder Freigabe zu setzen.

Dieser Endpunkt gilt nur für empfangene Rechnungen — also Rechnungen, die von einem Lieferanten ausgestellt, empfangen wurden und eine Aktion erfordern. Nur die unten aufgeführten Statuswerte sind für diesen Endpunkt zulässig.

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

Weitere Informationen und eine Übersicht der E-Rechnungsstatuswerte finden Sie im Artikel DocuWare E-Invoicing Service-Statuswerte verstehen.

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

Parameter des HTTP Request Body:

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 dediziertes 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)

Parameter des HTTP Request Body:

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:

Fehlerbehandlung

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

Fehler werden auf eine der folgenden Weisen gemeldet:

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

• Task Viewer – zeigt die Verarbeitungshistorie und Fehlerdetails für gesendete und empfangene E-Rechnungen an. Siehe DocuWare E-Invoicing Service konfigurieren – Historie

• Web Service-Antwort – gibt eine Fehlermeldung direkt von der E-Invoicing Service-API 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 Vertrag der juristischen Person gekündigt

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

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

Lösung: Überprüfen und korrigieren Sie die E-Invoicing Service-Konfiguration 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 E-Invoicing Service-Konfiguration.

• 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 im Netzwerk nicht 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 im Archiv nicht gefunden

• Doppelte Übermittlung – Rechnung wurde bereits gesendet

• Ungültiger Statusübergang

Lösung: Prüfen Sie die E-Rechnungsdaten und überprüfen Sie, ob die Workflow-Konfiguration korrekt ist.

Netzwerk und Verbindung

• 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.

Das folgende Muster wird zur Fehlerbehandlung im ausgehenden Workflow 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 Statusabfragen erforderlich.

2. Warten und Status abfragen

Fügen Sie eine Zeitverzögerung von 1–3 Minuten ein, bevor Sie Get /v1/tasks/{id}/status aufrufen. Prüfen Sie das Ergebnis des Tasks:

• Completed → mit der Prüfung des Indexfelds für den Rechnungsstatus fortfahren:

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

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

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

3. Fehler behandeln

Sobald ein endgültiger Fehler bestätigt ist:

• Verwenden Sie die Datenzuordnung der Web Service-Aktivität, um die Fehlermeldung aus der API-Antwort in ein dediziertes Indexfeld im Archiv zu schreiben (zum Beispiel Errors).

• Erstellen Sie eine Workflow-Aufgabe für den verantwortlichen Benutzer, damit dieser den Fehler prüfen und gemäß der definierten Aufgabenkonfiguration handeln kann.

Information

Die vom E-Invoicing Service zurückgegebene Fehlermeldung kann über den JSON-Pfad $errorMessage auf der Registerkarte Datenzuordnung der Web Service-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 zur Fehlerbehandlung

• Sehen Sie im Archiv ein dediziertes Fehler-Indexfeld vor (zum Beispiel Errors als Schlagwort), um Fehlermeldungen des E-Invoicing Service zu erfassen.

• Gestalten Sie die Workflow-Aufgabe für Fehlerfälle mit klaren Anweisungen für den Benutzer, wie er vorgehen soll.

• Verwenden Sie den Task Viewer unter DocuWare Konfigurationen > Integrationen > E-Invoicing, um die vollständige Verarbeitungshistorie 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 den E-Rechnungstask gestartet werden.

• Bei Netzwerk- oder Verbindungsfehlern wiederholt der E-Invoicing Service die Zustellung bis zu 24 Stunden lang automatisch. Vermeiden Sie in diesem Zeitraum eine manuelle erneute Übermittlung, um doppelte Sendungen zu verhindern.

Übersicht der Rechnungsstatuswerte

Die folgenden Statuswerte werden für E-Rechnungen verwendet. Einige Statuswerte werden automatisch durch den 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