BRIDGE - Manual de servicios de integración WSDL / XML (4-x)

3. Acerca del manual

3.1 Propósito y alcance

El presente manual de usuario tiene como finalidad la capacitación al usuario que desee utilizar los servicios provistos por Bridge para la integración con otros sistemas que provean de la información requerida de maestros y configuraciones generales para el funcionamiento de Bridge en su operatoria de tiendas con sus puntos de venta.

Se detallan los campos requeridos por cada entidad, los errores posibles y se proveen algunos escenarios de aplicación del servicio para las diferentes entidades.

En el presente documento se detallan las entidades de los maestros de Bridge que se podrán actualizar.

4. Bridge Core Server SOAP

4.1.1 Invocar un Servicio

Los servicios de BCore son expuestos vía SOAP definiendo métodos genéricos que reciben el nombre de la interfaz que agrupa servicios relacionados, y un xml como parámetro, el cual tiene nombre de la operación y parámetros de la misma. Dicho servicio retorna un xml como respuesta. Este xml se recibe como un simple string.

Por ejemplo, para ejecutar los servicios de proveedor de ítem, se deberá invocar el método SOAP

String execute(String service, String request, String store)

• String store: este parámetro opcional (el cual permite definir que el envío se realiza a una tienda específica, de no definirse o encontrarse con el valor 0 será para todas las tiendas)

a la siguiente url:

~ /bridge/services/bridgeCoreSOAP?wsdl

Por ejemplo:

http://localhost:8181/bridge/services/bridgeCoreSOAP?wsdl

NOTA: IP: PUERTO DE API (generalmente es el que termina en 1, con respecto al puerto de instalación del BM)

El parámetro service, es el nombre del servicio y el parámetro request será un xml con el nombre de la operación a ejecutar y sus parámetros. Dicho xml tiene la siguiente estructura básica:

<bridgeCoreRequest>

<operation>createOrUpdate</operation>

  <params>

    …

  </params>

</bridgeCoreRequest>

• operation: Nombre de la operación

• params: Parámetros de la operación.

4.1.1 Ejemplo de invocaciones a servicio:

El primer ejemplo muestra como invocar un servicio para crear o modificar uno o más proveedores:

service: supplier

request:

<bridgeCoreRequest>

<operation>createOrUpdate</operation>

  <params>

    <suppliers type=”list”>

     <supplier type=”bean”>

    <code>PR1</code>

     <name>Proveedor1</name>

     <fantasyName>Proveedor1 Fantastico</fantasyName>

<address>Avda. Santa Fe 1234</address>

<phone>011-155669800</phone>

<fiscalId>3-55555555-66</fiscalId>

    <activeFlag>true</activeFlag>

     </supplier>

 <supplier type=”bean”>

    <code>PR2</code>

     <name>Proveedor2</name>

     <fantasyName>Proveedor2 Fantastico</fantasyName>

<address>Avda. Garibaldi 9874</address>

<phone>011-1541878591</phone>

<fiscalId>3-44444444-66</fiscalId>

    <activeFlag>true</activeFlag>

     </supplier>

    </suppliers>

  </params>

</bridgeCoreRequest>

Donde operation es el nombre del método especifico a ejecutar para proveedores y params son los parámetros pasados a dicho método.

Cómo se puede ver en este ejemplo, se está pasando un listado de proveedores (suppliers). Dentro de este tag, hay un tag por cada proveedor (supplier) y dentro de este, los atributos propios del proveedor.

<supplier type=”bean”>

           <code>PR2</code>

           <name>Proveedor2</name>

<fantasyName>Proveedor2 Fantastico</fantasyName>

<address>Avda. Garibaldi 9874</address>

<phone>011-1541878591</phone>

<fiscalId>3-44444444-66</fiscalId>

          <activeFlag>true</activeFlag>

</supplier>

Este método devolverá un xml como el siguiente:

<?xml version="1.0" encoding="UTF-8" ?>

<bridgeCoreResponse>

  <ack>0</ack>

  <message></message>

</bridgeCoreResponse>

Donde ack es el código de error y message es el mensaje de dicho error. En el caso de ack sea 0, significa que el servicio se ejecutó sin errores.

En el siguiente ejemplo, para modificar un:

service: brand

request:

<bridgeCoreRequest>

<operation>createOrUpdate</operation>

<params>

<brands type=”list”>

<brand type=”bean”>

<name>Marca Nueva</name>

<activeFlag>true</activeFlag>

<code>MNU</code>

</brand>

<brands>

</params>

</bridgeCoreRequest>

Y la response en caso de éxito:

<?xml version="1.0" encoding="UTF-8" ?>

<bridgeCoreResponse>

  <ack>0</ack>

  <message></message>

</bridgeCoreResponse>

4.1.2 Request de referencia

Los mensajes de requerimiento tendrán la siguiente estructura.

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.business.soap.bridge.synthesis.com/">

   <soapenv:Header/>

   <soapenv:Body>

      <ser:execute>

         <!--Optional:-->

         <service>?</service> ** nombre del servicio a invocar **

         <!--Optional:-->

         <request>?</request> ** request de BridgeCoreRequest según ejemplo de cada servicio (en punto 7 - apéndice) **

         <!--Optional:-->

         <store>?</store> ** tiendas a ser enviado el requerimiento, puede ir vacío o con un 0 para todas las tiendas**

      </ser:execute>

   </soapenv:Body>

</soapenv:Envelope>

Ejemplo de request de marca (brand)

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:ser="http://services.business.soap.bridge.synthesis.com/">

<soapenv:Header/>

<soapenv:Body>

<ser:execute>

<!--Optional:-->

<service>brand</service>

<!--Optional:-->

<request> <![CDATA[ ** para el encapsulado de datos dentro del request **

<bridgeCoreRequest>

   <operation>createOrUpdate</operation>

   <params>

<brands type="list">

<brand type="bean">

<name>INCA</name>

<description>INCA KOLA</description>

<disabled>false</disabled>

</brand>

<brand type="bean">

<name>COCA</name>

<description>COCA COLA</description>

<disabled>false</disabled>

</brand>

  </brands>

  </params>

  </bridgeCoreRequest> ]]>

</request>

<!--Optional:-->

<store>0</store>

</ser:execute>

</soapenv:Body>

</soapenv:Envelope>

4.2 Manejo de errores

Cuando en la ejecución de BridgeCore ocurre un error, en la propiedad ack de la response se devuelve el código del mismo y en la propiedad message, el mensaje de dicho error.

Por ejemplo, el siguiente error es retornado cuando se intenta ejecutar algo, y la sesión de la terminal ha expirado:

<bridgeCoreResponse>

<ack>-1</ack>

<message>'000000000100265919ST' no existe. </message>

</bridgeCoreResponse>

5. Servicio de actualización

A continuación se detallan los diferentes maestros que se podrán popular.

5.1 Servicios de actualización de maestros de artículos

A continuación se describen los servicios que se ofrecen para la actualización de maestros de artículos, y sus entidades relacionadas. Cada uno de los servicios permite crear o actualizar las entidades mediante la operación “createOrUpdate”.

Para no repetir para cada servicio los valores de retorno en caso de éxito, se describirá aquí los campos relevantes que sirven para todos los casos, y cualquier particularidad será descripta en el punto correspondiente.

Los valores de retorno relevantes son:

Ejemplos de requerimientos para cada servicio pueden encontrarse en el apéndice.

5.1.1 Proveedores

Nombre del Servicio: supplier

Parámetros de entrada:

La lista suppliers debe contener entidades “supplier”, las cuales poseen la siguiente estructura:

NOTA:

Para el servicio suppplier al validar el email se utiliza una librería de Apache, que se encarga de determinar si un mail es válido o no (https://commons.apache.org/proper/commons-validator/)

El email “[email protected]” para la librería es inválido.

5.1.2 Marca del artículo

Nombre del Servicio: brand

Parámetros de entrada:

La lista brands debe contener entidades “brand”, las cuales poseen la siguiente estructura:

5.1.3 Niveles de Jerarquía de los artículos

Nombre del Servicio: merchandiseHierarchy

Parámetros de entrada:

La lista merchHierarchyLevels debe contener entidades “hierarchyLevel”, las cuales poseen la siguiente estructura:

La lista merchHierarchyGroups debe contener entidades “hierarchyGroup”, las cuales poseen la siguiente estructura:

5.1.4 Unidades de medida

Nombre del Servicio: unitOfMeasure

Parámetros de entrada:

La lista uoms debe contener entidades “uom”, las cuales poseen la siguiente estructura:

5.1.5 Impuesto IVA de los artículos
Nombre del Servicio: vatType

Parámetros de entrada:

La lista vatTypes debe contener entidades “vatType”, las cuales poseen la siguiente estructura:

5.1.6 Impuestos internos de los artículos

Nombre del Servicio: internalTax

Parámetros de entrada:

La lista internalTaxes debe contener entidades “internalTax”, las cuales poseen la siguiente estructura:

5.1.7 Depósitos

Los depósitos son los lugares físicos donde el retailer guarda mercadería, no incluye contenedores, barcos, o camiones que están en tránsito.

Nombre del Servicio: location

Parámetros de entrada:

La lista locations debe contener entidades “location”, las cuales poseen la siguiente estructura:

5.1.8 Maestro de artículos

Este servicio tiene dependencias de otros maestros (marca, proveedores, niveles de jerarquía, unidades de medida, impuesto IVA, depósitos, taxCategory) En caso de que se envíen artículos con datos de los maestros mencionados como dependencias, se debe considerar que esas referencias se hayan informado previamente a Bridge.

Nombre del Servicio: item

Parámetros de entrada:

La lista items debe contener entidades “item”, las cuales poseen la siguiente estructura:

La lista internalTaxes debe contener entidades “internalTax”, las cuales poseen la siguiente estructura:

Nota: cuando la nueva property “store.internalTaxInformedWithItem” esté en false, no considerar el tag internalTaxes al importar ya que se usará el servicio de relación de artículos con impuestos internos.

Cuando la property esté en true, se mantiene la lógica actual: con cada importación del servicio “ítem” se borran los impuestos internos asociados al ítem en el modelo y se crean las relaciones incluidas en el servicio.

La lista itemPictures debe contener entidades “itemPicture”, la cual posee la siguiente estructura:

Consideraciones del servicio para las imágenes:

• En el servicio siempre se añaden nuevas imágenes. No sirve ni para editar ni para eliminar imágenes existentes. En caso de querer llevar a cabo dichas acciones, se deberá realizar desde el BM.

• (*) Notas sobre configuración miniatura, base y template

  • En caso de ya existir una imagen configurada como miniatura o template, y en el servicio se especifica una nueva imagen como tal, se utilizará la nueva imagen para miniatura o template.

  • Si no se especifica ninguna imagen como miniatura o template, se tomará la primera como tal.

  • Si se especifica más de una, también se tomará la primera.

• (**) Notas sobre prioridad de las imágenes

  • Al ser un campo opcional, si viene una prioridad indicada para la imagen, se prioriza esa.

    •  En caso de existir una lista de imágenes ya asociadas al ítem que tenían la misma prioridad esta se pisa y queda priorizada la indicada en los últimos artículos recibidos por el servicio.

  • Si no viniera indicada la prioridad en la importación, se le da la prioridad siguiente a la que tenía la última imagen de ese ítem.

    • Ej: articulo 123 (imágenes nuevas C y D)

Imágenes nuevas C y D sin indicar prioridad

El servicio actual de ítems se extiende con algunos datos adicionales como el producto (si viene informado lo asocia, sino lo crea para tener compatibilidad hacia atrás), los atributos, el displayOrder y atributos.

Se extienden los sig campos:

5.1.9 Relación de artículos con impuestos internos

Nombre del Servicio: itemInternalTax

Parámetros de entrada:

La lista itemInternalTaxes debe contener entidades “itemInternalTax”, las cuales poseen la siguiente estructura:

5.1.10 Códigos de barras – alias

Este servicio tiene dependencia de otro maestro (items) En caso de que se envíen códigos de barras asociados a artículos, los mismos se deben haber informado previamente a Bridge.

Se validará que el código de barras no exista asociado a otro ítem.

Nombre del Servicio: alias

Parámetros de entrada:

La lista aliases debe contener entidades “alias”, las cuales poseen la siguiente estructura:

5.1.11 Artículos de tipo Stock

Este servicio tiene dependencia de otro maestro (items) En caso de que se envíen artículos para ser definidos del tipo stock, los artículos se deben haber informado previamente a Bridge.

Nombre del Servicio: stockItems

Parámetros de entrada:

La lista stockItems debe contener entidades “stockItem”, las cuales poseen la siguiente estructura:

5.1.12 Relación de artículos con proveedores

Este servicio permite tener por proveedor la lista de artículos que el mismo puede entregar a la tienda. Será utilizada para la generación de órdenes de compra.

Nombre del Servicio: itemSupplierItem

Parámetros de entrada:

La lista itemSupplierItems debe contener entidades “itemSupplierItem”, las cuales poseen la siguiente estructura:

5.1.13 Lista de precios de artículos

Este servicio tiene dependencia de otro maestro (items) En caso de que se envíen listas de precios, los artículos se deben haber informado previamente a Bridge.

El lote de registros debería pertenecer a la misma tienda. Por tal motivo en el request a enviar, el campo <store>codigoTienda</store> debería venir informado el código de la tienda a la cual pertenecen los registros informados dentro del mismo lote. No se debería enviar <store>0</store>. Esto es para evitar que todas las tiendas reciban registros que no son de esa tienda.

Nombre del Servicio: itemSellingPrices

Parámetros de entrada:

La lista itemSellingPrices debe contener entidades “itemSellingPrice”, las cuales poseen la siguiente estructura:

La lista items debe contener entidades “item”, las cuales poseen la siguiente estructura:

Nota: los campo tachados no se están importando en B7

5.1.14 Articulos de tipo Kits

En este servicio se registran los kits. Contiene un id interno de la tabla y luego la lista de todos los kits que se hayan definido.

Nombre del Servicio: aggregateItem

La lista aggregateItems debe contener entidades “aggregateItem”, las cuales poseen la siguiente estructura:

La lista aggregateItems debe contener entidades “aggregateItem”, las cuales poseen la siguiente estructura:

5.1.15 Artículos enlazados o linkeados

Este servicio tiene dependencia de otro maestro (items) En caso de que se envíen artículos para ser enlazados o linkeados, los artículos se deben haber informado previamente a Bridge.

Este servicio definen las relaciones de artículos linkeados. Al venderse el código de ítem del campo ID_ITM (padre del kit) automáticamente se vende el artículo del código ID_ITM_MBR (hijos componentes) con la cantidad que se haya definido

Nombre del Servicio: linkedItem

Parámetros de entrada:

La lista linkedItems debe contener entidades “linkedItem”, las cuales poseen la siguiente estructura:

• En el servicio linkedItem, se considerar la <operation>delete</operation> 

• Afecta la tabla CO_CLN_ITM. Si existe el registro informado en el servicio, se elimina el registro sino se informa del error.

5.1.16 Relación entre artículos

Este servicio tiene dependencia de otro maestro (items). En caso de que se envíen artículos para ser relacionados, los artículos se deben haber informado previamente a Bridge.

La entidad permite definir relaciones entre artículos (complementarios, sustitutos..)

Nombre del Servicio: itemRelated

Parámetros de entrada:

La lista itemsRelated debe contener entidades “itemRelated”, las cuales poseen la siguiente estructura:

• En el servicio itemRelated, se agrega la operación de eliminar.

  • <operation>delete</operation> 

  • Impacta en la tabla CO_ASCTN_RLTD_ITM. Si existe el registro informado en el servicio, se eliminar el registro sino se informa el error.

5.1.17 Artículos del tipo servicio

Este servicio tiene dependencia de otro maestro (items) En caso de que se envíen artículos para ser definidos como servicios, los artículos se deben haber informado previamente a Bridge.

Nombre del Servicio: serviceItem

Parámetros de entrada:

La lista serviceItems debe contener entidades “serviceItem”, las cuales poseen la siguiente estructura:

5.1.18 Stock por depósito

Este servicio tiene dependencias de otros maestros (ítems y depósitos) En caso de que se envíen las unidades en stock, los artículos y depósitos ya se deben haber informado previamente a Bridge.

Este servicio es utilizado para realizar la carga inicial de stock en una tienda ya sea porque se trata de una nueva tienda o porque se quiere pisar el stock al inicio del período con el stock del ERP. Es preciso especificar en el request a qué tienda debe ser replicado el stock.

Consideraciones:

• Si se trata de una tienda Bridge, la misma debe estar cerrada para que el stock se actualice. 

• Las reservas realizadas serán dadas de baja

• Si hubieran artículos serializables o que requieren lote, se deberá enviar el listado completo de series / lotes con stock. 

  • Si hubiera diferencias entre la lista de series / lotes y las cantidades informadas, el stock de ese artículo no será actualizado.

• No se actualizará el stock de los ítems no informados. Es decir, si la relación entre la tienda/depósito/SKU/estado no fuera enviada en el servicio, el stock de la base de datos no será actualizado

Nombre del Servicio: stock

Parámetros de entrada:

La lista stocks debe contener entidades “stock”, las cuales poseen la siguiente estructura:

La lista ítems debe contener entidades “item”, las cuales poseen la siguiente estructura:

La lista ítems serializables o que requieren lote debe contener entidades “serializedItem”, las cuales poseen la siguiente estructura:

Nota: la sumatoria de stockUnits de la lista debe ser igual a la cantidad de stockUnits informada en el item

5.2 Actualización de stock por movimientos de abastecimiento externos a Bridge

5.2.1 Producto

Esta entidad agrupa los diferentes ítems cuando comparten atributos. La relación con Ítem (AS_ITM) es uno a mucho, siendo obligatorio al menos un ítem por cada producto.

No es requerido el uso de la entidad “producto” si no se utilizarán atributos y/o atributos de especificación. De ser utilizados los mismos, se requiere un orden en el envío de los datos.

Para el envío de entidades a través de los servicios de integración, se debe considerar el orden de envío de las entidades:

• Alta de atributos y atributos de especificaciones (ambos casos opcionales).

• Alta del producto con sus atributos y especificaciones (deben ya existir en Bridge)

  • Enviar el producto con la lista de atributos y especificaciones que se deseen relacionar al mismo.

• Enviar el o los ítems asociados al producto.

• En aquellos casos en los cuales no se requiera el alta de productos, sólo se enviará al ítem (sin atributos, especificaciones ni producto asociado).

  • Sólo en este caso cuando Bridge recibe por servicio al ítem, genera durante el proceso de importación el registro correspondiente al producto.

  • Para BridgePOS tanto para la venta como para el manejo de stock es por medio del ítem.

  • El producto sólo permite/facilita el agrupamiento y detalle de atributos para búsquedas y para Bridge WEB.

Nombre del Servicio: product

Parámetros de entrada:

La lista products debe contener entidades “product”, las cuales poseen la siguiente estructura: