API V5

Introducción

V5 Traceability Gateway permite el intercambio de datos bidireccional entre la gama de productos V5 Traceability y otras soluciones. La puerta de enlace es muy flexible y proporciona una implementación rápida con muchos ERP diferentes y sistemas externos, lo que permite a los clientes integrar de manera eficiente toda su fábrica. La gama de productos V5 tiene una amplia API para su uso en la integración.

Esta guía proporcionará una descripción general detallada de cómo utilizar los diversos métodos para importar y exportar datos. También detallará cada entidad que se puede importar y los campos posibles para estas entidades.

La puerta de enlace se puede utilizar de 2 formas principales:

• A través de una API REST de interfaz web que utiliza archivos JSON o XML.
• A través del intercambio directo de archivos con documentos CSV o XML.

Ambos métodos se analizarán en esta guía, además de proporcionar ejemplos para las principales áreas de integración de datos.

1. ¿Qué hace la puerta de enlace V5?
2. Diagrama de flujo de datos de ejemplo
3. Guías de integración
4. Documentos de referencia de integración V5
5. Metodología – API V5
   1. Solicitudes de exportación/GET
   2. Solicitudes de importación/POST
   3. ¿Insertar o Actualizar?
   4. Exportar marcadores
   5. Parámetros URI
   6. Registros, transacciones y descriptores del sistema
6. Metodología: uso compartido de archivos CSV
   1. Ordenación de archivos de datos y encabezados
   2. Importaciones
   3. Exportaciones
7. Frecuencia y Secuencia
8. Contáctenos

El servicio de integración de V5 Traceability se puede implementar para cubrir una variedad de puntos de datos, que cada cliente individual puede personalizar completamente según sus requisitos. Estos requisitos se analizarán durante las fases iniciales de la implementación de la trazabilidad V5.

Dependiendo de los requisitos del cliente, V5 Traceability se puede configurar para integrar cualquier cantidad de áreas, como formulación/listas de materiales, programación de trabajos, órdenes de compra y venta y niveles y ubicaciones de inventario.

En esta sección puede encontrar guías específicas para la integración de módulos específicos de Trazabilidad V5:

• Materias primas
• Fórmulas
• Inventario/Ubicación de existencias
• Trabajos/Órdenes de producción
• Ordenes de compra
• Ordenes de venta
• Mudanzas

Para obtener ayuda para instalar y actualizar la API V5, consulte la siguiente documentación:

• Guía de instalación y actualización de API V5

A lo largo de esta guía de métodos de integración de V5 Traceability, haremos uso regular de dos piezas de documentación para ayudarnos. Ambos son útiles independientemente del método de integración que estemos usando. Estos son:

• La Hoja de trabajo de integración V5 que contiene información útil y plantillas para los módulos más comúnmente integrados.
• La Manual de API V5, que se puede utilizar para identificar URI de importación/exportación específicos, además de proporcionar una guía completa para cada clase de datos utilizada por la API V5.

Si usa este método, la API V5 se instalará como un servicio web para facilitar la transferencia de datos. Desde aquí, las transacciones son manejadas por las diferentes clases de módulos disponibles.

Para obtener más información sobre estas clases, los diferentes puntos finales/URI, así como información sobre las diversas clases de bases de datos con las que trataremos cuando usemos la API V5, podemos usar tanto el 'Hoja de trabajo de mapeo de integración V5' y el Sitio web de la API V5 para ayudarnos. Desde aquí podemos utilizar el explorador de paquetes en la parte superior izquierda de esta ventana para navegar por las diferentes secciones del manual de la API.

Haremos uso de estas secciones para crear ejemplos a medida que discutamos los diversos aspectos de la integración de datos a continuación.

Una vez instalados, se puede acceder a los puntos finales de la API a través de un navegador o un cliente REST en:

http://{hostname:port}/V5-API/api

El módulo IntegrationImport tiene una ruta de /integrate/import/

El módulo IntegrationExport tiene una ruta de /integrate/export/

La ruta del módulo 'Transacciones' es /integrate/export/transactions/

Cada método tiene su propia ruta listada en el directorio API V5 como un ‘Target URI’. Esto se puede agregar al final de las rutas anteriores para ejecutar el método.

Cada descripción de método también contiene una ‘request type’, que indica si se trata de una solicitud GET o POST más el URI para ese método dado.

Cualquier solicitud GET o POST se procesará en formato JSON. Todos los campos y objetos están definidos en el paquete de la base de datos que puede encontrar a través de la paquete de servicios.

Como se mencionó anteriormente, el módulo de exportación de API V5 tiene una ruta de:

http://{hostname:port}/V5-API/api/integrate/export/

Entonces, en realidad, esto se vería así (si interactúa a través de una instancia instalada localmente de la API V5):

http://127.0.0.1:8080/V5-API/api/integrate/export/

Lo que vendría después depende de los datos que queramos extraer de V5. Luego nos referiríamos al paquete de servicios, usando las ventanas a la izquierda de la ventana principal de la API para seleccionar el paquete de servicios, seguido de 'IntegrationExport' a continuación.

También podemos usar el enlace de servicios en la página de índice, que luego cargará el resumen de clase para ese paquete, donde podemos elegir la clase 'IntegrationExport'.

Luego se nos mostrará el URI de destino de exportación (1) junto con una lista de puntos finales disponibles para la clase de módulo de exportación. Podemos ver todo esto en detalle haciendo clic en el constructor 'IntegrationExport' (2), o podemos usar el ‘Method Summary’ siguiente tabla (3) para encontrar rápidamente el punto final deseado. También podemos ver el URI de destino para este módulo en la parte superior de la página, por lo que todo lo que tendríamos que hacer ahora es identificar los objetos, campos y valores requeridos.

Así que tomemos la primera entrada en la tabla de resumen de métodos aquí, ‘Batch’. Hacer clic en el enlace de la columna de la derecha (4) nos llevará directamente al punto final que queremos conocer.

Esto nos proporciona la información que necesitamos saber, incluidos los datos que se recuperarán, el tipo de solicitud y, lo que es más importante, el URI de destino de la solicitud.

Entonces, ahora sabemos que si queremos extraer un lote de la API V5, el punto final que tendríamos que alcanzar sería:

http://127.0.0.1:8080/V5-API/api/integrate/export/batch/{batchNumber}

Veamos rápidamente cómo funcionaría esto en la práctica. Podemos comenzar por encontrar un lote que queremos extraer a través de la API, busquemos el lote '50009622' que podemos ver aquí en Centro de Control.

Usando lo que hemos aprendido anteriormente, podemos completar el URI en el cliente REST como tal:

Ejecutar este proceso ahora generará un archivo JSON detallado para ese lote, que luego puede ser consumido y analizado por la aplicación cliente. Un retorno típico para esta solicitud podría verse así.

En muchos casos donde el pluralismo es aplicable a los puntos finales que estamos abordando, por ejemplo, aquí el lote puede convertirse en lotes, podemos usar esto para llamar a una lista de lotes con el ‘export/batches’ URI.

Como se mencionó anteriormente, el módulo de importación de API V5 tiene una ruta de:

http://{hostname:port}/V5-API/api/integrate/import/

Lo que seguiría a esto dependería de qué datos estamos buscando importar a través de la API. Volveríamos a la sección de paquetes de servicios de la Manual de API y haga clic en 'IntegrationImport' (1) esta vez.

Esto se presenta de la misma manera que la página de exportaciones, con el URI de importación (2), el enlace a la parte superior de las páginas de resumen a continuación (3) y la tabla de resumen de métodos (4) donde podemos ver todos los puntos finales disponibles. .

Como antes, solo necesitaríamos encontrar el punto final relevante para los datos que deseamos publicar en el sistema a través de la API.

Tenga en cuenta que la mayoría de los puntos finales POST de importación esperan una matriz para que se puedan enviar varios registros en una sola solicitud. Esto se puede ver mirando los tipos de parámetros para los puntos finales de importación bajo el ‘Method Summary’.

Tomemos los productos básicos como ejemplo aquí:

Lo que esto nos dice aquí es que podemos usar este punto final para importar listas de productos/ingredientes que luego se pueden usar para la formulación. La URI que usaríamos para esto sería:

http://127.0.0.1:8080/V5-API/api/integrate/import/commodity

Podemos ver este punto final en uso a continuación, junto con un archivo de importación de muestra muy básico en formato JSON:

Para ayudarnos a estructurar un archivo de importación JSON, podemos hacer uso del enlace a la sección de paquetes de base de datos relevante del manual de la API presente en el resumen del servicio:

O podemos navegar manualmente a la sección relevante seleccionando la sección de resumen de clase de base de datos de la Página de inicio de la API.

Si navegamos a la página de clase de base de datos a continuación para ‘Commodity’, podemos cómo debemos estructurar o archivo JSON. Por ejemplo, si queremos definir un código de producto al usar este URI, este sería ‘code’, e igualmente para la descripción de la mercancía, esto sería ‘description’.

Observe cómo estos campos están a la izquierda del archivo JSON de ejemplo anterior, junto con otros campos que podemos ver en la captura de pantalla, como ‘defExpiryDays’. También podríamos agregar el costo predeterminado de la mercancía a nuestro archivo, y al verificar a continuación podemos ver que simplemente sería ‘cost’ (1). También tenga en cuenta que cualquier cosa listada aquí como ‘primary key’ (2) es un campo obligatorio para ese extremo, es decir, el archivo no se importará si no está presente.

También podemos atravesar diferentes niveles de la API desde esta clase de base de datos, así que veamos cómo podemos hacer eso para incluir más información sobre nuestros productos básicos. ‘units’.

Hacia el final de esta página nos encontraremos ‘WeightUnit’, que podemos usar como una clase anidada dentro del URI de la mercancía.

Esto nos da nuestra clase de base de datos para ‘units’, que puede sentarse al mismo nivel que las otras clases que ya hemos definido. Para descubrir qué datos podemos anidar aquí podemos hacer clic en ‘WeightUnit’ aquí para buscar las definiciones de esa clase.

Como podemos ver, solo hay 3 puntos de datos dentro de esta clase, y en nuestro ejemplo JSON los estamos usando todos, ‘code’, ‘description’, y ‘conversionRate’. Estos 3 puntos de datos estarían anidados dentro del ‘units’ campo, como se muestra.

Si ejecutamos este archivo JSON como se indicó anteriormente, (dependiendo del cliente que estemos usando) veremos una respuesta de la API, y también podremos ver este producto importado a nuestro 'Materias primas' tabla en el Centro de control.

Cuando se usa la función POST para llegar a los puntos finales de la API V5, esto puede actualizar o insertar un registro. Lo que sucede aquí está definido por la clave principal que intentamos publicar.

Si tomamos nuestro ejemplo de mercancía anterior, vimos en las definiciones de clases de la base de datos que el código de la mercancía es su clave principal. Cuando estemos publicando, si este código ya existe, actualizaremos el registro de ese producto con los nuevos valores incluidos en ese nivel de clase.

Por el contrario, si el código no existe actualmente en la base de datos V5, se creará un nuevo registro.

Sin embargo, si miramos nuestra ‘units’ clase anidada, tenga en cuenta que si bien podemos insertar nuevos datos de unidad si la clave principal de esta clase aún no está presente, no podemos actualizar las unidades existentes utilizando el ‘commodity’ punto final En su lugar, tendríamos que abordar la ‘import/unit’ URI en su lugar.

La API V5 utiliza marcadores de exportación para diferenciar entre los datos que ya se han exportado o no al sistema ERP de un cliente. De manera predeterminada, esto está habilitado para ayudar a exportar datos que el ERP externo aún no ha visto, y una vez que se marcan como exportados en la base de datos V5, estos datos no se incluirán en exportaciones futuras.

Sin embargo, esto se puede deshabilitar según las preferencias del cliente. Esto también se puede deshabilitar si el sistema ERP en uso puede devolver marcadores de exportación a la API V5 para reconocer que ya recibió los datos en cuestión.

En esta situación, se utiliza un acuse de recibo para informar a la API V5 que se han recibido datos; el punto final que se puede utilizar para controlar esto está documentado. esta página.

Si ni la API V5 ni el ERP están configurados para proporcionar marcadores de exportación, entonces, según el punto final utilizado, esto podría devolver una gran cantidad de datos. En estos casos, podemos usar parámetros URI para filtrar la cantidad de datos que se exportan.

La API V5 también utiliza varios parámetros de URI que se pueden usar para reducir aún más nuestras solicitudes del sistema.

Podemos ver si estos parámetros están disponibles para nuestros puntos finales revisando los resúmenes de métodos en nuestro servicio deseado. si podemos ver ‘int’ seguido de un parámetro, luego podemos usar este parámetro para filtrar los resultados que recibiremos de la API.

Por ejemplo, vimos arriba que esto funciona para ‘batch’ al permitirnos filtrar por el número de lote.

Otros ejemplos podrían incluir extraer registros de lotes por fecha, donde podemos usar ‘batch_system_logs/filterFrom/{filterDate}’ (usando convenciones de datación de época).

Para muchos de los módulos que se pueden integrar a través de la API V5, suele ser más conveniente recuperar información de los puntos finales de registro y transacciones. Algunos de ellos se pueden utilizar para varios propósitos (como "registros del sistema"), mientras que otros están más personalizados para módulos específicos (como "transacciones de ventas").

Estos puntos finales utilizan descriptores del sistema para indicar ciertos eventos que suceden (recibir un producto, consumir un ingrediente para la producción, etc.) y son particularmente útiles para mantener la precisión del inventario en todo el sistema V5.

Para revisar estos puntos finales y qué información devuelven/para qué módulos son útiles, haga clic en esta página.

El método de uso compartido de archivos V5 utiliza archivos de "encabezado" csv y csvh para realizar intercambios de datos con V5 Traceability. Para estos intercambios, utilizaríamos archivos de "encabezado" para determinar el orden de los datos tanto para las importaciones como para las exportaciones, y luego importaríamos o recibiríamos un csv exportado que sigue este orden. Podemos echar un vistazo a cómo funcionaría esto en la práctica a continuación.

Ya sea que estemos importando o exportando datos utilizando el método de uso compartido de archivos csv, utilizaremos archivos de encabezado para determinar el orden de los datos. En términos de cómo podemos estructurarlos, aquí podemos hacer uso tanto del 'Hoja de trabajo de mapeo de integración V5' y el en línea Manual de API para ayudarnos con esto. Veamos un ejemplo aquí para un ‘Commodities’ importar desde la hoja de trabajo.

Como podemos ver aquí, SG ya ha estructurado un diseño de encabezado básico aquí, y si miramos en el manual de API en esta clase de base de datos en particular, podemos ver que la mayoría de los campos aquí existen en esta clase, permitiéndonos simplemente usar ‘code’, ‘cost’, ‘bulkUnit’ etc. tal como se definen aquí.

Tenga en cuenta que, de manera similar a cuando estábamos viendo la estructuración de nuestros archivos JSON arriba, la clave principal (code) debe ser incluido

También podemos recorrer las clases de la base de datos de una manera similar a la que vimos al estructurar la importación JSON anterior. Podemos ver esto en nuestro ejemplo anterior con ‘units.code’. Dentro de ‘Commodity’ clase tenemos la ‘WeightUnits’ clase (definida como ‘units’).

Siguiendo este enlace a la ‘WeightUnit’ class nos mostrará que para definir el código de la unidad de peso, esto es ‘code’ en esta clase, así que para atravesar esto desde nuestro ‘Commodity’ el punto de partida seria ‘units.code’.

Podemos atravesar tantos niveles como queramos aquí, solo tienen que estar vinculados en el manual de la API.

Haríamos lo mismo para estructurar los encabezados que usaríamos para las exportaciones, usando las definiciones de clase de base de datos apropiadas para identificar qué datos queremos recibir del sistema y en qué orden.

Los archivos de encabezado deben construirse como archivos csv, con 1 valor en cada celda en la fila superior hasta que hayamos definido todos los datos que queremos importar o exportar. Este archivo csv debe guardarse y luego editarse su extensión para que sea un ‘csvh’ archivo (la vista de extensión de archivo en Windows debe estar habilitada para hacer esto).

Cualquier edición del archivo csvh debe realizarse después de volver a cambiarlo a un archivo csv y editarlo en este formato.

Los encabezados utilizados para las importaciones deben colocarse en:

<installdir>\SG Control Center\gateway\import\column_defs

Los encabezados utilizados para las exportaciones deben colocarse en:

<installdir>\SG Control Center\gateway\export\order

Ahora podemos ver cómo haríamos para realizar nuestras importaciones y exportaciones.

Una vez que nuestros archivos de encabezado relevantes estén en su lugar, debemos completar nuestro archivo csv para importarlo.

Como ya se mencionó, los datos en nuestro archivo csv deben adherirse a la misma estructura que su archivo de encabezado correspondiente, es decir, los datos correctos deben estar en la columna correcta para que la importación tenga éxito. Para seguir con nuestro ejemplo de productos básicos, podemos ver que en este ejemplo a continuación, hemos incluido los datos del encabezado para ayudarnos con la entrada de datos. Sin embargo, no es necesario incluirlo (consulte 'Ignorar encabezados' a continuación).

Una vez que hayamos configurado esto, podemos continuar llenando el csv para incluir todos los productos que queremos importar.

Con el csv completo, las importaciones se pueden realizar colocando los archivos csv con el formato y el nombre apropiados en ‘\SG Control Center\gateway\import’. Las convenciones de nomenclatura para estos archivos se definen en la hoja de trabajo de mapeo de integración V5, por lo que para los productos básicos podemos ver que esto es:

Entonces, por ejemplo, nuestro nombre de archivo podría llamarse 'commodity-0530231803.csv para decirnos que esto se importó el 30^th mayo de 2023 a las 18:03. No hay una preferencia de orden de fecha/hora establecida, por lo que SG recomendaría usar cualquier formato que funcione mejor para cada cliente aquí (esto puede terminar siendo determinado por el ERP externo en uso).

Después de colocar nuestros archivos en la carpeta correcta, Control Center los procesará automáticamente, siempre que las importaciones estén habilitadas en Gateway. El sistema proporcionará un diálogo para informarnos si el proceso fue exitoso o no. Puede encontrar más información sobre esto, con registros, en la sección 'Puerta de enlace' del Centro de control.

Los archivos también se pueden importar manualmente desde otras ubicaciones haciendo clic con el botón derecho en el icono del Centro de control en el sistema y seleccionando Puerta de enlace > Importar archivo.

Esto abrirá un cuadro de diálogo dentro del Centro de control para seleccionar el archivo csv apropiado.

Dentro del propio Gateway podemos establecer opciones contra el proceso de importación:

Los ajustes aquí se pueden definir de la siguiente manera:

• Importación habilitada – habilita la importación, lo que permite que Gateway escanee la carpeta de importación en busca de csv a medida que se colocan allí.
• Insertar entidades secundarias – permite que Gateway cree dinámicamente entidades internas si están vinculadas dentro del archivo csv. Un buen ejemplo de esto podría ser una importación de fórmula que enumere productos que aún no están presentes en la base de datos. El Gateway creará estas entidades 'secundarias' para nosotros en este caso, siempre que se proporcione la clave principal para el producto (código).
• Ignorar encabezados – obliga al Gateway a omitir la primera línea (fila) de un csv importado. Esto es útil si el archivo de encabezado está incluido en el archivo de importación csv.
• Nivel de validación – establece cómo se validan los datos a medida que el Gateway los importa. Hay 2 opciones aquí:
  • Advertir – Si existe un error en un archivo y no se puede importar una línea, el sistema le avisará pero seguirá intentando procesar el resto del archivo.
  • aborto involuntario – Si existe un error en un archivo y la línea no se puede importar, el sistema abortará el proceso y le informará del error.

Los cambios en la configuración se pueden aplicar en la parte superior derecha de este panel. El Centro de control debe reiniciarse para que los cambios surtan efecto.

La exportación a través del método de uso compartido de archivos csv se gestiona en gran medida mediante el archivo de encabezado y la información que solicita del sistema. Si los estructuramos correctamente usando el manual de la API, entonces deberíamos recibir todos los datos que queremos en el orden correcto.

Dentro del propio Gateway también podemos establecer opciones frente al proceso de exportación:

Aquí podemos usar las casillas de verificación provistas para seleccionar qué datos deseamos exportar, según los puntos de datos que deseamos ver.

Tenga en cuenta que las clases de base de datos de inicio aquí, como ‘BatchConsumption’ y ‘SystemLogs’ son diferentes de aquellos con los que comenzaríamos para las importaciones, pero siempre que podamos navegar con éxito el manual de API para estas clases, podemos producir un archivo de encabezado adecuado.

Una vez que hemos seleccionado lo que queremos exportar, es simplemente cuestión de ingresar un intervalo de exportación (en milisegundos) en la parte superior izquierda y aplicar este valor (0 nunca exportará) en la parte superior derecha. El Centro de control debe reiniciarse para que los cambios surtan efecto.

Los archivos csv exportados se colocarán en ‘<installdir>\SG Control Center\gateway\export’ by default.

Independientemente de la metodología utilizada para la integración con V5 Traceability, la frecuencia y el nivel de automatización de las importaciones y exportaciones de datos es un elemento del proceso que se puede construir para adaptarse a los requisitos de cada cliente.

Esto puede hacerlo manualmente el cliente o puede automatizarse para capturar la salida de un ERP externo desde una ubicación específica en el servidor del cliente.

También se puede imponer un orden específico de importaciones en esta etapa, por ejemplo, podemos importar una lista de materiales antes de una orden de trabajo relacionada con esa lista de materiales. Podríamos hacer esto cargando los archivos en secuencia en el directorio de importación o en los puntos finales de API URI.

Como se muestra arriba, también podemos configurar la puerta de enlace para exportar a intervalos específicos para enviar los datos al sistema ERP.

Las importaciones y exportaciones pueden administrarse casi en tiempo real o realizarse a intervalos establecidos. Usando la ruta API, tanto las importaciones como las exportaciones se pueden administrar más fácilmente casi en tiempo real. La frecuencia de importación para el método de uso compartido de archivos csv depende de la solución ERP/middleware individual que se implemente, mientras que la frecuencia de exportación se administra a través del Centro de control, como se describe anteriormente.

¿Está interesado en V5 Traceability y la integración de datos que proporciona? Póngase en contacto con nuestro equipo de ventas esta página!