How-to set up workflows for DocuWare E-Invoicing Service

DocuWare E‑Invoicing Service connects your legal entity, such as a company, with country-specific e‑invoicing networks and tax authorities to send and receive compliant e‑invoices.

The DocuWare Workflow Designer automates and controls how e-invoices are processed within DocuWare. Together with the E-Invoicing Service, workflows handle the following scenarios:

• Sending e-invoices to recipients via the configured network

• Validating technical and business rules for e-invoices

• Processing incoming e-invoices

You configure and use these functions in DocuWare Configurations > Collaboration > Workflow Designer. For a general introduction to the Workflow Designer, see Workflow Designer help.

Prerequisites

• Before setting up workflows for the E-Invoicing Service, ensure the E-Invoicing Service has been configured for the relevant legal entity and that the workflow user has the Use permission for the E-Invoicing Service configuration. See How-to configure DocuWare E-Invoicing Service.

• ConfigurationName: During the E-Invoicing Service setup, you assign a unique name to each configuration. This name is available as the workflow variable ConfigurationName and is used in the Web Service activity to reference the correct E-Invoicing Service configuration. Ensure the value matches the configuration name exactly as defined in DocuWare Configurations > Integrations > E-Invoicing.

E-invoicing Service functions in the Workflow Designer

The E-Invoicing Service functions are called from within a DocuWare workflow using the Web Service activity. The E-Invoicing Service is pre-registered as DocuWare E-Invoicing in the Workflow Designer, so no manual URL configuration is required.

To use a function, add a Web Service activity, select DocuWare E-Invoicing under Defined web service, and choose the desired endpoint. Configure the Request, HTTP Headers, and HTTP Request Body tabs as described for each endpoint below. Optionally, use Data assignment to map response values back to document index fields, and Status codes to define how HTTP response codes are handled.

The Web Service activity processes one document at a time. Each workflow run handles a single e-invoice and all related actions for that document.

Note: Processing and synchronization logic

The DocuWare E-Invoicing Service processes e-invoices asynchronously. When an e-invoice is submitted to the network, the service returns a Task ID immediately, but the actual delivery happens in the background. The workflow cannot check the result instantly. Instead, it must wait and poll for the current status using a dedicated status endpoint.

This asynchronous behavior also applies to error messages, which may only become available after the network has processed the request.

Endpoints in Workflow Designer for E-Invoicing

The following endpoints are available under the web service DocuWare E-Invoicing:

1. Send E-Invoice

Endpoint: Post /v1/invoices/

Submits an e-invoice stored in DocuWare to the configured network for delivery to the recipient.

HTTP Request Body parameters:

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}"
}

The configuration value must match the configuration name exactly as defined in DocuWare Configurations > Integrations > E-Invoicing. See How-to configure DocuWare E-Invoicing Service.

2. Get Status Update

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

Retrieves the current processing status of a submitted e-invoice from the network. The {id} in the route is the Task ID returned in the response of a previous HTTP Request done in this workflow. Store this value in a global workflow variable to pass it to this endpoint.

HTTP Headers: Accept: application/json (pre-configured)

HTTP Request Body: none

Route configuration:

JSON HTTP Response Body (200):

{
  "taskId": "{id}"
}

3. Update Invoice Status

Endpoint: Put /v1/invoices/status/

Updates the status of a received e-invoice stored in DocuWare. Use this endpoint to set the invoice status based on business events such as payment confirmation or approval.

This endpoint applies to received invoices only — invoices issued by a supplier that have been received and require action. Only the status values listed below are valid for this endpoint.

The invoice status for issued (outgoing) invoices is updated automatically via the network. There is no need to update the status of a sent invoice from within the workflow. You can use the status values for issued invoices in the DocuWare Workflow to control processes, but do not use them to update an invoice status within the network.

For more information and an e-invoice status reference, see Understanding DocuWare E-Invoicing Service Statuses.

HTTP Headers: Accept: application/json + Content-Type: application/json (pre-configured)

HTTP Request Body parameters:

JSON HTTP Request Body:

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

JSON HTTP Response Body (200):

{
  "taskId": "{id}"
}

Status values written to statusValue:

4. Create Validation Report

Endpoint: Post /v1/invoices/validation/report

Runs a technical and business rule check on an e-invoice stored in DocuWare and generates a validation report. The result is written to a dedicated index field and a validation report is attached to the e-invoice.

This function is currently available for Germany only.

HTTP Headers: Accept: application/json + Content-Type: application/json (pre-configured)

HTTP Request Body parameters:

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}"
}

Validation result values written to validationStatusField:

Error handling

When processing e-invoices through the DocuWare E-Invoicing Service, errors can occur at different stages of the workflow. Before addressing how to handle errors, it is helpful to understand where errors are reported and what types of errors can occur.

Errors are reported in one of the following ways:

• Workflow History – logs the workflow execution and any failed activities

• Task Viewer – displays the processing history and error details for sent and received e-invoices. See How-to configure DocuWare E-Invoicing Service – History

• Web Service response – returns an error message directly from the E-Invoicing Service API that can be mapped to a document index field

Error types and solutions

The following types of errors can occur. The steps required to resolve an error depend on the specific error and its root cause:

Configuration and setup

• Invalid or mismatched ConfigurationName

• No active license or contract cancelled for the legal entity

• Workflow user missing Use permission on the E-Invoicing Service configuration

• Wrong environment selected (Staging vs. Production)

Solution: Review and correct the E-Invoicing Service configuration and retry.

Certificate and authentication

• Expired or invalid electronic certificate (Poland/KSeF)

• Incorrect certificate PIN (Poland/KSeF)

Solution: Renew your electronic certificate via the Polish Ministry of Finance and update it in the E-Invoicing Service configuration.

• Peppol ID not active or not registered for your account

Solution: Contact DocuWare Support.

Recipient

• Recipient Peppol ID not found in the network

Solution: Verify the recipient details on the e-invoice and contact the recipient to confirm their Peppol ID.

Document

• Document not found in the file cabinet

• Duplicate submission – invoice has already been sent

• Invalid status transition

Solution: Check the e-invoice data and verify that the workflow configuration is correct.

Network and connectivity

• Access point unreachable

• Peppol network temporarily unavailable

• KSeF service temporarily unavailable

• Tax authority system under maintenance

Solution: Check the status on the respective network's public status page.

How the workflow handles errors

When an e-invoice is submitted via the Send E-Invoice endpoint, the E-Invoicing Service returns a Task ID immediately. The actual delivery to the network happens in the background and typically completes within 1–3 minutes. The workflow must poll for the result using the Get Status Update endpoint.

The following pattern is recommended for handling errors in the outbound workflow:

1. Submit and store Task ID

After calling Post /v1/invoices/, store the returned Task ID in a global workflow variable. This Task ID is required for all subsequent status checks.

2. Wait and poll for status

Add a Time Delay activity of 1–3 minutes before calling Get /v1/tasks/{id}/status. Check the result of the task:

• Completed → proceed to check the invoice status index field:

  • Status = sent → e-invoice delivered successfully, continue workflow

  • Status = error → delivery failed, proceed to error handling

• Retry → the E-Invoicing Service is retrying delivery automatically. Add a Time Delay of approximately 40 minutes and poll again using Get /v1/tasks/{id}/status. The service will continue retrying for up to 24 hours.

3. Handle errors

When a final error is confirmed:

• Use the Data assignment configuration of the Web Service activity to write the error message from the API response to a dedicated index field in the file cabinet (for example Errors).

• Create a Workflow Task for the responsible user to review the error and act according to the defined task configuration.

Information

The error message returned by the E-Invoicing Service can be mapped to a document index field using the JSON path $errorMessage in the Data assignment tab of the Web Service activity. This makes the error visible directly on the document without requiring access to the Task Viewer.

Recommendations for error handling

• Include a dedicated error index field (for example Errors as Keyword) in the file cabinet to capture error messages from the E-Invoicing Service.

• Design the Workflow Task for error cases with clear instructions for the user on how to proceed.

• Use the Task Viewer in DocuWare Configurations > Integrations > E-Invoicing to review the full processing history and detailed error messages for all sent and received e-invoices. In certain cases, a retry for the e-invoice task can be initiated in the Task Viewer.

• For network or connectivity errors, the E-Invoicing Service retries automatically for up to 24 hours. Avoid manual resubmission during this period to prevent duplicate sending.

Invoice status reference

The following status values are used for e-invoices. Some status values are set automatically by the background process with the Peppol network or other networks such as KSeF in Poland.

Issued invoice

Received invoice

Issued simplified invoice

Supported versions: DocuWare Cloud