Cómo configurar flujos de trabajo para DocuWare E-Invoicing Service

DocuWare E‑Invoicing Service conecta su entidad jurídica, como una empresa, con redes de facturación electrónica específicas de cada país y con las autoridades fiscales para enviar y recibir facturas electrónicas conformes.

Workflow Designer de DocuWare automatiza y controla cómo se procesan las facturas electrónicas dentro de DocuWare. Junto con E-Invoicing Service, los flujos de trabajo gestionan los siguientes escenarios:

• Envío de facturas electrónicas a los destinatarios a través de la red configurada

• Validación de reglas técnicas y de negocio para las facturas electrónicas

• Procesamiento de facturas electrónicas entrantes

Estas funciones se configuran y se utilizan en Configuraciones de DocuWare > Colaboración > Workflow Designer. Para una introducción general a Workflow Designer, consulte la ayuda de Workflow Designer.

Requisitos previos

• Antes de configurar flujos de trabajo para E-Invoicing Service, asegúrese de que E-Invoicing Service esté configurado para la entidad jurídica correspondiente y de que el usuario del flujo de trabajo tenga el permiso Uso sobre la configuración de E-Invoicing Service. Consulte Cómo configurar DocuWare E-Invoicing Service.

• ConfigurationName: durante la configuración de E-Invoicing Service, se asigna un nombre único a cada configuración. Este nombre está disponible como la variable del flujo de trabajo ConfigurationName y se utiliza en la actividad Servicio web para referenciar la configuración correcta de E-Invoicing Service. Asegúrese de que el valor coincida exactamente con el nombre de la configuración tal y como se ha definido en Configuraciones de DocuWare > Integraciones > E-Invoicing.

Funciones de E-Invoicing Service en Workflow Designer

Las funciones de E-Invoicing Service se invocan desde un flujo de trabajo de DocuWare mediante la actividad Servicio web. E-Invoicing Service está preregistrado como DocuWare E-Invoicing en Workflow Designer, por lo que no se requiere ninguna configuración manual de URL.

Para utilizar una función, añada una actividad Servicio web, seleccione DocuWare E-Invoicing en Servicio web definido y elija el endpoint deseado. Configure las pestañas Solicitud, Cabeceras HTTP y Cuerpo de la solicitud HTTP como se describe para cada endpoint a continuación. Opcionalmente, use Asignación de datos para mapear los valores de respuesta a campos de índice del documento, y Códigos de estado para definir cómo se gestionan los códigos de respuesta HTTP.

La actividad Servicio web procesa un documento cada vez. Cada ejecución del flujo de trabajo gestiona una sola factura electrónica y todas las acciones relacionadas con ese documento.

Nota: lógica de procesamiento y sincronización

DocuWare E-Invoicing Service procesa las facturas electrónicas de forma asíncrona. Cuando se envía una factura electrónica a la red, el servicio devuelve inmediatamente un Task ID, pero la entrega real se realiza en segundo plano. El flujo de trabajo no puede comprobar el resultado al instante. En su lugar, debe esperar y consultar el estado actual mediante un endpoint de estado dedicado.

Este comportamiento asíncrono también se aplica a los mensajes de error, que pueden estar disponibles únicamente después de que la red haya procesado la solicitud.

Endpoints en Workflow Designer para E-Invoicing

En el servicio web DocuWare E-Invoicing están disponibles los siguientes endpoints:

1. Enviar factura electrónica

Endpoint: Post /v1/invoices/

Envía una factura electrónica almacenada en DocuWare a la red configurada para su entrega al destinatario.

Parámetros del cuerpo de la solicitud HTTP:

Cuerpo JSON de la solicitud HTTP:

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

Cuerpo JSON de la respuesta HTTP (200):

{
  "taskId": "{id}"
}

El valor de configuration debe coincidir exactamente con el nombre de la configuración definido en Configuraciones de DocuWare > Integraciones > E-Invoicing. Consulte Cómo configurar DocuWare E-Invoicing Service.

2. Obtener actualización de estado

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

Recupera el estado de procesamiento actual de una factura electrónica enviada desde la red. El {id} en la ruta es el Task ID devuelto en la respuesta de una solicitud HTTP anterior realizada en este flujo de trabajo. Almacene este valor en una variable global del flujo de trabajo para pasarlo a este endpoint.

Cabeceras HTTP: Accept: application/json (preconfigurado)

Cuerpo de la solicitud HTTP: ninguno

Configuración de la ruta:

Cuerpo JSON de la respuesta HTTP (200):

{
  "taskId": "{id}"
}

3. Actualizar el estado de la factura

Endpoint: Put /v1/invoices/status/

Actualiza el estado de una factura electrónica recibida almacenada en DocuWare. Utilice este endpoint para establecer el estado de la factura en función de eventos de negocio como la confirmación de pago o la aprobación.

Este endpoint se aplica únicamente a facturas recibidas, es decir, facturas emitidas por un proveedor que se han recibido y requieren acción. Solo los valores de estado enumerados a continuación son válidos para este endpoint.

El estado de las facturas emitidas (salientes) se actualiza automáticamente a través de la red. No es necesario actualizar el estado de una factura enviada desde el flujo de trabajo. Puede usar los valores de estado de las facturas emitidas en el flujo de trabajo de DocuWare para controlar procesos, pero no los utilice para actualizar el estado de una factura dentro de la red.

Para obtener más información y una referencia de los estados de las facturas electrónicas, consulte Información sobre los estados de DocuWare E-Invoicing Service.

Cabeceras HTTP: Accept: application/json + Content-Type: application/json (preconfigurado)

Parámetros del cuerpo de la solicitud HTTP:

Cuerpo JSON de la solicitud HTTP:

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

Cuerpo JSON de la respuesta HTTP (200):

{
  "taskId": "{id}"
}

Valores de estado escritos en statusValue:

4. Crear informe de validación

Endpoint: Post /v1/invoices/validation/report

Ejecuta una comprobación de reglas técnicas y de negocio sobre una factura electrónica almacenada en DocuWare y genera un informe de validación. El resultado se escribe en un campo de índice dedicado y se adjunta un informe de validación a la factura electrónica.

Esta función está disponible actualmente solo para Alemania.

Cabeceras HTTP: Accept: application/json + Content-Type: application/json (preconfigurado)

Parámetros del cuerpo de la solicitud HTTP:

Cuerpo JSON de la solicitud HTTP:

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

Cuerpo JSON de la respuesta HTTP (200):

{
  "taskId": "{id}"
}

Valores del resultado de validación escritos en validationStatusField:

Gestión de errores

Al procesar facturas electrónicas a través de DocuWare E-Invoicing Service, pueden producirse errores en diferentes fases del flujo de trabajo. Antes de abordar cómo gestionar los errores, conviene comprender dónde se informan y qué tipos de errores pueden producirse.

Los errores se notifican de alguna de las siguientes maneras:

• Historial del flujo de trabajo: registra la ejecución del flujo de trabajo y las actividades fallidas

• Task Viewer: muestra el historial de procesamiento y los detalles de errores de las facturas electrónicas enviadas y recibidas. Consulte Cómo configurar DocuWare E-Invoicing Service – Historial

• Respuesta del servicio web: devuelve un mensaje de error directamente desde la API de E-Invoicing Service que se puede mapear a un campo de índice del documento

Tipos de errores y soluciones

Pueden producirse los siguientes tipos de errores. Los pasos necesarios para resolverlos dependen del error específico y de su causa raíz:

Configuración e instalación

• ConfigurationName inválido o no coincidente

• Sin licencia activa o contrato cancelado para la entidad jurídica

• Falta el permiso Uso del usuario del flujo de trabajo sobre la configuración de E-Invoicing Service

• Entorno incorrecto seleccionado (Staging vs. Producción)

Solución: revise y corrija la configuración de E-Invoicing Service e inténtelo de nuevo.

Certificado y autenticación

• Certificado electrónico caducado o inválido (Polonia/KSeF)

• PIN del certificado incorrecto (Polonia/KSeF)

Solución: renueve su certificado electrónico a través del Ministerio de Finanzas polaco y actualícelo en la configuración de E-Invoicing Service.

• El Peppol ID no está activo o no está registrado para su cuenta

Solución: contacte con DocuWare Support.

Destinatario

• No se ha encontrado el Peppol ID del destinatario en la red

Solución: verifique los datos del destinatario en la factura electrónica y contacte con el destinatario para confirmar su Peppol ID.

Documento

• Documento no encontrado en el archivador

• Envío duplicado: la factura ya se ha enviado

• Transición de estado inválida

Solución: compruebe los datos de la factura electrónica y verifique que la configuración del flujo de trabajo sea correcta.

Red y conectividad

• Punto de acceso inaccesible

• Red Peppol temporalmente no disponible

• Servicio KSeF temporalmente no disponible

• Sistema de la autoridad fiscal en mantenimiento

Solución: consulte el estado en la página pública de estado de la red correspondiente.

Cómo gestiona los errores el flujo de trabajo

Cuando se envía una factura electrónica a través del endpoint Enviar factura electrónica, E-Invoicing Service devuelve inmediatamente un Task ID. La entrega real a la red se realiza en segundo plano y normalmente se completa en 1-3 minutos. El flujo de trabajo debe consultar el resultado mediante el endpoint Obtener actualización de estado.

Para la gestión de errores en el flujo de trabajo saliente se recomienda el siguiente patrón:

1. Enviar y almacenar el Task ID

Tras invocar Post /v1/invoices/, almacene el Task ID devuelto en una variable global del flujo de trabajo. Este Task ID es necesario para todas las comprobaciones de estado posteriores.

2. Esperar y consultar el estado

Añada una actividad Retraso de tiempo de 1-3 minutos antes de invocar Get /v1/tasks/{id}/status. Compruebe el resultado de la tarea:

• Completado → continúe con la comprobación del campo de índice del estado de la factura:

  • Estado = sent → factura electrónica entregada correctamente, continúe el flujo de trabajo

  • Estado = error → la entrega ha fallado, proceda con la gestión de errores

• Reintentar → E-Invoicing Service está reintentando la entrega automáticamente. Añada un Retraso de tiempo de aproximadamente 40 minutos y vuelva a consultar mediante Get /v1/tasks/{id}/status. El servicio continuará reintentando durante un máximo de 24 horas.

3. Gestionar errores

Cuando se confirme un error final:

• Utilice la configuración de Asignación de datos de la actividad Servicio web para escribir el mensaje de error de la respuesta de la API en un campo de índice dedicado del archivador (por ejemplo, Errors).

• Cree una Tarea de flujo de trabajo para que el usuario responsable revise el error y actúe según la configuración de la tarea definida.

Información

El mensaje de error devuelto por E-Invoicing Service se puede mapear a un campo de índice del documento mediante la ruta JSON $errorMessage en la pestaña Asignación de datos de la actividad Servicio web. De este modo, el error es visible directamente en el documento sin necesidad de acceder al Task Viewer.

Recomendaciones para la gestión de errores

• Incluya un campo de índice de errores dedicado (por ejemplo, Errors como palabra clave) en el archivador para capturar los mensajes de error de E-Invoicing Service.

• Diseñe la Tarea de flujo de trabajo para casos de error con instrucciones claras para que el usuario sepa cómo proceder.

• Utilice el Task Viewer en Configuraciones de DocuWare > Integraciones > E-Invoicing para revisar el historial completo de procesamiento y los mensajes de error detallados de todas las facturas electrónicas enviadas y recibidas. En determinados casos, en el Task Viewer se puede iniciar un reintento de la tarea de la factura electrónica.

• En el caso de errores de red o conectividad, E-Invoicing Service reintenta automáticamente durante un máximo de 24 horas. Evite el reenvío manual durante este periodo para impedir envíos duplicados.

Referencia de estados de factura

Los siguientes valores de estado se utilizan para las facturas electrónicas. Algunos valores de estado los establece automáticamente el proceso en segundo plano con la red Peppol u otras redes como KSeF en Polonia.

Factura emitida

Factura recibida

Factura simplificada emitida

Versiones compatibles: DocuWare Cloud