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

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

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

• 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 de las facturas electrónicas

• Procesamiento de facturas electrónicas entrantes

• Envío de informes fiscales a partir de los datos o el archivo de una factura electrónica; el envío directo de e-reports no es compatible

• Búsqueda en el directorio de la dirección de una empresa en Peppol Registry & Annuaire

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

Requisitos previos

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

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

• Campos de índice: Se recomienda configurar los siguientes campos de índice en el archivador que se utiliza para procesar las facturas electrónicas:

• TaxReportID

• Network_ID

• Invoice_Status

• Validation_Status

Funciones del E-Invoicing Service en el Workflow Designer

Las funciones del E-Invoicing Service se invocan desde un flujo de trabajo de DocuWare mediante la actividad Servicio web. El E-Invoicing Service está preregistrado como DocuWare E-Invoicing en el Workflow Designer, por lo que no es necesaria 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, Encabezados HTTP y Cuerpo de la solicitud HTTP tal como se describe para cada endpoint más abajo. Opcionalmente, utilice Asignación de datos para asignar 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 única factura electrónica y todas las acciones relacionadas con ese documento.

Nota: Lógica de procesamiento y sincronización

El 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 de inmediato un ID de tarea, pero la entrega real se produce 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 específico.

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

Los siguientes endpoints están disponibles en el servicio web DocuWare E-Invoicing en el Workflow Designer. Utilícelos para automatizar acciones de facturación electrónica directamente desde sus flujos de trabajo de DocuWare.

Endpoints del Workflow Designer para E-Invoicing

Los siguientes endpoints están disponibles en el servicio web DocuWare E-Invoicing:

1. Enviar factura electrónica

Endpoint: Post /v1/invoices/

Envía a la red configurada una factura electrónica almacenada en DocuWare 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 configuration debe coincidir exactamente con el nombre de la configuración tal como se define en DocuWare Configuraciones > Integraciones > E-Invoicing. Consulte Cómo configurar DocuWare E-Invoicing Service.

2. Obtener actualización de estado

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

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

Encabezados 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 y 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 las facturas recibidas, es decir, las facturas emitidas por un proveedor que se han recibido y requieren alguna acción. Para este endpoint solo son válidos los valores de estado que se indican a continuación.

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

Encabezados 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):

{
  taskStatus: "InProcess",
  error: ""
}

Error: 404 Not Found:

Valores de estado que se escriben 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 en una factura electrónica almacenada en DocuWare y genera un informe de validación. El resultado se escribe en un campo de índice específico y se adjunta un informe de validación a la factura electrónica.

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

Encabezados 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 la validación que se escriben en validationStatusField:

5. Enviar informe fiscal a partir de un archivo o los datos de una factura electrónica

Endpoint: Post /v1/tax-reports/create

Envía un informe fiscal a la DGFiP para cumplir las obligaciones de e-reporting obligatorias. El e-report se puede generar a partir de los datos de índice almacenados en DocuWare o enviarse directamente desde un archivo de factura electrónica conforme existente.

Información: Esta función está disponible actualmente solo para Francia.

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

Cuerpo JSON de la respuesta HTTP (200):

{
  "taskId": "{id}"
}

Para obtener más información y una referencia de los estados de los e-reports, consulte Información sobre los estados de DocuWare E-Invoicing Service.
Para obtener más información sobre el proceso de E-Reporting, consulte Información sobre E-Reporting con el DocuWare E-Invoicing Service (próximamente).

6. Búsqueda en el directorio Peppol/Annuaire

Endpoint: Get /v1/directory

Busca la dirección y la información de enrutamiento de una empresa en el Peppol Registry o Annuaire. Este endpoint es síncrono: el resultado se devuelve directamente en la respuesta. No se emite ningún ID de tarea ni es necesario realizar sondeos.

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

Parámetros del cuerpo de la solicitud HTTP: ninguno

Cuerpo JSON de la respuesta HTTP (200):

Este es un ejemplo del cuerpo de respuesta si busca DocuWare con fr y 505184754 a través de este endpoint.

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

Referencia de los campos de respuesta:

Gestión de errores

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

Los errores se notifican de una de las siguientes formas:

• Historial del flujo de trabajo: registra la ejecución del flujo de trabajo y las actividades que han fallado

• Visor de tareas: muestra el historial de procesamiento y los detalles de los 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 del E-Invoicing Service que se puede asignar a un campo de índice del documento

Tipos de errores y soluciones

Pueden producirse los siguientes tipos de errores. Los pasos necesarios para resolver un error dependen del error concreto y de su causa raíz:

Configuración y preparación

• ConfigurationName no válido o que no coincide

• No hay una licencia activa o el contrato se ha cancelado para la entidad jurídica

• El usuario del flujo de trabajo no tiene el permiso Uso en la configuración del E-Invoicing Service

• Entorno seleccionado incorrecto (preproducción frente a producción)

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

Certificado y autenticación

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

• PIN del certificado incorrecto (Polonia/KSeF)

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

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

Solución: Póngase en contacto con DocuWare Support.

Destinatario

• El Peppol ID del destinatario no se encuentra en la red

Solución: Verifique los datos del destinatario en la factura electrónica y póngase en contacto con el destinatario para confirmar su Peppol ID.

Documento

• El documento no se encuentra en el archivador

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

• Transición de estado no válida

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

Red y conectividad

• Punto de acceso inaccesible

• La red Peppol no está disponible temporalmente

• El servicio KSeF no está disponible temporalmente

• El sistema de la autoridad fiscal está 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 mediante el endpoint Enviar factura electrónica, el E-Invoicing Service devuelve de inmediato un ID de tarea. La entrega real a la red se produce en segundo plano y suele completarse en un plazo de 1 a 3 minutos. El flujo de trabajo debe consultar el resultado mediante el endpoint Obtener actualización de estado.

Se recomienda el siguiente patrón para gestionar los errores en el flujo de trabajo saliente:

1. Enviar y guardar el ID de tarea

Después de llamar a Post /v1/invoices/, guarde el ID de tarea devuelto en una variable global del flujo de trabajo. Este ID de tarea es necesario para todas las comprobaciones de estado posteriores.

2. Esperar y consultar el estado

Añada una actividad Retardo de 1 a 3 minutos antes de llamar a Get /v1/tasks/{id}/status. Compruebe el resultado de la tarea:

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

  • Estado = sent → la factura electrónica se ha entregado correctamente; continúe con el flujo de trabajo

  • Estado = error → la entrega ha fallado; continúe con la gestión de errores

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

3. Gestionar los errores

Cuando se confirma un error definitivo:

• Utilice la configuración 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 específico 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 tarea definida.

Información

El mensaje de error que devuelve el E-Invoicing Service se puede asignar 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. Así, el error queda visible directamente en el documento sin necesidad de acceder al Visor de tareas.

Recomendaciones para la gestión de errores

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

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

• Utilice el Visor de tareas en DocuWare Configuraciones > 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, se puede iniciar un reintento de la tarea de la factura electrónica en el Visor de tareas.

• En caso de errores de red o de conectividad, el E-Invoicing Service reintenta automáticamente durante un máximo de 24 horas. Evite el reenvío manual durante este periodo para evitar 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