Integrando Bridge Core desde terminales externas - BRIDGE 7

1. Introducción

1.1 ¿Qué es Bridge Core?

Bridge Core es una solución que permite ejecutar operaciones y reglas devolviendo el resultado en un formato entendible por el cliente para poder ser utilizadas por cualquier otra aplicación.

1.1.1 Componentes de Bridge Core

Bridge Core Server:

Es el servidor de reglas de negocio, el cual procesa los requerimientos recibidos, desde las aplicaciones externas, a través de un cliente (Web Service), ejecutando las operaciones y/o reglas de negocio correspondientes utilizando BridgeCore, y retornando el resultado de dicho procesamiento al cliente.

Este servidor establece y mantiene las sesiones con los clientes.

Bridge Core Server Rest

Es un servidor RESTful de reglas de negocio, el cual procesa los requerimientos recibidos desde una invocación HTTP, ejecuta las operaciones y/o reglas de negocio correspondientes utilizando BridgeCore, y retornando el resultado de dicho procesamiento al cliente.

Cliente:

Es una librería cuya misión es la de simplificar la interacción entre aplicaciones externas (como por ejemplo una aplicación de eCommerce, un POS tradicional, un Self-Checkout, un cliente Mobile, etc.) y el Servidor de Reglas. Para ello, provee de un mecanismo para poder interactuar con el servidor de reglas, realizando peticiones y obteniendo las respectivas respuestas de procesamiento de manera simplificada. Este cliente solo sirve para comunicarse con Bridge Core Server.

1. Recursos

Un concepto importante en REST es la existencia de recursos (elementos de información), que pueden ser accedidos utilizando un identificador global (un Identificador Uniforme de Recurso). Para manipular estos recursos, los componentes de la red (clientes y servidores) se comunican a través de una interfaz estándar (HTTP) e intercambian representaciones de estos recursos.

Los recursos que expone Bridge Core Server Rest son:

workflow: Este recurso retorna una representación del Workflow actual de Bridge Core.
terminal/{terminal}: Este recurso representa una terminal. Se utiliza cuando se desea establecer una conexión e iniciar una transacción con una terminal dada. Por ejemplo, si se desea conectar a la terminal 10, se accederá a terminal/10.
services: Retorna el conjunto de servicios disponibles e Bridge Core.
service/{serviceName}: Permite acceder a un servicio determinado sobre el cual se pueden invocar métodos. Por ejemplo, service/customerOrder.

2. Establecer conexión a una Terminal

Si lo que se desea es realizar una transacción en una terminal dada, lo primero que hay que hacer es un startup de dicha terminal. Esta acción es requerida para que Bridge Core asigne una sesión de terminal al cliente que intenta utilizar las reglas de negocio. Sin la petición de esta acción ningún cliente podrá utilizar las reglas de negocio del Workflow, ya que durante este proceso se asigna una terminal del sistema y un identificador de sesión de terminal.

Para hacer un startup a través de una request HTTP, se debe invocar la operación estándar POST de HTTP con la siguiente url:

~/terminal/{codigoTerminal}

Así, por ejemplo, si deseo conectarme a un server rest local, e iniciar la terminal 10, invoco:

http://localhost:8080/bcoreserver/

Bridge Core Server REST retorna los resultados en XML. Por eso, el header de la request HTTP debe tener los siguientes valores:

Content-Type:application/xml

Accept:application/xml

Dicha operación retorna un terminal representation, el cual en xml tiene la siguiente estructura:

<?xml version="1.0" encoding="UTF-8" ?>
<bridgeCoreResponse>
  <ack>0</ack>
  <message></message>
  <sessionId>56a31332-6732-47e3-b00b-c5ad00c9de6d</sessionId>
  <operationResult class="string">56a31332-6732-47e3-b00b-c5ad00c9de6d</operationResult>
  <representation class="terminalRepresentation">
    <terminalCode>10</terminalCode>
    <storeCode>2</storeCode>
    <status>OK</status>
  </representation>
</bridgeCoreResponse>

Toda response tiene los siguientes atributos:

sessionId: Es el Identificador de la conexión de la terminal. Este id se necesita para ejecutar el resto de las operaciones dentro de dicha sesión.

ack: Es el código de retorno de la operación. Si la operación no retorna ningún error, el valor de esta propiedad es 0. Caso contrario, el valor de ack es el código que identifica el error ocurrido.

message: Si durante la ejecución de la operación ha ocurrido un error, en esta propiedad viene el mensaje de dicho error.

operationResult: Es el valor retornado por la operación ejecutada. En este caso coincide con el identificador de conexión de la terminal.

representation: Dentro de esta propiedad viene la representación retornada por la operación, y difiere de acuerdo a la operación invocada. En este caso retorna un TerminalRepresentation con sus datos propios.

3. Invocar una operación

3.1 Login

Una vez establecida una conexión a una terminal, se puede empezar a invocar operaciones para loguearse con un usuario, iniciar una transacción, ejecutar operaciones dentro de dicha transacción, finalizar, etc.

La primera operación que se debe invocar es la de logueo, en la cual se inicia una sesión de usuario para esa terminal.

Para invocar dicha operación, se debe enviar una request HTTP PUT a la siguiente url.

~/terminal/{codigoTerminal}

Por ejemplo, si la conexión se ha establecido a la terminal 10, la url debe ser:

~/terminal/10

A su vez, el header de la request debe ser:

Content-Type:application/xml

Accept:application/xml

Y el entity a enviar en XML tiene la siguiente estructura

<bridgeCoreRequest>
  <connectionId>56a31332-6732-47e3-b00b-c5ad00c9de6d</connectionId>
  <operation>login</operation>
  <params>
    <userName>suser</userName>
    <userPassword>suser123</userPassword>
  </params>
</bridgeCoreRequest>

Donde:

connectionId: Es el id de la conexión. Dicho id fue retornado cuando se invocó la operación de startup de la terminal y debe ser usado cada vez que se invoque una operación dentro de la sesión de esa terminal.

operation: Es el nombre de la operación a invocar.

params: dentro de este tag van los parámetros de la operación. En este caso son dos parámetros:

userName: Es el nombre de usuario.

userPassword: Es la contraseña del usuario.

La respuesta de una operación es un xml con la a siguiente estructura:

<?xml version="1.0" encoding="UTF-8" ?>
<bridgeCoreResponse>
  <ack>0</ack>
  <message></message>
  <sessionId>56a31332-6732-47e3-b00b-c5ad00c9de6d</sessionId>
  <representation class="terminalRepresentation">
    <terminalCode>10</terminalCode>
    <storeCode>$(storeId)</storeCode>
    <status>OK</status>
    <sessionData>
      <menu>
        <options>
          <optionMenu>
            <id>1</id>
            <optionNumber>1</optionNumber>
            <optionName>Venta</optionName>
          </optionMenu>
          …
        </options>
      </menu>
      <trainingMode>false</trainingMode>
      <promoOptions/>
      <promoSuggestions/>
    </sessionData>
  </representation>
</bridgeCoreResponse>

En este caso, como se puede ver, también se retornan valores para las propiedades ack, message y sessionId.

Dentro de representation retorna un terminalRepresentation y dentro de menú se encuentran las transacciones que se pueden iniciar.

3.2 Select Transaction

Esta operación permite seleccionar la transacción a inicializar a partir de su id, el cual fue retornado en las opciones de menú de la operación de Login:

<sessionData>
      <menu>
        <options>
          <optionMenu>
            <id>1</id>
            <optionNumber>1</optionNumber>
            <optionName>Venta</optionName>
          </optionMenu>
          …

Para invocar dicha operación, se debe ejecutar una request HTTP PUT igual a la de Login, pero con el siguiente Entity:

<bridgeCoreRequest>
  <connectionId>56a31332-6732-47e3-b00b-c5ad00c9de6d</connectionId>
  <operation>selectTransaction</operation>
  <params>
    <transactionSubtype>1</transactionSubtype>
  </params>
</bridgeCoreRequest>

Dónde:

operation: Es el nombre de la operación a ejecutar, en este caso: selectTransaction

params: transactionSubtype es el id de la transacción seleccionada. En este la transacción con id 1 representa una transacción de venta.

Y la respuesta de dicha operacion es la siguiente:

<?xml version="1.0" encoding="UTF-8" ?>
<bridgeCoreResponse>
  <ack>0</ack>
  <message></message>
  <sessionId>db0af19d-6574-4c01-ae38-746eb7511ae6</sessionId>
  <representation class="terminalRepresentation">
    <terminalCode>10</terminalCode>
    <storeCode>$(storeId)</storeCode>
    <status>OK</status>
    <sessionData>
      <ticket>
        <userName>suser</userName>
        <terminalCode>10</terminalCode>
        <storeCode>$(storeId)</storeCode>
        <subtotal>
          <number>0</number>
        </subtotal>
        <total reference="../subtotal"/>
        <totalBalance reference="../subtotal"/>
        <items/>
        <payments/>
        <paymentsTotal reference="../subtotal"/>
        <change reference="../subtotal"/>
        <paid>false</paid>
        <discounts/>
        <discountsItemsTotal reference="../subtotal"/>
        <discountsTransactionTotal reference="../subtotal"/>
        <discountsPromoTotal reference="../subtotal"/>
        <totalLoyaltyBenefits>
          <number>0.00</number>
        </totalLoyaltyBenefits>
        <promoPaymentPlans/>
        <promoGifts/>
      </ticket>
      <tendersMenu>
        <options>
          <optionMenu>
            <id>1</id>
            <optionNumber>1</optionNumber>
            <optionName>Contado</optionName>
          </optionMenu>
          <optionMenu>
            <id>2</id>
            <optionNumber>2</optionNumber>
            <optionName>DÃ³lares</optionName>
          </optionMenu>
          …
        </options>
      </tendersMenu>
      <trainingMode>false</trainingMode>
      <promoOptions/>
      <promoSuggestions/>
    </sessionData>
    <cashDrawerOpenAllowed>false</cashDrawerOpenAllowed>
  </representation>
</bridgeCoreResponse>

En este punto, se ha iniciado una transacción de venta, sobre la cual se pueden ejecutar operaciones de agregar items, pagos, anular items, anular pagos, finalizar trx. Etc.

Dichas operaciones, y sus parámetros está explicado en el documento DEFINIR DOCUMENTO. A su vez, el el Apendice A de este documento se encuentras ejemplos de requests y responses de cada una de las operaciones que se pueden invocar.

4. Invocar un Servicio

En BridgeCore es posible invocar ciertos servicios Remotos sin necesidad de establecer una conexión a una terminal. Los servicios están agrupados en interfaces, sobre el cual se pueden ejecutar distintas llamadas.

Así, por ejemplo, si se quieren ejecutar operaciones de orden de compra, las cuales no están asociadas a una terminal, se debe invocar enviando una HTTP PUT request a la siguiente url:

~/service/customerOrder

Con el siguiente Entity

<bridgeCoreRequest>
  <connectionId>3bc87f6a-98aa-4cba-985c-e58a70cf1d50</connectionId>
  <operation>create</operation>
  <params>
    <terminal>10</terminal>
  </params>
</bridgeCoreRequest>

5. 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:

<?xml version="1.0" encoding="UTF-8" ?>
<bridgeCoreResponse>
  <ack>10061</ack>
  <message>La conexión con la terminal 10 ha expirado.</message>
  <sessionId>56a31332-6732-47e3-b00b-c5ad00c9de6d</sessionId>
</bridgeCoreResponse>

6. Obtener el workflow

Para obtener una representación en XML del workflow completo de la instancia de BridgeCore, se debe ejecutar un HTTP GET request a la siguiente URL:

~/workflow

Al acceder a dicho resource, devuelve el siguiente XML:

<?xml version="1.0" encoding="UTF-8" ?>
<bridgeCoreResponse>
  <ack>0</ack>
  <message></message>
  <operationResult class="bCWorkflow">
    <name>POS Workflow</name>
    <activitiesConfig>
      <bCActivityConfig>
        <interfaze>
          <name>com.synthesis.bridge.bcore.business.activities.IdleActivity</name>
          <packaje>com.synthesis.bridge.bcore.business.activities</packaje>
          <methods>
            <bCMethod>
              <name>startup</name>
              <parameterTypes>
                <string>java.lang.String</string>
              </parameterTypes>
              <declaringClass>com.synthesis.bridge.bcore.business.activities.IdleActivity</declaringClass>
              <returnType>java.lang.String</returnType>
            </bCMethod>
          </methods>
        </interfaze>
        <implClass>
          <name>com.synthesis.bridge.bcore.business.activities.impl.IdleActivityImpl</name>
          <packaje>com.synthesis.bridge.bcore.business.activities.impl</packaje>
          <methods>
            <bCMethod>
              <name>startup</name>
              <parameterTypes>
                <string>java.lang.String</string>
              </parameterTypes>
              <declaringClass>com.synthesis.bridge.bcore.business.activities.impl.IdleActivityImpl</declaringClass>
              <returnType>java.lang.String</returnType>
            </bCMethod>
…

7. Obtener los servicios disponibles

Para obtener una representación en XML de los services disponibles de Bridge Core, se debe ejecutar un HTTP GET request a la siguiente URL:

~/services

Al acceder a dicho resource, devuelve el siguiente XML:

<?xml version="1.0" encoding="UTF-8" ?>
<bridgeCoreResponse>
  <ack>0</ack>
  <message></message>
  <operationResult class="bCServices">
    <services>
      <bCServiceConfig>
        <interfaze>
          <name>com.synthesis.bridge.bcore.business.services.CustomerOrderService</name>
          <packaje>com.synthesis.bridge.bcore.business.services</packaje>
          <methods>
            <bCMethod>
              <name>create</name>
              <parameterTypes>
                <string>java.lang.String</string>
              </parameterTypes>
              <declaringClass>com.synthesis.bridge.bcore.business.services.CustomerOrderService</declaringClass>
              <returnType>java.lang.Object</returnType>
            </bCMethod>
          </methods>
        …
    </services>
  </operationResult>
</bridgeCoreResponse>

8. Apendice A

En el siguiente apartado se muestran distintos ejemplos de Request y Responses de BridgeCore REST Server. Primero se expondrán todas Las BridgeCore Request, y luego se mostrarán las Representations asociadas a cada BridgeCoreResponse.

8.1 Activity: IdleActivity

8.1.1 Operation: startup

Tipo de operación: POST

Request

<operation>login</operation>

<userName>suser</userName>

<userPassword>suser123</userPassword>

</params>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.2 Activity: LoginActivity

8.2.1 Operation: findCustomers

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>findCustomers</operation>

<personLastName>Perez</personLastName>

</params>

</bridgeCoreRequest>

Response: FindCustomersRepresentation

8.2.2 Operation: findItems

Tipo de operación: GET

Request

<operation>findItems</operation>

</params>
</bridgeCoreRequest>

Response: FindItemsRepresentation

Tipo de operación: PUT

Request

<operation>login</operation>

<userName>suser</userName>

<userPassword>suser123</userPassword>

</params>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.3 Activity: SelectTransaction

8.3.1 Operation: cashDrawerOpen

Tipo de operación: PUT

Request

<operation>cashDrawerOpen</operation>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.3.2 Operation: logoff

Tipo de operación: PUT

Request

<operation>logoff</operation>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.3.3 Operation: receivedPaymentReport

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>receivedPaymentsReport</operation>

</bridgeCoreRequest>

Response: ReceivedPaymentsReportRepresentation

8.3.4 Operation: resumeTransaction

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>resumeTransaction</operation>

</params>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.3.5 Operation: selectTransaction

Tipo de operación: PUT (seleccionar)

Request

<operation>selectTransaction</operation>

</params>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.3.6 Operation: specialLogoff

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>specialLogoff</operation>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.4 Activity: SellingActivity

8.4.1 Operation: addCardPayment

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request 1: Ingreso por teclado

<operation>addCardPayment</operation>

<voidFlag>false</voidFlag>

</params>

</bridgeCoreRequest>

Request 2: Ingreso por MSR

<operation>addCardPayment</operation>

<voidFlag>false</voidFlag>

<value>jklue4567</value>

</cardTracks>

</params>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.4.2 Operation: addCashPayment

Tipo de operación: PUT

Request 1: Medio de pago Efectivo

<connectionId>99adfdd7-9ad5-4ec2-a1cb-2028b944aa04</connectionId>

<operation>addCashPayment</operation>

<voidFlag>false</voidFlag>

</params>

</bridgeCoreRequest>

Request 2: Medio de pago Dólar

<connectionId>99adfdd7-9ad5-4ec2-a1cb-2028b944aa04</connectionId>

<operation>addCashPayment</operation>

</params>

</bridgeCoreRequest>

Request 3: Medio de pago Euro

<connectionId>99adfdd7-9ad5-4ec2-a1cb-2028b944aa04</connectionId>

<operation>addCashPayment</operation>

<voidFlag>false</voidFlag>

</params>

</bridgeCoreRequest>

Request 4: Medio de pago Cheque

<connectionId>99adfdd7-9ad5-4ec2-a1cb-2028b944aa04</connectionId>

<operation>addCashPayment</operation>

<voidFlag>false</voidFlag>

</params>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.4.3 Operation: addCheckPayment

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>addCheckPayment</operation>

<voidFlag>false</voidFlag>

</params>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.4.4 Operation: addItem

Tipo de operación: PUT

Request 1: Agregado de ítem por cantidad

<operation>addItem</operation>

</params>

</bridgeCoreRequest>

Request 2: Agregado de ítem por magnitud

<operation>addItem</operation>

<processPromotions>false</processPromotions>

</params>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.4.5 Operation: addItemList

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>addItemList</operation>

</value>

</value>

</itemDataList>

</params>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.4.6 Operation: applyDiscountToItem

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request 1: Monto de descuento

<connectionId>e92744ec-2e00-45f8-b03f-dd5dffac9e56</connectionId>

<operation>applyDiscountToItem</operation>

</params>

</bridgeCoreRequest>

Request 2: Porcentaje de descuento

<connectionId>e92744ec-2e00-45f8-b03f-dd5dffac9e56</connectionId>

<operation>applyDiscountToItem</operation>

<processPromotions>false</processPromotions>

</params>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.4.7 Operation: applyDiscountToTransaction

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request 1: Monto de descuento

<operation>applyDiscountToTransaction</operation>

</params>

</bridgeCoreRequest>

Request 2: Porcentaje de descuento

<operation>applyDiscountToTransaction</operation>

</params>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.4.8 Operation: cancelTransaction

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>cancelTransaction</operation>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.4.9 Operation: cashDrawerOpen

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>cashDrawerOpen</operation>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.4.10 Operation: findCustomers

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>findCustomers</operation>

<personLastName>Junin</personLastName>

<personFirstName>Liliana</personFirstName>

</params>

</bridgeCoreRequest>

Response: FindItemsRepresentation

8.4.11 Operation: findItems

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>findItems</operation>

</params>
</bridgeCoreRequest>

Response: FindItemsRepresentation

8.4.12 Operation: finishTransaction

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>finishTransaction</operation>

</bridgeCoreRequest>

Response: xxRepresentation

8.4.13 Operation: linkCustomerWithLoyaltyData

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>linkCustomerWithLoyaltyData</operation>

</params>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.4.14 Operation: linkCustomerWithTaxData

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request 1

Request 2

Response: TerminalRepresentation

8.4.15 Operation: specialLogoff

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>specialLogoff</operation>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.4.16 Operation: suspendTransaction

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>suspendTransaction</operation>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.4.17 Operation: totalizeTransaction

Tipo de operación: PUT

Request

Response: xxRepresentation

8.4.18 Operation: voidItem

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>voidItem</operation>

</params>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.4.19 Operation: voidItemDiscount

Tipo de operación: PUT

Request

<operation>voidItemDiscount</operation>

</params>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.4.20 Operation: voidTransactionDiscount

Tipo de operación: PUT

Request

<operation>voidTransactionDiscount</operation>

</params>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.5 Activity: SpecialLogin

Tipo de operación: PUT

Request

<operation>login</operation>

<userPassword>suser123</userPassword>

</params>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.5.2 Operation: unblockTerminal

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>unblockTerminal</operation>

<userName>suser</userName>

<userPassword>suser123</userPassword>

</params>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.6 Activity: TransferringTerminal

8.6.1 Operation: cancelTransaction

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>cancelTransaction</operation>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.6.2 Operation: specialLogoff

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>specialLogoff</operation>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.6.3 Operation: transferTerminal

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>transferTerminal</operation>

<userPassword>false</userPassword>

</params>

</bridgeCoreRequest>

Response: xxRepresentation

8.7 Activity: Controlling

8.7.1 Operation: addTender

Tipo de operación: PUT

Request

<operation>addTender</operation>

<voidFlag>false</voidFlag>

</params>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.7.2 Operation: cancelTransaction

Tipo de operación: PUT

Request

<operation>cancelTransaction</operation>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.7.3 Operation: finishTransaction

Tipo de operación: PUT

Request

<operation>finishTransaction</operation>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.7.4 Operation: specialLogoff

Tipo de operación: PUT

Request

<operation>specialLogoff</operation>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.8 Activity: TenderAdjustment

8.8.1 Operation: cancelTransaction

Tipo de operación: PUT

Request

<operation>cancelTransaction</operation>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.8.2 Operation: finishTransaction

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>finishTransaction</operation>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.8.3 Operation: specialLogoff

Tipo de operación: GET/POST/PUT/DELETE (seleccionar)

Request

<operation>specialLogoff</operation>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.8.4 Operation: tenderAdjustment

Tipo de operación: PUT

Request 1: Efectivo

<operation>tenderAdjustment</operation>

<newVoidFlag>false</newVoidFlag>

<originalVoidFlag>false</originalVoidFlag>

</params>

</bridgeCoreRequest>

Request 2: Cheque

<operation>tenderAdjustment</operation>

<newVoidFlag>false</newVoidFlag>

</params>

</bridgeCoreRequest>

<operation>tenderAdjustment</operation>

<newVoidFlag>false</newVoidFlag>

<originalPaymentAmount>false</originalPaymentAmount>

</params>

</bridgeCoreRequest>

Request 3: Tarjeta

<operation>tenderAdjustment</operation>

<newVoidFlag>false</newVoidFlag>

<originalPaymentAmount>false</originalPaymentAmount>

</params>

</bridgeCoreRequest>

Response: TerminalRepresentation

8.9 Service: CustomerOrderService

8.9.1 Operation: create/calculate

Tipo de operación: PUT

El servicio de creación sirve para crear y persistir una orden de compra, o bien para calcular como sería una orden con la diferencia de que no se crea en la base de datos. A continuación se mostrarán distintos ejemplos de creación y cálculo.

Partes de la Request

Declaración de Request: todos los datos deben estar encerrados entre los siguientes tags.

</bridgeCoreRequest>

Nombre de la operación: sin importar cuál de las dos operaciones sea, siempre debe ser asignado de la siguiente manera.

<operation>create</operation>

Parámetros: deben estar encerrados entre los siguientes tags.

<params>

</ params >

A continuación se detallan los siguientes parámetros de ingreso, los cuales deben ir dentro del tag mencionado arriba.

Datos generales de la orden: identificación de cliente, fecha estimada de entrega

Nombre de usuario y contraseña: deben pertenecer a un usuario válido existente en la base de datos.

Indicador de creación o cálculo: true en caso de creación, y false en caso de cálculo. Si este parámetro no se ingresa, el valor a tomar por defecto es false.

Crear orden

<customerOrderCalculate>false</customerOrderCalculate>

Calcular orden

Indicador de procesado de promociones: se debe enviar true en caso de que se solicite calcular promociones y descuentos, y false caso contrario.

Datos de ítems: no es posible enviar una lista vacía, se debe ingresar al menos uno. Dependiendo de las características del ítem, los atributos itemPrice e itemQty no serán necesarios. Pero en todos los casos itemBarcode será obligatorio.

Un solo ítem:

</value>

</customerOrderItems>

Más de un ítem:

</value>

</value>

</value>

</value>

</customerOrderItems>

Tipo de entrega: es excluyente y sólo existen dos tipos de entrega.

Retiro en tienda: se corresponde con el tipo “Order for Pickup”

Entrega a domicilio: se corresponde con el tipo “Order for Delivery”

Datos de entrega: si bien el método de entrega es excluyente, se puede enviar información de ambos tipos. Pero luego BCore tomará la información del que se necesite según el tipo enviado, y los datos que no necesite los ignorará.

Retiro en tienda

<customerOrderContactPerson>Alfredo Perez</customerOrderContactPerson>

Entrega a domicilio

<customerOrderAddress>25 de Mayo 1100</customerOrderAddress>
<customerOrderContactPerson>Juan Perez</customerOrderContactPerson>
<customerOrderDeliveryShift>8:00-10:00</customerOrderDeliveryShift>
<customerOrderAdditionalDeliveryData>Entre Pedro Molina y Colon</customerOrderAdditionalDeliveryData>

A continuación se mostrarán varios ejemplos de solicitudes.

Request 1: Ejemplo de creación/cálculo para orden con retiro en tienda, enviando varios artículos y sin cálculo de promociones.

Creación de orden

<operation>create</operation>

</value>

</value>

</value>

</value>

</customerOrderItems>

<customerOrderCalculate>false</customerOrderCalculate>

<processPromotions>false</processPromotions>

<customerOrderContactPerson>Alfredo Perez</customerOrderContactPerson>

</params>

</bridgeCoreRequest>

Cálculo de orden

<operation>create</operation>

<customerOrderContactPerson>Alfredo Perez</customerOrderContactPerson>

<customerOrderAdditionalDeliveryData>Entre Pedro Molina y Colon</customerOrderAdditionalDeliveryData>

</value>

</value>

</value>

</value>

</customerOrderItems>

<processPromotions>false</processPromotions>

</params>

</bridgeCoreRequest>

Request 2: Orden para delivery

En el atributo customerOrderTypeCode se define el tipo de retiro mediante el código ofd (Order For Delivery). Es necesario definir también la dirección y persona de contacto.

Response: CustomerOrderRepresentation

<operation>create</operation>

<customerOrderCalculate>false</customerOrderCalculate>

<customerOrderContactPerson>Alfredo Perez</customerOrderContactPerson>

<customerOrderAdditionalDeliveryData>Entre Pedro Molina y Colon</customerOrderAdditionalDeliveryData>

</value>

</value>

</value>

</value>

</customerOrderItems>

<processPromotions>false</processPromotions>

</params>

</bridgeCoreRequest>

Request 3: Calcular Orden

Para calcular orden, lo único que se debe hacer es invocar a la operación create con el atribute processPromotions en true.

Response: CustomerOrderRepresentation

<operation>create</operation>

<customerOrderCalculate>false</customerOrderCalculate>

<customerOrderContactPerson>Alfredo Perez</customerOrderContactPerson>

<customerOrderAdditionalDeliveryData>Entre Pedro Molina y Colon</customerOrderAdditionalDeliveryData>

</value>

</value>

</value>

</value>

</customerOrderItems>

</params>

Responses de error

Las respuestas de error son devueltas por diferentes motivos tales como:

Ingreso de al menos un artículo con precio, código o cantidad inválida
Datos faltantes y/o inválidos de entrega
Errores de acceso a la base de datos, etc.

A continuación se mostrarán varios ejemplos de respuestas de error.

Error response 1: ingreso de datos inválidos de artículos.

Request

<operation>create</operation>

<customerOrderCalculate>false</customerOrderCalculate>

<customerOrderContactPerson>Alfredo Perez</customerOrderContactPerson>

<customerOrderAdditionalDeliveryData>Entre Pedro Molina y Colon</customerOrderAdditionalDeliveryData>

</value>

</value>

</value>

</value>

</customerOrderItems>

<processPromotions>false</processPromotions>

</params>

</bridgeCoreRequest>

Response

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

<message>Los siguientes items de la orden de compra son inválidos: 75001|Precio inválido.;89001|El artículo no admite cantidad.</message>

</bridgeCoreResponse>

La interpretación del error se debe hacer de la siguiente manera:

-Partir el mensaje en dos tomando ‘:’ como carácter splitter. La primera parte es un mensaje informativo de error y la segunda es el detalle del error.

8.9.1 Operation: update

Request 1: Actualizar Orden

Para actualizar orden, se le debe pasar la última versión de la orden de compra.

Response: CustomerOrderRepresentation

<operation>update</operation>

<customerOrderContactPerson>Alfredo Perez</customerOrderContactPerson>

<customerOrderAdditionalDeliveryData>Entre Pedro Molina y Colon</customerOrderAdditionalDeliveryData>

</value>

</value>

</value>

</value>

</customerOrderItems>

<processPromotions>false</processPromotions>

</params>

</bridgeCoreRequest>

8.9.2 Operation: find

Tipo de operación: PUT

La operación de búsqueda recupera una o más órdenes de compra guardadas en el sistema. Los parámetros que se envían en la operación son:

customerOrderFindNumber: número de orden de compra. Si este parámetro se envía, al ser unívoco, el resultado será una orden de compra que contendrá datos detallados de la orden. Si no se envía, entonces contendrá datos generales de todas las órdenes encontradas.

retirementStoreCode: código de retiro de la tienda.

lowerDateRange: fecha de inicio del intervalo de búsqueda.

upperDateRange: fecha de fin del intervalo de búsqueda.

Nota: si se define intervalo de fechas, lowerDateRange y upperDateRange se deben tener valores concretos.

partyIdentificationNumber: número de identificación del cliente.

customerOrderState: código del estado de la orden de compra. (Mencionar todos los códigos).

customerOrderShipmentMethod: código de tipo de entrega de la orden. Los posibles códigos son: ofd (Order For Delivery, que es la entrega a domicilio), ofp (Order For Pickup, que es retiro en tienda).

resultPage: indica el número de página a mostrar en caso de haber resultados. Valor por defecto: 0 (cero).

rowsPage: indica la cantidad de registros por página en caso de haber resultados. Valor por defecto: 15.

Nota: todos los parámetros son opcionales. En caso de que se envíe una Request de este estilo, se devolverán todas las órdenes de compra del sistema (si existiera al menos una guardada).

Request 1: Se envían todos los parámetros de búsqueda.

</params>

</bridgeCoreRequest>

Response: FindCustomerOrdersRepresentation

Request 2: No se envían parámetros de búsqueda.

</bridgeCoreRequest>

Response: FindCustomerOrdersRepresentation

8.9.3 Operation: invoice

Tipo de operación: PUT

La operación de facturación toma una orden de compra en estado “To Invoice” (“A negociar”) y la factura.

Parámetros:

customerOrderNumber: número de orden de compra.
customerOrderVersionNumber: número de versión de la orden de compra. Si se envía, debe ser el último registrado en el historial de versiones.
itemDataList: lista de ítems de la orden, la cual en caso de enviarse, debe controlarse que sean exactamente los mismos datos tanto de precios, cantidades, y descuentos que los de la última.
customerOrderTotalAmount: el monto total de la orden de compra.
couponDataList: lista de cupones. Nota: no se encuentra implementado.
paymentDataList: lista de pagos.
transactionId: ID de transacción de venta.
documentNumber: número de documento/factura.
receiptDate: fecha de documento/factura.
receiptAmount: monto del documento/factura.
username: nombre de usuario.
userPassword: contraseña.
Nota: todos los atributos remarcados en verde son listas que pueden contener uno o más elementos.

Request 1: Se envían todos los parámetros de facturación.

<operation>invoice</operation>

</value>

</value>

</paymentDataList>

<priceModifierReasonCode>Descuento Navidad</priceModifierReasonCode>

</value>

</customerOrderPriceItemModifierList>

</value>

<priceModifierReasonCode>Descuento Navidad</priceModifierReasonCode>

</value>

</customerOrderPriceItemModifierList>

</value>

</itemDataList>

</params>

</bridgeCoreRequest>

Request 2: Se envían únicamente ítems para comparar, algunos contienen descuentos y otros no. No se envían datos de facturación ni pagos.

<operation>invoice</operation>

</value>

<priceModifierReasonCode>Descuento Navidad</priceModifierReasonCode>

</value>

</customerOrderPriceItemModifierList>

</value>

</itemDataList>

</params>

</bridgeCoreRequest>

Request 3: no se envían datos de ítems. Por lo tanto, no se debe realizar control de ítems. Se envían solamente pagos y datos de facturación.

<operation>invoice</operation>

</value>

</value>

</paymentDataList>

</params>

</bridgeCoreRequest>

Request 4: no se envían datos ni de ítems, ni de pagos, ni de facturación. Tampoco de la versión de la orden (automáticamente se factura la última versión). Lo que debería ocurrir es que se facture la orden de compra y se autocompleten los pagos con en Medio de Pago de Balance, y que el monto sea por el total de la orden de compra.

<operation>invoice</operation>

</params>

</bridgeCoreRequest>

Response: CustomerOrderRepresentation

8.9.4 Operation: charge

Tipo de operación: PUT

La operación de cobro toma una orden de compra en estado “To Deliver” (“A entregar”) y la cobra.

Parámetros:

customerOrderNumber: número de orden de compra.
customerOrderVersionNumber: número de versión de la orden de compra. Si se envía, debe ser el último registrado en el historial de versiones.
paymentDataList: lista de pagos.
transactionId: ID de transacción de venta.
documentNumber: número de documento/factura.
receiptDate: fecha de documento/factura.
receiptAmount: monto del documento/factura.
username: nombre de usuario.
userPassword: contraseña.

Nota: todos los atributos remarcados en verde son listas que pueden contener uno o más elementos.

Request 1: Se envían todos los parámetros de cobro.

<operation>charge</operation>

</value>

</paymentDataList>

</params>

</bridgeCoreRequest>

Request 2: No se envían datos de facturación, ni el último número de versión de la orden de compra.

<operation>charge</operation>

</value>

</paymentDataList>

</params>

</bridgeCoreRequest>

Nota: si el monto de los pagos netos no fuera suficiente para saldar el total de la orden, la orden continuará en el mismo estado “A enviar” hasta que se cumpla dicha condición.

Response: CustomerOrderRepresentation

8.10 Representations

8.10.1 TerminalRepresentation

Paquete: bridge-representations

Response

8.10.2 FindCustomersRepresentation

Paquete: bridge-representations

Response

<type>Documento de identidad</type>

</partyIdentificationData>

<type>Pasaporte</type>

</partyIdentificationData>

</identifications>

<roles>

<name>Empleado</name>

<description>Realiza tareas de mantenimiento de hardware</description>

</partyRoleData>

</roles>

<partyType>Pérez, Juan</partyType>

<firstLine>Olascoaga 12</firstLine>

<secondLine>Piso 1 Depto 25</secondLine>

<city>MENDOZA</city>

<state>MENDOZA</state>

</address>

<email>

<email>juanperez@yahoo.com.ar</email>

</email>

</telephone>

<taxes>

<registrationName>Impuesto</registrationName>

<taxType>Impuesto Interno</taxType>

</taxRegistrationData>

</taxes>

<type>LOYALTY</type>

<name>Primer cuenta de Lealtad</name>

<customerIdentityType>Tipo de Identidad</customerIdentityType>

<loyaltyProgram>Primer programa de Lealtad</loyaltyProgram>

</loyaltyCumulativeNetSalesAmount>

<cards>

</customerAccountCardData>

</cards>

</customerAccountData>

</accounts>

</customerData>

</customersData>

</representation>

</bridgeCoreResponse>

8.10.3 FindItemsRepresentation

Paquete: bridge-representations

Response

8.10.4 AdditionalDataRepresentation

Paquete: bridge-representations

Response

8.10.5 AuthorizationsRepresentation

Paquete: bridge-representations

Response

8.10.6 ReceivedPaymentsReportRepresentation

Paquete: bridge-representations

Response

8.10.7 VtolToScreenRepresentation

Paquete: bridge-business-components

Response

8.10.8 SessionRepresentationTest

Paquete: bridge-core

Response

8.10.9 CustomerOrderRepresentation

Paquete: bridge-core

Response

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

<itemDescription>Epson C92 printer</itemDescription>

</quantityOrdered>

</itemPrice>

</itemExtendedPrice>

<surcharge>false</surcharge>

</discountTotal>

</discountAmntTotal>

</discountPerTotal>

</discountPromoTotal>

</netValue>

</priceWithoutVAT>

</priceIvaAmount>

</totalInternalTaxes>

</taxableAmount>

</amount>

</taxablePercentage>

</MagnitudTax>

</taxDetail>

<isReturned>false</isReturned>

<isVoid>false</isVoid>

</customerOrderLineItemRepresentation>

<itemDescription>Wii Console</itemDescription>

</quantityOrdered>

</itemPrice>

</itemExtendedPrice>

<surcharge>false</surcharge>

</discountTotal>

</discountAmntTotal>

</discountPerTotal>

</discountPromoTotal>

</netValue>

</priceWithoutVAT>

</priceIvaAmount>

</totalInternalTaxes>

</taxableAmount>

</amount>

</taxablePercentage>

</taxDetail>

<isReturned>false</isReturned>

<isVoid>false</isVoid>

</customerOrderLineItemRepresentation>

<itemDescription>GH Aerosmith for PS3</itemDescription>

</itemPrice>

</itemExtendedPrice>

<surcharge>false</surcharge>

</discountTotal>

</discountAmntTotal>

</discountPerTotal>

</discountPromoTotal>

</netValue>

</priceWithoutVAT>

</priceIvaAmount>

</totalInternalTaxes>

</taxableAmount>

</amount>

</taxDetail>

<isReturned>false</isReturned>

<isVoid>false</isVoid>

</customerOrderLineItemRepresentation>

</itemPrice>

</itemExtendedPrice>

<surcharge>false</surcharge>

</discountTotal>

</discountAmntTotal>

</discountPerTotal>

</discountPromoTotal>

</netValue>

</priceWithoutVAT>

</priceIvaAmount>

</totalInternalTaxes>

</taxableAmount>

</amount>

</taxDetail>

<isReturned>false</isReturned>

<isVoid>false</isVoid>

</customerOrderLineItemRepresentation>

</customerOrderControlTransactionLineItems>

<contactPerson>Alfredo Perez</contactPerson>

</discountsItemsTotal>

</subtotal>

</discountableSubtotal>

<total>

</total>

</ivaPerception>

</iBPerception>

</promoDiscountTotal>

</discountsTransactionTotal>

</miscelaneos>

</positiveGross>

</negativeGross>

</ivaTotal>

</internalTaxesTotal>

</totalLoyaltyBenefits>

</operationResult>

</bridgeCoreResponse>

8.10.10 FindCustomerOrdersRepresentation

Paquete: bridge-core

Response: respuesta detallada

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

<customerFullname>Juan Pérez</customerFullname>

<name>Order for Delivery</name>

</typeData>

<name>Ready for picking</name>

</stateData>

<contactPerson>Alfredo Perez</contactPerson>

<additionalDeliveryInformation>Entre Pedro Molina y Colon</additionalDeliveryInformation>

</shipmentPrice>

</deliveryData>

<description>Epson C92 printer</description>

</orderedQuantity>

</unitPrice>

</extendedPrice>

</customerOrderItemData>

<description>Wii Console</description>

</orderedQuantity>

</unitPrice>

</extendedPrice>

</customerOrderItemData>

<description>GH Aerosmith for PS3</description>

</orderedQuantity>

</unitPrice>

</extendedPrice>

</customerOrderItemData>

</orderedQuantity>

</unitPrice>

</extendedPrice>

</customerOrderItemData>

</itemDataList>

</customerOrderData>

</customerOrdersData>

</operationResult>

</bridgeCoreResponse>

Response: respuesta resumida

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

<customerFullname>Juan Pérez</customerFullname>

</totalAmount>

<name>Order for Delivery</name>

</typeData>

<name>Ready for picking</name>

</stateData>

</customerOrderData>

</customerOrdersData>

</operationResult>

</bridgeCoreResponse>

OrderRepresentation

Paquete: bridge-sample-mcking

Response

Árvore de páginas

Integrando Bridge Core desde terminales externas - BRIDGE 7

Integrando Bridge Core desde terminales externas - BRIDGE 7

1. Introducción

1.1 ¿Qué es Bridge Core?

1.1.1 Componentes de Bridge Core

1. Recursos

2. Establecer conexión a una Terminal

3. Invocar una operación

3.1 Login

3.2 Select Transaction

Esta operación permite seleccionar la transacción a inicializar a partir de su id, el cual fue retornado en las opciones de menú de la operación de Login:

4. Invocar un Servicio

5. Manejo de errores

6. Obtener el workflow

7. Obtener los servicios disponibles

8. Apendice A

8.1 Activity: IdleActivity

8.1.1 Operation: startup

8.2 Activity: LoginActivity

8.2.1 Operation: findCustomers

8.2.2 Operation: findItems

8.2.3 Operation: login

8.3 Activity: SelectTransaction

8.3.1 Operation: cashDrawerOpen

8.3.2 Operation: logoff

8.3.3 Operation: receivedPaymentReport

8.3.4 Operation: resumeTransaction

8.3.5 Operation: selectTransaction

8.3.6 Operation: specialLogoff

8.4 Activity: SellingActivity

8.4.1 Operation: addCardPayment

8.4.2 Operation: addCashPayment

8.4.3 Operation: addCheckPayment

8.4.4 Operation: addItem

8.4.5 Operation: addItemList

8.4.6 Operation: applyDiscountToItem

8.4.7 Operation: applyDiscountToTransaction

8.4.8 Operation: cancelTransaction

8.4.9 Operation: cashDrawerOpen

8.4.10 Operation: findCustomers

8.4.11 Operation: findItems

8.4.12 Operation: finishTransaction

8.4.13 Operation: linkCustomerWithLoyaltyData

8.4.14 Operation: linkCustomerWithTaxData

8.4.15 Operation: specialLogoff

8.4.16 Operation: suspendTransaction

8.4.17 Operation: totalizeTransaction

8.4.18 Operation: voidItem

8.4.19 Operation: voidItemDiscount

8.4.20 Operation: voidTransactionDiscount

8.5 Activity: SpecialLogin

8.5.1 Operation: login

8.5.2 Operation: unblockTerminal

8.6 Activity: TransferringTerminal

8.6.1 Operation: cancelTransaction

8.6.2 Operation: specialLogoff

8.6.3 Operation: transferTerminal

8.7 Activity: Controlling

8.7.1 Operation: addTender

8.7.2 Operation: cancelTransaction

8.7.3 Operation: finishTransaction

8.7.4 Operation: specialLogoff

8.8 Activity: TenderAdjustment

8.8.1 Operation: cancelTransaction

8.8.2 Operation: finishTransaction

8.8.3 Operation: specialLogoff

8.8.4 Operation: tenderAdjustment

8.9 Service: CustomerOrderService

8.9.1 Operation: create/calculate

8.9.1 Operation: update

8.9.2 Operation: find

8.9.3 Operation: invoice

8.9.4 Operation: charge

8.10 Representations

8.10.1 TerminalRepresentation

8.10.2 FindCustomersRepresentation

8.10.3 FindItemsRepresentation

8.10.4 AdditionalDataRepresentation

8.10.5 AuthorizationsRepresentation