Servicios Web - EXFID

Introducción

ExFlow puede importar documentos de varias fuentes, como Sistema de Archivos Local, Almacenamiento de Azure o Servicios Web.

Esta página describe el Servicio Web de ExFlow EXFID: qué hace, cómo configurarlo y qué métodos ofrece. EXFID es un servicio web SOAP, por lo que la integración puede escribirse en cualquier lenguaje que pueda enviar peticiones SOAP, por ejemplo C# o VB.NET.

Con EXFID, los integradores externos o partners de Business Central pueden enviar facturas electrónicas a ExFlow utilizando un protocolo estandarizado.

General

Una factura importada en ExFlow normalmente consta de dos archivos:

• Un archivo XML con la factura en una estructura conocida.
• Un archivo PDF con una presentación de la factura.

En algunos casos solo se requiere uno de los dos archivos:

• Solo XML: Si la Definición de Intercambio de Datos tiene una hoja de estilos (XSL), ExFlow genera el PDF a partir del XML.
• Solo PDF: Si el PDF es un archivo PDF/A-3 con un XML incrustado, por ejemplo ZUGFeRD o Factur-X, ExFlow extrae el XML y cualquier adjunto incrustado del PDF.

La importación a través de EXFID la inicia el sistema externo, no ExFlow ni una entrada de Cola de Trabajos. El sistema externo llama a EXFID en Business Central, y cada llamada crea un Documento Entrante con los archivos como Adjuntos de Documentos Entrantes. Los documentos se procesan después, cuando se ejecuta la importación en el Diario de Importación de ExFlow.

Business Central / ExFlow

Instale ExFlow y ejecute el Asistente para obtener una configuración.

Importe una Definición de Intercambio de Datos (DED) adecuada, ya sea una de ExFlow o una DED existente en Business Central.

Servicio Web EXFID

Vaya a: Configuración de ExFlow --> Crear/actualizar servicios web predeterminados

Asegúrese de que los servicios web EXFID y EXFWEB existan en Servicios web en Business Central. Si faltan, ejecute Crear/actualizar servicios web predeterminados en la Configuración de ExFlow.

La dirección SOAP de EXFID se muestra en Servicios web en Business Central. Para Business Central online tiene este formato:

https://api.businesscentral.dynamics.com/v2.0/<tenant id>/<environment>/WS/<company name>/Codeunit/EXFID

Configuración de ExFlow

Vaya a: Configuración de ExFlow --> Importación OCR

Campo	Descripción
Tipo de Intercambio de Datos Web Def.	Seleccione el Tipo de Intercambio de Datos utilizado para los documentos importados a través de EXFID. Si la lista está vacía, ejecute Importar Definiciones de Intercambio de Datos en la Configuración de ExFlow e importe una o más Definiciones de Intercambio de Datos.
Web Optional Doc. XPath	Opcional. El XPath en el XML de la factura que apunta a los adjuntos opcionales. Más información en Adjuntos Opcionales más abajo.

Diario de Importación

Vaya a: Diarios de Importación de ExFlow

Cree o configure un Diario de Importación de ExFlow para procesar los documentos importados a través de EXFID.

Para crear un nuevo Diario de Importación de ExFlow, edite la lista y establezca un Nombre y una Descripción para el nuevo diario. Luego, establezca Tipo de Origen en Servicio Web.

Procese los documentos importados ejecutando Importar Documentos en el Diario de Importación, o ejecutando Importar Documentos por Lote.

Métodos

Todos los archivos se envían como texto codificado en Base64. El contenido también puede comprimirse con gzip antes de codificarse en Base64. ExFlow lo detecta y lo descomprime automáticamente.

Método	Descripción
AddDocument	Envía un documento. Parámetros: nombre del archivo XML, archivo XML, nombre del archivo PDF, archivo PDF.
AddDocumentByDocumentId	Igual que AddDocument, pero con un Document Id. Se utiliza para vincular adjuntos enviados previamente con AddAttachment.
AddAttachment	Envía un adjunto opcional antes del documento. Devuelve un Document Id, que luego se utiliza en AddDocumentByDocumentId.
AddAttachmentChunk	Igual que AddAttachment, pero para archivos grandes enviados en varias partes.
AddDocumentChunk	Envía un documento grande en varias partes.
CreateDocumentFromChunks	Crea el documento a partir de todas las partes enviadas con AddDocumentChunk.

Documentos Grandes – Chunks

Los archivos grandes pueden dividirse en varias partes (chunks) y enviarse una a una.

1. Llame a AddDocumentChunk con Chunk Id 1 y un Document Id vacío. ExFlow devuelve un Document Id.
2. Llame a AddDocumentChunk para las siguientes partes con el mismo Document Id y Chunk Id 2, 3, etc. Los nombres de archivo (XML y PDF) solo se envían con la última parte.
3. Llame a CreateDocumentFromChunks con el Document Id. ExFlow une las partes en el orden de Chunk Id y crea el documento.

El texto Base64 se divide en partes, y las partes se vuelven a unir en el mismo orden. Las partes que no se hayan utilizado en el plazo de una hora se eliminan.

Adjuntos Opcionales

Se pueden agregar adjuntos opcionales para incluir más documentos que el XML y el PDF. Hay dos formas:

Adjuntos Incrustados
Algunos formatos XML, como Peppol y OIOUBL, incluyen los adjuntos en el XML como datos codificados en Base64, opcionalmente comprimidos con gzip. Para ver cómo se configura, importe la Definición de Intercambio de Datos de Peppol u OIOUBL. La misma configuración puede utilizarse para cualquier formato XML.

Adjuntos Pre-Enviados
Si el formato XML no soporta adjuntos incrustados, o si incrustarlos es técnicamente difícil, los adjuntos pueden enviarse antes del documento:

1. Llame a AddAttachment (o AddAttachmentChunk para archivos grandes) para cada adjunto. La primera llamada devuelve un Document Id. Utilice el mismo Document Id para los siguientes adjuntos.
2. Llame a AddDocumentByDocumentId con el mismo Document Id para enviar el XML y el PDF.

Todos los adjuntos enviados con ese Document Id se agregan al Documento Entrante. Si Web Optional Doc. XPath está configurado en la Configuración de ExFlow, solo se agregan los adjuntos cuyo nombre de archivo se encuentra en ese XPath en el XML de la factura. Si el valor en el XPath es una URL, ExFlow descarga el archivo desde esa URL en su lugar.

Los adjuntos que no se hayan utilizado en el plazo de una hora se eliminan.

Autenticación

OAuth

Desde ExFlow 19.2, EXFID soporta la autenticación OAuth (de servicio a servicio). Esto es obligatorio para Business Central online.

1. Registrar una aplicación en Azure
Vaya a: Portal de Azure --> Microsoft Entra ID --> Registros de aplicaciones

1. Registre una nueva aplicación, asígnele un nombre y seleccione el tipo de cuenta relevante.
2. Copie el Id. de aplicación (cliente). Es necesario en Business Central y en la integración.
3. Cree un secreto de cliente (o certificado) para la integración.
4. En Permisos de API, agregue Dynamics 365 Business Central --> Permisos de aplicación --> API.ReadWrite.All.
5. Haga clic en Conceder consentimiento de administrador. Esto requiere un Administrador Global o un usuario con permiso para conceder el consentimiento de administrador.

2. Crear la Aplicación de Microsoft Entra en Business Central
Vaya a: Aplicaciones de Microsoft Entra

1. Cree una nueva ficha e introduzca el Id. de cliente del Registro de Aplicación.
2. Agregue una descripción relevante y establezca Estado en Habilitado.
3. En Conjuntos de Permisos de Usuario, agregue el conjunto de permisos EX WEB SERVICE. Deje el campo Empresa en blanco para que se aplique a todas las empresas.
4. Haga clic en Conceder consentimiento.

La integración ahora puede obtener un token de acceso de Microsoft Entra ID (flujo de credenciales de cliente, ámbito https://api.businesscentral.dynamics.com/.default) y llamar a EXFID con él.

Clave de Acceso al Servicio Web

Una Clave de Acceso al Servicio Web solo puede utilizarse con Business Central on-premises o un contenedor local. Business Central online no admite Claves de Acceso al Servicio Web.

Abra la tarjeta de usuario en Business Central y cree una Clave de Acceso al Servicio Web. Utilice el nombre de usuario y la clave como credenciales en la integración.