Manual de integración - Servicios
PROMO V7.0

Índice

Acerca del manual

Propósito y alcance

El presente manual tiene como finalidad la capacitación al usuario que desee integrar su aplicación de ventas con ellos servicios que expone Promo.
Se provee una descripción detallada de los mensajes que deben ser enviados al mismo y de cómo interpretar los mensajes de respuesta que dará ante un requerimiento.

Documentación de PROMO

PROMO provee la siguiente documentación:

Manual de usuario:

Este documento tiene la finalidad de capacitar al usuario que desee utilizar la consola de Administración de Promociones de PROMO.

Manual de instalación:

Este documento describe los procedimientos para instalar los componentes de Motor y Consola, la creación e inicialización de la Base de Datos y los requerimientos necesarios para el correcto funcionamiento de dichos componentes.

Manual de integración - Motor:

Este documento describe detalladamente los mensajes que deben ser enviados al Motor de Promociones y la forma de interpretar los mensajes de respuesta que el mismo dará ante un requerimiento.

Manual de integración - Servicios:

Este documento describe detalladamente los servicios que expone la consola de Promo y la forma de enviar y recibir información con ella.

Nota: Antes de continuar con la lectura del presente manual, se recomienda leer los capítulos 2 y 3 del Manual de usuario.

Herramientas utilizadas

En el desarrollo de este manual se utilizarán para los ejemplos basicamente tres herramientas que son de dominio público:

CURL (https://curl.haxx.se/) "command line tool and library for transferring data with URLs": Es una herramienta por linea de comandos para enviar/recibir mensajes http.
POSTMAN (https://www.postman.com) "The Collaboration Platform for API Development": Herramienta Grafica para la creación, envio y recepción de mensajes.
SOAPUI (https://www.soapui.org/) "Accelerating API Quality Through Testing": Otra herramienta Gráfica para la definición, envio y recepción de mensajes.

Seguridad: Atenticación de Sistemas Externos con los Servicios

Antes de consumir un servicio provisto por Promo, deberá realizarse un Proceso de autenticación OAuth2. El mismo consiste en obtener un TOKEN que luego debe ser enviado en los subsiguientes mensajes.

Entonces como primer paso a comenzar la comunicación con los servicios de Promo, el sistema externo debe realizar el proceso descripto aqui.

Primero deberá de solicitarse el Tocken de acceso, que utilizando CURL el comando sería:

Ejemplo

curl –v –X POST –u my-client: -d "grant_type=password" –d "username=sender" –d "password=mate" –d "scope=read" http://localhost:8080/promo/oauth/token

Donde "http://localhost:8080/promo/oauth/token" debe ser cambiado por la URL donde se encuentra la consola de Promo, de la misma forma que el usuario y password.

La respuesta ejemplo se puede ver en la siguiente ventana:

Una vez obtenido el token, se deberá enviar en las subsiguientes solicitudes. Por ejemplo realizamos un GET con la herramienta CURL:

Ejemplo

curl -X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8" -H "Content-type: application/json" -H "Accept: application/json" "http://localhost:8080/promo/api/rest/customer?code=1"

De la misma forma, el mismo request pero realizado en POSTMAN, sería:

Consola: Servicios REST de Consulta

Aqui se presentan los servicios provistos para consulta de infomormación contenida en PROMO.

Antes de consumir el servicio debe obtenerse el TOKEN de identificación como se explica en "Seguridad: Atenticación de Sistemas Externos con los Servicios"

Consulta de Datos de Clientes

PROMO expone un servicio que permite consultar tarjetas a la BBDD utilizando el ID de cliente. Junto con los campos del cliente, también se devuelve un listado de Tarjetas y Cupones, elementos de Fidelidad.
Si no tiene elementos de Fidelidad, se devolverán las Tarjetas o Cupones vacías
El código de la consulta debe ser exacto y solo se devolverá un resultado, si es que el cliente existe.
El formato en que se responde es en JSON.

La solicitud utilizando CURL será:

Ejemplo

curl -X GET -H "Authorization: Bearer
 8c014b30-a674-456e-bc18-29a072a7a1f8" -H "Content-type: 
application/json" -H "Accept: application/json" 
"http://localhost:8080/promo/api/rest/customer?code=1"

Obteniéndose la siguiente respuesta:

Ejemplo

{
"_id": "59a992cacaec3625e8447663",
"code": "1",
"creationDate": "2017-09-01T17:03:06Z",
"email": "gala @sts.com",
"identificationType": "DNI",
"identifier": "54333222",
"isActive": true,
"lastName": "Higgins",
"name": "GALA",
"version": 0,

"cards": [
{
"_id": "59a99439caec3625e84476f8",
"amount": 254,
"code": "2220000000001",
"created": "2017-09-01T17:09:13Z",
"isConsumed": false,
"status": "ENABLED",
"storeCode": "BLC",
"terminalCode": "2",
"transactionId": "BLC_201709011409677",
"type": "2",
"validFrom": "2017-09-01T03:00:00Z",
"validTo": "2018-09-01T03:00:00Z",
"version": 2,
"customerId": "1"
}
],

"coupons": []


}

En caso de que el cliente no exista en la base la respuesta se devolverá vacía.-

Servicio de Consulta de Cupón

PROMO expone un servicio que permite consultar cupones a la BBDD utilizando solo el número de cupón y como respuesta se obtienen los movimientos asociados a dicho cupón.

También se pueden realizar consultas sobre el historial de movimientos de cupones.

Los parámetros de entrada de la consulta son:

Propiedad	Tipo de dato	Descripción
*companyId*	Alfanumérico	Código de la compañia
*barcode*	Alfanumérico	Código de la tarjeta la cual se quiere consultar
*limit*	Numérico	Cantidad de registros de movimientos a retornar (default: 5) con un maximo de 100.000 por consulta.
*dateFrom*	Numérico	Fecha de Inicio en formato YYYYMMDD. Si no se especifica code.
*dateTo*	Numérico	Fecha de Final en formato YYYYMMDD. Si no se especifica code.
*couponAction*	Alfanumérico	Codigo de Operación que se quiere consultar. Si no se especifica code. Por defecto son todas las operaciones. Los valores disponibles son: CREATE, REDEEM, VOID

EJEMPLO 1: se solicitan los datos del cupon 1020000000007

La misma pero utilizando CURL:

Ejemplo

curl
 -X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8" 
-H "Content-type: application/json" -H "Accept: application/json" http://localhost:8080/promo/api/rest/coupon?barcode=1020000000007

Obteniéndose la siguiente respuesta:

Ejemplo

{
"_id": "59a993d6caec3625e84476e1",
"barcode": "1020000000007",
"consumed": false,
"couponFormat": "PRE_PRINTED",
"couponStatus": "ACTIVE",
"couponType": "2",
"issuedDate": "2017-09-01T17:07:34Z",
"maxUsageTimes": 1,
"storeCode": "BC",
"terminalCode": "2",
"transactionId": "BC_201709011407171",
"usedTimes": 0,
"validFrom": "2017-09-01T17:07:34Z",
"validTo": "2117-08-08T17:07:34Z",
"version": 0,

*"couponHistory": \[*


{
"couponAction": "CREATE",
"date": "2017-09-01T17:07:34Z",
"storeCode": "BC"
}
]
}

En caso de que el cliente no exista en la base la respuesta se devolverá vacía.-

EJEMPLO 2: Se solicitan todos los cupones creados en el periodo 01/06/2020-01/07/2020, para la empresa napse con un limite de 100.000 registros.

(curl -X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8" -H "Content-type: application/json" -H "Accept: application/json"http://localhost:8080/promo/api/rest/coupon?dateFrom=20200601&dateTo=20200701&companyId=napse&limit=100000&couponAction=CREATE')

La respuesta será del tipo:

Ejemplo

{
    "couponHistory": [
        {
            "transactionId": "napse_1_10_20200608105150",
            "date": "2020-06-05T18:11:00Z",
            "coupon": "1010010106479",
            "couponAction": "CREATE",
            "storeCode": "1",
            "terminalCode": "10"
        },
        {
            "transactionId": "napse_1_10_20200608105150",
            "date": "2020-06-05T18:11:00Z",
            "coupon": "1010010102945",
            "couponAction": "CREATE",
            "storeCode": "1",
            "terminalCode": "10"
        },
        {
            "transactionId": "napse_1_10_20200608105150",
            "date": "2020-06-05T18:11:00Z",
            "coupon": "1010010109418",
            "couponAction": "CREATE",
            "storeCode": "1",
            "terminalCode": "10"
        },
        {
            "transactionId": "napse_1_10_20200608105250",
            "date": "2020-06-05T18:21:30Z",
            "coupon": "1010010102891",
            "couponAction": "CREATE",
            "storeCode": "1",
            "terminalCode": "10"
        }
    ]
}

Servicio DE Consulta de Tarjetas

(Actualizado desde 6.5.2)

PROMO expone un servicio que permite consultar tarjetas a la BBDD utilizando solo su número de tarjeta y como respuesta se obtienen los datos de la tarjeta en cuestión y los movimientos asociados a dicha tarjeta. Los datos que se devuelven son: fecha, id de transaccion, tipo de operación, monto, tienda.

Para consumir este servicio se debe realizar una solicitud del tipo GET con los parametros correspondientes a la siguiente URL: http://servidor:puerto/promo/api/rest/card

Los parámetros de entrada de la consulta son:

Propiedad	Tipo de dato	Descripción
*companyId*	Alfanumérico	Código de la compañia
*code*	Alfanumérico	Código de la tarjeta la cual se quiere consultar
*limit*	Numérico	Cantidad de registros de movimientos a retornar (default: 5) con un maximo de 100.000 por consulta.
*dateFrom*	Numérico	Fecha de Inicio en formato YYYYMMDD
*dateTo*	Numérico	Fecha de Final en formato YYYYMMDD
*isTypes*	Booleano	(desde 7.EP2.1) Si se especifica el valor true se retornarán solamente los tipos de tarjetas definidos. *ver ejemplo mas abajo

Si se especifica una tarjeta, se retornaran los datos y movimientos asociados a dicha tarjeta, pudiendose opcionalmente especificar un rango de fechas y un limite en la cantidad de movimientos.

Si no se especifica tarjeta, se debe especificar un rango de fechas y se retornaran todos los movimientos de ls tarjetas en ese rango, incluyendo en ese caso el numero de tarjeta que se trata.

Para el caso de información de tarjetas, el Formato de la Respuesta será (JSON):

Propiedad	Tipo de dato	Descripción
_id*	Alfanumérico	Uso Interno
amount*	Numérico	Saldo Actual de la tarjeta.
code*	Alfanumérico	Número de Tarjeta
Created*	Alfanumérico	Fecha de Creacion en formato ISODATE
isConsumed*	Booleano	Si ha sido consumida o no
status*	Alfanumérico	Estado actual de la tarjeta
storeCode*	Alfanumérico	Codigo de Tienda de generacion (si aplica)
terminalCode*	Alfanumérico	Codigo de terminal de generacion (si aplica)
transactionId*	Alfanumérico	Codigo de Transacción que la genero (si aplica)
type*	Alfanumérico	Tipo de Tarjeta
version*	Numérico	Uso Interno
cardHistory	Colección	Conjunto de registros que corresponden a cada movimiento de la tarjeta, con: amount: monto del movimiento card (Solo si no se consulto por una dterminada): Numero de tarjeta cardAction: Tipo de movimiento date: fecha del movimiento (ISO DATE) storeCode: codigo de tienda transactionId: Codigo de transaccion.

Estos datos son retornados solo si se consulta por un codigo de tarjeta determinado.

Para el caso de Tipos de tarjeta:

Propiedad	Tipo de dato	Descripción
amountChargeLimit	Numérico	Limite de carga
*cardNumberLength*	Numérico	Longitud del número de tarjeta
cardTypePrefixRange	Array	definicion de rangos de prefijos para esa tarjeta.
code	Alfanumérico	Codigo del tipo
customerValidation	Alfanumérico	Si es Nominado, el tipo de validacion de customer (NO, API, FILE)
description	Alfanumérico	Descripcion del tipo
isActive	Booleano	True si se encuentra activo
isCVVRequired	Booleano	True si requiere cvv
isNominated	Booleano	True si es nominada
isRechargeable	Booleano	True is es recargable
name	Alfanumérico	Nombre del tipo

EJEMPLO 1: se solicitan los datos de la tarjeta 1000000000001 para la compañia napse y con movimientos del 01/04/2020 al 31/04/2020 sin especificar limites con lo cual seran los 5 ultimos movimientos.

.

Via CURL

Ejemplo

curl
 -X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8 
-H "Content-type: application/json" -H "Accept: application/json" "http://localhost:8080/promo/api/rest/card?code=1000000000001&companyId=napse&dateFrom=20200401&dateTo=20200431"

El cual recibirá una respuesta dle tipo:

Ejemplo

{
    "_id": "5ea975e31c8fcf4aec17953e",
    "amount": 320.0,
    "code": "1000000000001",
    "companyId": "napse",
    "created": "2020-04-29T12:41:07Z",
    "isConsumed": false,
    "status": "ENABLED",
    "storeCode": "BLC",
    "terminalCode": "001",
    "transactionId": "BLC_202004290941889",
    "type": "001",
    "version": 2,
    "cardHistory": [
        {
            "amount": "20.0",
            "cardAction": "AMOUNT_UPDATE",
            "date": "2020-04-29T12:42:26Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "300.0",
            "cardAction": "CHARGE",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "0",
            "cardAction": "ACTIVATION",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        }
    ]
}

EJEMPLO 2: se solicitan todos los movimientos del 29/04/2020 al 29/04/2020 con un maximo de 100.000 movimientos.

Via CURL:

Ejemplo

curl
 -X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8 
-H "Content-type: application/json" -H "Accept: application/json" "http://localhost:8080/promo/api/rest/card?companyId=napse&dateFrom=20200429&dateTo=20200429&limit=100000"

El cual recibirá una respuesta dle tipo:

Ejemplo

   {
    "cardHistory": [
        {
            "amount": "10.0",
            "card": "1000000000000",
            "cardAction": "AMOUNT_UPDATE",
            "date": "2020-04-29T12:42:18Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "300.0",
            "card": "1000000000000",
            "cardAction": "CHARGE",
            "date": "2020-04-29T12:02:06Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "0",
            "card": "1000000000000",
            "cardAction": "ACTIVATION",
            "date": "2020-04-29T12:02:06Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "20.0",
            "card": "1000000000001",
            "cardAction": "AMOUNT_UPDATE",
            "date": "2020-04-29T12:42:26Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "300.0",
            "card": "1000000000001",
            "cardAction": "CHARGE",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "0",
            "card": "1000000000001",
            "cardAction": "ACTIVATION",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "300.0",
            "card": "1000000000002",
            "cardAction": "CHARGE",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "0",
            "card": "1000000000002",
            "cardAction": "ACTIVATION",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "300.0",
            "card": "1000000000003",
            "cardAction": "CHARGE",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "0",
            "card": "1000000000003",
            "cardAction": "ACTIVATION",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "300.0",
            "card": "1000000000004",
            "cardAction": "CHARGE",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "0",
            "card": "1000000000004",
            "cardAction": "ACTIVATION",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "300.0",
            "card": "1000000000005",
            "cardAction": "CHARGE",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "0",
            "card": "1000000000005",
            "cardAction": "ACTIVATION",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        }
    ]
}

Tipos de Tarjetas

Cuando se especifica el parámetro "isTypes" se retornarán solamente los tipos de tarjeta definidos.

EJEMPLO 3:

Via CURL

Ejemplo

curl
 -X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8 
-H "Content-type: application/json" -H "Accept: application/json" "http://localhost:8080/promo/api/rest/card?companyId=napse&isTypes=true"

El cual recibira una respuesta del tipo:

Ejemplo

  {
    "cardTypes": [
        {
            "amountChargeLimit": 0.0,
            "cardNumberLength": 16,
            "cardTypePrefixRange": [
                {
                    "_id": "5f45547d830a697a4012df3c",
                    "creationAt": "2020-08-25T18:12:13Z",
                    "isSuggested": false,
                    "prefixEnd": 1000,
                    "prefixStart": 1
                },
                {
                    "_id": "5f45547d830a697a4012df3d",
                    "creationAt": "2020-08-25T18:12:13Z",
                    "isSuggested": false,
                    "prefixEnd": 2000,
                    "prefixStart": 1001
                }
            ],
            "code": "tc01",
            "customerValidation": "NO",
            "description": "TC01",
            "isActive": true,
            "isCVVRequired": false,
            "isNominated": false,
            "isRechargeable": true,
            "name": "TC01"
        },
        {
            "amountChargeLimit": 5000.0,
            "cardNumberLength": 11,
            "cardTypePrefixRange": [
                {
                    "_id": "5f45575d830a697a4012df40",
                    "creationAt": "2020-08-25T18:24:29Z",
                    "isSuggested": false,
                    "prefixEnd": 3000,
                    "prefixStart": 3000
                }
            ],
            "code": "tc02",
            "customerValidation": "FILE",
            "description": "TC02",
            "isActive": false,
            "isCVVRequired": true,
            "isNominated": true,
            "isRechargeable": true,
            "name": "TC02"
        }
    ]
}

Servicio De Consulta de Mapas

PROMO expone un servicio que permite consultar mapas utilizando solo el número de mapa y como respuesta se obtiene el xml del mapa de la misma forma que se obtiene por la opcion de "descargar".

Como en el caso de los servicios REST previamente descriptos se necesita una authorizacion via OAuth2.

La siguiente figura muestra el contenido del request de ejemplo:

Donde:

Operation: valor getMaps para obtener el mapa solicitado.

companyId: identificacion o codigo de empresa la cual realiza el request.

mapNumber: Numero de mapa solicitado.

La respuesta es del tipo:

Response

<?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>   
    <ack>0</ack>
    <message>OK</message>
    <maps>
        <map version:="5">
            <?xml version="1.0" encoding="iso-8859-1"?>
            <promo-engine start-date="15/01/2019 00:00" end-date="22/01/2084 23:59" validity-after-void="365" map-version="5" suggest="conditional">
                <parameter key="Logging" value="true" />
                <parameter key="LogConfigurationFile" value="logrsca.xml" />
                <parameter key="LogConfigurationCategory" value="com.synthesis.promo" />
                <parameter key="Descriptors" value="descriptor.properties" />
                <parameter key="DAOConfigurationFeatures" value="com.synthesis.promo.engine.dao.ConfigurationFeatures" />
                <parameter key="EvaluationAlgorithmClass" value="com.synthesis.promo.engine.evaluation.InStepsAlgorithm" />
                <promotions>
                    <promotion nro="5c3df6e0f7a021227ca8f7d4" name="Promociòn 10% de Descuento SKU 1" code="Promociòn 10% de Descuento SKU 1" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="true" suggest="not" descriptor="Promociòn 10% de Descuento SKU 1">
                        <sets>
                            <set name="5c3df6f6f7a021227ca8f7d8" type="item" attribute="code" comparator="Into" value="1" />
                        </sets>
                        <condition type="basic" name="Exists">
                            <parameter key="use-set" value="5c3df6f6f7a021227ca8f7d8" />
                        </condition>
                        <benefits>
                            <benefit instance="PercentageDiscount" nro="5c3df748f7a021227ca8f7dc">
                                <parameter key="displayMessage" value="Promociòn 10% de Descuento SKU 1" />
                                <parameter key="printerMessage" value="Promociòn 10% de Descuento SKU 1" />
                                <parameter key="TLOGMessage" value="Promociòn 10% de Descuento SKU 1" />
                                <parameter key="applicationMethod" value="lineByLine" />
                                <parameter key="prorationMethod" value="proportional" />
                                <parameter key="applicationPriceType" value="benefited-price" />
                                <parameter key="name" value="5c3df6e0f7a021227ca8f7d4" />
                                <parameter key="percent" value="10" />
                                <parameter key="unit" value="qty" />
                                <applied-elements>
                                    <use-set name="5c3df6f6f7a021227ca8f7d8" />
                                </applied-elements>
                            </benefit>
                        </benefits>
                    </promotion>
                    <promotion nro="5c3dfcd5f7a021227ca8f807" name="Promocion 3x2 en SKU 2" code="Promocion 3x2 en SKU 2" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="true" suggest="always" descriptor="Con 3 items del SKU 2 obtendra Promocion 3x2 en SKU 2">
                        <sets>
                            <set name="5c3dfd00f7a021227ca8f80c" type="item" attribute="code" comparator="Into" value="2" />
                        </sets>
                        <combo>
                            <combo-component min="3" max="3" attribute="qty" use-set="5c3dfd00f7a021227ca8f80c" />
                        </combo>
                        <benefits>
                            <benefit instance="PercentageDiscount" nro="5c3dfd52f7a021227ca8f80e">
                                <parameter key="displayMessage" value="Promocion 3x1 en SKU 2" />
                                <parameter key="printerMessage" value="Promocion 3x1 en SKU 2" />
                                <parameter key="TLOGMessage" value="Promocion 3x1 en SKU 2" />
                                <parameter key="applicationMethod" value="resume" />
                                <parameter key="prorationMethod" value="proportional" />
                                <parameter key="applicationPriceType" value="benefited-price" />
                                <parameter key="name" value="5c3dfcd5f7a021227ca8f807" />
                                <parameter key="percent" value="100" />
                                <parameter key="unit" value="qty" />
                                <applied-elements>
                                    <use-set name="5c3dfd00f7a021227ca8f80c" max="1.0" attribute="qty" />
                                </applied-elements>
                            </benefit>
                        </benefits>
                    </promotion>
                    <promotion nro="5c3dffd1f7a021227ca8f82e" name="Promocion Cupon de Regalo en SKU 3" code="Promocion Cupon de Regalo en SKU 3" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="true" suggest="not">
                        <sets>
                            <set name="5c3e0041f7a021227ca8f835" type="item" attribute="code" comparator="Into" value="3" />
                        </sets>
                        <condition type="basic" name="Exists">
                            <parameter key="use-set" value="5c3e0041f7a021227ca8f835" />
                        </condition>
                        <benefits>
                            <benefit instance="CouponBenefit" nro="5c3e0001f7a021227ca8f832">
                                <parameter key="displayMessage" value="Promocion Cupon de Regalo en SKU 3" />
                                <parameter key="printerMessage" value="Promocion Cupon de Regalo en SKU 3" />
                                <parameter key="TLOGMessage" value="Promocion Cupon de Regalo en SKU 3" />
                                <parameter key="applicationMethod" value="resume" />
                                <parameter key="prorationMethod" value="proportional" />
                                <parameter key="applicationPriceType" value="benefited-price" />
                                <parameter key="name" value="5c3dffd1f7a021227ca8f82e" />
                                <parameter key="qty" value="1" />
                                <parameter key="couponid" value="tc01" />
                                <applied-elements>
                                    <use-set name="5c3e0041f7a021227ca8f835" max="1.0" attribute="qty" />
                                </applied-elements>
                            </benefit>
                        </benefits>
                    </promotion>
                </promotions>
                <evaluation-algorithm>
                    <step>
                        <function name="ALL">
                            <function name="SIMPLE">
                                <promotion-usage name="Promociòn 10% de Descuento SKU 1" />
                            </function>
                            <function name="SIMPLE">
                                <promotion-usage name="Promocion 3x2 en SKU 2" />
                            </function>
                            <function name="SIMPLE">
                                <promotion-usage name="Promocion Cupon de Regalo en SKU 3" />
                            </function>
                        </function>
                    </step>
                </evaluation-algorithm>
            </promo-engine>
        </map>
    </maps>
</promoCoreResponse>

Donde se observa:

ack: resultado del request, donde 0 es procesamiento correcto. (Ver codigos de respuesta ack mas arriba en este documento).

message: es el mensaje de error resultante.

maps: tag general que contiene los elementos map retornados en la respuesta. Cada elemento map, contiene todos los elementos y tags que contiene un mapa como cuando es descargado a archivo.

Servicio De Consulta de Promociones Distribuidas

PROMO expone un servicio que permite consultar promociones distribuidas utilizando un filtro por compañía (obligatorio) y parámetros de filtros opcionales (tienda/as, región/es, código/os) y como respuesta se obtiene un xml con las promociones obtenidas.

Como en el caso de los servicios REST previamente descriptos se necesita una autorización via OAuth2.

La siguiente figura muestra el contenido del request de ejemplo:

Donde:

Operation (obligatorio): valor getPromotions para obtener promociones.

companyId (obligatorio): identificación o código de empresa la cual realiza el request.

stores (opcional): Tiendas a la que pertenece la / las promociones.

regions (opcional): Zonass a la que pertenece la / las promociones.

promoCode (opcional): Código / os de promociones solicitadas

La respuesta es del tipo:

getPromotions

<?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>
    <ack>0</ack>
    <message value="" />
    <promotions>
        <promotion nro="5c6c61f053c6832cc00eec0f" name="2 plays 1 xbox gratis" code="Promo1" className="com.synthesis.promo.engine.promotion.ConditionXComboPromotion" reportParticipants="false" suggest="not">
            <sets>
                <set name="5c6c689153c6832cc00eec24" type="item" attribute="code" comparator="Into" value="111" />
                <set name="5c6c625853c6832cc00eec13" type="item" attribute="code" comparator="Into" value="111" />
                <set name="5c6c628d53c6832cc00eec15" type="item" attribute="code" comparator="Into" value="112" />
                <set name="5c6c6aae53c6832cc00eec38" type="item" attribute="code" comparator="Into" value="112" />
            </sets>
            <condition type="basic" name="Exists">
                <parameter key="use-set" value="5c6c689153c6832cc00eec24" />
            </condition>
            <combo>
                <combo-component min="2" max="2" attribute="qty" use-set="5c6c625853c6832cc00eec13" />
                <combo-component min="1" max="1" attribute="qty" use-set="5c6c628d53c6832cc00eec15" />
            </combo>
            <benefits>
                <benefit instance="PercentageDiscount" nro="5c6c64fd53c6832cc00eec19">
                    <parameter key="displayMessage" value="2 plays 1 xbox gratis" />
                    <parameter key="printerMessage" value="2 plays 1 xbox gratis" />
                    <parameter key="TLOGMessage" value="2 plays 1 xbox gratis" />
                    <parameter key="applicationMethod" value="resume" />
                    <parameter key="prorationMethod" value="proportional" />
                    <parameter key="applicationPriceType" value="benefited-price" />
                    <parameter key="name" value="5c6c61f053c6832cc00eec0f" />
                    <parameter key="percent" value="100" />
                    <parameter key="unit" value="qty" />
                    <applied-elements>
                        <use-set name="5c6c6aae53c6832cc00eec38" />
                    </applied-elements>
                </benefit>
            </benefits>
        </promotion>
        <promotion nro="5c6c61f053c6832cc00eec0frest" name="2 plays 1 xbox gratisrest" code="Promo2" className="com.synthesis.promo.engine.promotion.ConditionXComboPromotion" reportParticipants="false" suggest="not">
            <sets>
                <set name="5c6c689153c6832cc00eec24" type="item" attribute="code" comparator="Into" value="111" />
                <set name="5c6c625853c6832cc00eec13" type="item" attribute="code" comparator="Into" value="111" />
                <set name="5c6c628d53c6832cc00eec15" type="item" attribute="code" comparator="Into" value="112" />
                <set name="5c6c6aae53c6832cc00eec38" type="item" attribute="code" comparator="Into" value="112" />
            </sets>
            <condition type="basic" name="Exists">
                <parameter key="use-set" value="5c6c689153c6832cc00eec24" />
            </condition>
            <combo>
                <combo-component min="2" max="2" attribute="qty" use-set="5c6c625853c6832cc00eec13" />
                <combo-component min="1" max="1" attribute="qty" use-set="5c6c628d53c6832cc00eec15" />
            </combo>
            <benefits>
                <benefit instance="PercentageDiscount" nro="5c6c64fd53c6832cc00eec19">
                    <parameter key="displayMessage" value="2 plays 1 xbox gratis" />
                    <parameter key="printerMessage" value="2 plays 1 xbox gratis" />
                    <parameter key="TLOGMessage" value="2 plays 1 xbox gratis" />
                    <parameter key="applicationMethod" value="resume" />
                    <parameter key="prorationMethod" value="proportional" />
                    <parameter key="applicationPriceType" value="benefited-price" />
                    <parameter key="name" value="5c6c61f053c6832cc00eec0frest" />
                    <parameter key="percent" value="100" />
                    <parameter key="unit" value="qty" />
                    <applied-elements>
                        <use-set name="5c6c6aae53c6832cc00eec38" />
                    </applied-elements>
                </benefit>
            </benefits>
        </promotion>
    </promotions>
</promoCoreResponse>

Donde se observa:

ack: resultado del request, donde 0 es procesamiento correcto. (Ver códigos de respuesta ack mas arriba en este documento).

message: es el mensaje de error resultante.

promotions: tag general que contiene los elementos promotion retornados en la respuesta. Cada elemento promotion, contiene todos los elementos y tags que contiene una promoción.

Servicio De Consulta de Promoción

PROMO expone tres servicios que permiten consultar una promoción utilizando un filtro por compañía (obligatorio) y consultar mediante número de promoción o código de promoción o número de beneficio de promoción y como respuesta se obtiene un xml con la promoción obtenida.

Como en el caso de los servicios REST previamente descriptos se necesita una autorización via OAuth2.

Las siguientes figuras muestran los contenidos de los request mencionados

Donde:

Operation (obligatorio): valor getPromotionsByNro, getPromotionsByCode o getPromotionsByBenefitNro.

companyId (obligatorio): identificación o código de empresa la cual realiza el request.

nro (obligatorio): para una búsqueda mediante el número de promoción o para una búsqueda mediante el número de benefició de promoción.

promoCode (obligatorio): para una búsqueda mediante el código de promoción

La respuesta es del tipo:

<?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>
    <ack>0</ack>
    <message value="" />
    <promotions>
        <promotion nro="5c9cd81353c6832f848f8ffb1" name="promoParaCancelar1" code="Promo1" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not">
            <sets>
                <set name="5c9cd83053c6832f848f8ffe" type="item" attribute="code" comparator="Into" value="111" />
            </sets>
            <condition type="basic" name="Exists">
                <parameter key="use-set" value="5c9cd83053c6832f848f8ffe" />
            </condition>
            <benefits>
                <benefit instance="PercentageDiscount" nro="5c9cd86f53c6832f848f9001">
                    <parameter key="displayMessage" value="promoParaCancelar" />
                    <parameter key="printerMessage" value="promoParaCancelar" />
                    <parameter key="TLOGMessage" value="promoParaCancelar" />
                    <parameter key="applicationMethod" value="resume" />
                    <parameter key="prorationMethod" value="proportional" />
                    <parameter key="applicationPriceType" value="benefited-price" />
                    <parameter key="name" value="5c9cd81353c6832f848f8ffb1" />
                    <parameter key="percent" value="10" />
                    <parameter key="unit" value="qty" />
                    <applied-elements>
                        <use-set name="5c9cd83053c6832f848f8ffe" />
                    </applied-elements>
                </benefit>
            </benefits>
        </promotion>
    </promotions>
</promoCoreResponse>

Donde se observa:

ack: resultado del request, donde 0 es procesamiento correcto. (Ver códigos de respuesta ack más arriba en este documento).

message: es el mensaje de error resultante.

promotions: tag general que contiene los elementos promotion retornados en la respuesta. Cada elemento promotion, contiene todos los elementos y tags que contiene una promoción.

Servicio Próximo Número de tarjeta

PROMO expone un servicio que permita consultar, para un determinado tipo de tarjeta cual es el próximo numero de tarjeta inactivo y sin cliente asociado.

Para los ejemplos se realizaron las consultas de tarjetas utilizando la herramienta "PostMan" de Chrome. Deberá obtenerse un nuevo Tocken (cUrl), y luego podrá realizarse la consulta de próximo numero de tarjetas (PostMan).
El único método aceptado para realizar este pedido es POST.

Como todo servicio rest de la consola, para realizar cualquier operación será necesario utilizar un token de acceso. El mismo debe incluirse en la cabecera http Authorization, por ej.

Authorization
Bearer fb489bee-ff9f-4a4b-905c-28c6969ef180 No olvidar el Bearer(Espacio)

curl -v -X POST -u my-client: -d "grant_type=password" -d "username=sender" -d "password=mate" -d "scope=read"http://localhost:8080/promo/oauth/token

El cuerpo del mensaje deberá ser un xml. A continuación se detallarán las posibles peticiones y sus respuestas involucradas.

Ejemplo de Consulta por proximo numero de Tarjeta

<promoCoreRequest>
 <operation>NextCardNumber</operation>
     <params>
        <type>nominada</type>
     </params>
</promoCoreRequest>

Respuesta - Se informa el próximo numero de tarjeta

<promoCoreResponse>
  <ack>0</ack>
  <message>
    <id>2345000000002</id>
  </message>
</promoCoreResponse>

Servicio de Reporte de Promociones

(> v7.EP2.1)

PROMO expone un servicio que permite consultar la misma información que se obtiene del Reporte de Promociones por Consola (ver dicho reporte para información de filtros y datos).

Los parámetros de entrada de la consulta son:

Propiedad	Tipo de dato	Descripción
*companyId*	Alfanumérico	Código de la compañia
*limit*	Numérico	Cantidad de registros de movimientos a retornar con un maximo de 50.000 por consulta. Default: 25
*offset*	Numérico	Registro desde el cual comenzar el conteo hasta "limit" registros. Default: 0
*dateFrom*	Numérico	Fecha de Inicio en formato YYYYMMDD.
*dateTo*	Numérico	Fecha de Final en formato YYYYMMDD.
*transactionType*	Alfanumérico	Opcionalmente se puede filtrar por tipo de Transaccion: SALES o RETURN. Default: '' (Todas)
*store*	Alfanumérico	Código de Tienda por el cual se quiere filtrar. Default: '' (Todas)
pname	Alfanumérico	El nombre de la Promoción por el cual se desea filtrar. Default: '' (Todas)
pcode	Alfanumérico	El código de la Promoción por la cual se desea filtrar. Default: '' (Todas)

La Respuesta será del tipo JSON con los siguientes parámetros:

Propiedad	Tipo de dato	Descripción
*Records*	Vector	Cada uno de los registros que componen el reporte
*Header*	Vector	Encabezado con informacion adicional

Cada elemento del Vector Records contendrá los siguientes parámetros correspondientes a cada una de las columnas del informe:

Propiedad	Tipo de dato	Descripción
*transactionId*	Alfanumérico	Código de la transacción
*offline*	Booleano	Verdadero si la transacción fué realizada en modo offline
*unitPrice*	Numérico	Precio unitario del producto
*benefitClass*	Alfanumérico	Clase de beneficio
*itemCode*	Alfanumérico	Codigo de Producto
*discountApply*	Numérico	Descuento Aplicado
*deploymentChannels*	Alfanumérico	Canal de Publicacion
date	Alfanumérico	Fecha de la transaccion
transactionType	Alfanumérico	Tipo de Transaccion
campaign	Alfanumérico	Campaña
quantity	Numérico	Cantidad del Producto
promotionCode	Alfanumérico	Codigo de Promocion
promotionName	Alfanumérico	Nombre de la Promocion
store	Alfanumérico	Tienda
subTotal	Numérico	Subtotal de la transaccion
conditionTimeRange	Alfanumérico	Condicion de Fecha/hora si aplica.

Cada elemento del Vector Header contendrá los siguientes parámetros Informativos:

Propiedad	Tipo de dato	Descripción
*total*	Numérico	Total de Registros disponibles
*offset*	Numérico	offset solicitado actualmente
limit	Numérico	Limite solicitado actualmente

Esta informción sirve para mantener una paginación como sucede en pantalla pero a nivel servicio. Digamos:

Primer consulta: offset: 0, limit: 25 → returna la primer pagina de 25 registros y me informa un total de 500.

Segunda consulta: offset: 25, limit 25 → retorna la segunda pagina, es decir registros 26 a 50.

En lo sucesivo se podra ir pidiendo paginas hasta llegar a offset: 475, limit 25.

Tambien se podria realizar un paginado de a 100 registros por consulta, etc. (limit: 100).

EJEMPLO 1:

Solicitamos un reporte de Promociones para la compañia myCompany, entre el 21/11/2020 y el 04/12/2020, limitado a 25 registros a partir del 500 (esto es el equivalmente a la pagina 21 en pantalla), para el codigo de Promocion 10549

Obteniéndose la siguiente respuesta:

Ejemplo

{
    "records:": "[{\"transactionId\":\"xx_0621_002_20201202123540\",\"offline\":false,\"unitPrice\":10400.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"1580203\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"02/12/2020 04:35\",\"transactionType\":\"Venta\",\"campaign\":\"Mercadeo\",\"quantity\":1.0,\"promotionCode\":\"10549\",\"promotionName\":\"MY PROMO-10549\",\"store\":\"0621 - MY STORE \",\"subTotal\":10400.0,\"conditionTimeRange\":\"\r\nEntre las fechas con horario 26/11/2020 02:00-06/12/2020 01:59\r\n\"},{\"transactionId\":\"xx_0621_001_20201202112635\",\"offline\":false,\"unitPrice\":5600.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"720190\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"02/12/2020 03:26\",\"transactionType\":\"Venta\",\"campaign\":\"Mercadeo\",\"quantity\":1.0,\"promotionCode\":\"10549\",\"promotionName\":\"MY PROMOTION-10549\",\"store\":\"0621 - MY STORE\",\"subTotal\":5600.0,\"conditionTimeRange\":\"\r\nEntre las fechas con horario 26/11/2020 02:00-06/12/2020 01:59\r\n\"}]",
    "header": {
        "total": 504,
        "offset": 500,
        "limit": 25
    }
}

.

Consola: Servicios REST de Carga de Datos

Aqui se presentan los servicios provistos para enviar o cargar información en PROMO.

Antes de consumir el servicio debe obtenerse el TOKEN de identificación como se explica en "Seguridad: Atenticación de Sistemas Externos con los Servicios"

Precios: Servicio de Carga De Lista Cero

Se creo un Servicio Rest que permite la carga de los productos de una lista cero, El Mismo recibe la información y sera procesada de manera asincrónica, es decir recibe la información y luego sera procesada.

La Lista cero es la lista base donde se encontraran todos los precios de los productos, la misma tiene la prioridad mas baja de las listas (El motor al consultar los precios evalúa las listas existentes de prioridad de mayor a menor).

La Lista cero sera enviada desde un sistema externo a promo, el proceso crea y actualiza los precios enviados.

En la consola se agrego la pantalla de Monitoreo de Importaciones. en la sección de soporte, desde esta pantalla se podrá ver el resultado de la importación, ver la información enviada en la importación (menú contextual Contenido), el detalle de la importación mostrará el total de los registros los procesados correctamente y los que tuvieron errores, estos últimos en caso de existir se verán en la pantalla paginados o se podrá descargar los mismos en un archivo de texto. El monitor también permite el re proceso de la importaciones.

El Método es un POST a la siguiente dirección: <promo>/api/rest/priceList con el siguiente body:

{
	"companyId": "napse",
	"store": "napse",
	"items": [
		 {
		"sku": "0527-1537",
		"salePrice": 69406.77,
		"costPrice": 50942.13,
		"saleCreditPrice": 119716.68,
		"magnitudePrice": 829,
		"measuredUnit": "cm3",
		"supplierItem": "PR3",
		"supplierFinancial": "PR2",
		"supplierItemAmount": 52471,
		"supplierFinancialAmount": 53604,
		"saleWholesalePrice": 31858,
		"saleWholesaleLimit": 6081,
		"limit": 794,
		"enabledDate": "2018-12-25T10:42:25Z"
         "discountable":true,
         "manualDiscount":false
	}, 	
	{
		"sku": "66897-001",
		"salePrice": 39123.0,
		"costPrice": 10452.59,
		"saleCreditPrice": 42433.6,
		"magnitudePrice": 371,
		"measuredUnit": "kg",
		"supplierItem": "PR2",
		"supplierFinancial": "PR2",
		"supplierItemAmount": 52551,
		"supplierFinancialAmount": 21423,
		"saleWholesalePrice": 78603,
		"saleWholesaleLimit": 9691,
		"limit": 2982,
		"enabledDate": "2019-01-20T10:41:55Z"
	}
	]
}

La respuesta del mismo será en caso Ok (Http.status=200)

{
    "status": "Informacion Recibida OK",
    "description": "La lista de precios será procesada"
}

En caso de Error: (Http.status=400)

{
    "status": "companyId is Required",
    "description": "Debe enviar el campo companyId"
}

{
    "status": "companyId is Invalid",
    "description": "Debe enviar el campo companyId valido"
}

Nota: La compania enviada en el rest debe tener el modulo de precios habilitado para que el servicio se habilite

Propiedad	Tipo de dato	Descripción
*companyId*	Alfanumérico	Código de la compania
*store*	Alfanumérico	Código de la tienda de Promo
*sku*	Alfanumérico	Código del producto
*salePrice*	Numérico	Precio de venta
*costPrice*	Numérico	Opcional. Precio de costo
*saleCreditPrice*	Numérico	Precio de crédito
*magnitudePrice*	Numérico	Opcional. Precio por magnitud (kilo, litro, bulto, etc)
*measuredUnit*	Alfanumérico	Opcional. unidad de medida
*supplierItem*	Alfanumérico	Opcional.Es el código del proveedor del ítem
*supplierItemAmount*	Numérico	Opcional. Es el monto que el proveedor reconoce (monto del recupero)
*supplierFinancial*	Alfanumérico	Opcional. Es el código del proveedor financiero del ítem
*supplierFinancialAmount*	Numérico	Opcional. Es el monto que el proveedor Financiero reconoce (monto del recupero)
saleWholesalePrice	Numérico	Opcional.Precio mayorista
*saleWholesaleLimit*	Numérico	Opcional. Cantidad a partir de la cual aplica el precio mayorista
*limit*	Numérico	Opcional.(límite de unidades que se podrán vender a ese precio)
enabledDate	Fecha	Fecha que indica apartir de cuando el precio es valido (FORMATO ISO 8601 (UTC))
discountable	Booleano	Opcional. determina si el item se le puede aplicar descuento.(de omitir dicho campo por default sera true)
manualDiscount	Booleano	Opcional. determina si el item se le puede aplicar descuento Manual .(de omitir dicho campo por default sera true)

El proceso de importación de la lista cero, insertara/actualizara el producto en la lista cero de la tienda, en caso de tener el campo enable_date con una fecha futura,ese precio se habilitara en el momento que sea el enable_date.

El proceso de actualización de precios para una lista cero, lockea mientras se esta procesando la actualización, en caso inesperado error no contemplado y quede lockeado, hay un configuration data que determina el tiempo en minutos de espera de un lockeo de actualización que es el siguiente (luego de ese tiempo se podrá volver a correr el proceso para esa lista cero).

ConfigurationData.readAsInteger(companyId, "prices", "priceList.lockForUpate",15)

Servicio de Importación de Catálogos

PROMO expone este nuevo servicio para brindar una alternativa en la carga/recepción de catalogos que, hasta la presente versión, podia realizarse unicamente via archivos. Para comprender esta sección se recomienda referirse al manejo de catalogos en el manual del usuario.

El esquema de autenticación es el mismo que en los demás servicios REST presentados aqui (ver mas arriba).

Una vez obtenido el token de acceso, el servicio puede ser invocado utilizando el método POST, desde la URL: <promo>/api/rest/catalogs

El formato general del request es:

{
 "companyId": "myCompanyId",
"catalog":"CatalogId",
"params":[      
"param1":"param1value",
"paramN":"paramNvalue"
],
"items": [
{.... primer item .......},
{.... otro item .......},
{.... otro item .......},
{.... otro item .......},
{.... otro item .......},
]
}

donde

Campo	Descripción	Tipo de Dato
companyId	codigo de Empresa	alfanumérico
catalog	identificador del catálogo	alfanumérico
params	Parametros que dependeran del catálogo	Listado de objetos de tipo clave, valor. Cada catalogo puede tener sus parametros especificos, pero como valor genérico tenemos: "deleteAllCollectionFirst" : "true" Indica que antes de realizar la importacion de este conjunto de registros se realice el borrado de todos los registros existentes. NOTA: (desde 6.5.5 y 7.TRK) Ejemplo: [...] "params": [ { "deleteAllCollectionFirst": "true" } ], [...] Importante No aplica a tarjetas de fidelidad y asignacion de convenios.
items	Registros a importar	Coleccion de objetos dependientes de cada catálogo

Cada uno de los items dependerá del catalogo en su formato, pero existe un campo común a todos:

Campo	Descripcion	Tipo de Dato
operation	La operación a realizar sobre el elemento. Los valores posibles son: I: Insertar U: Actualizar R: Eliminar IU: (desde 6.5.5 y 7.TRK) Insertar/Actualizar: Si el registro no existe sera insertado (I), si existe será actualizado (U). Importante No aplica a tarjetas de fidelidad y asignacion de convenios.	Alfanumérico

La respuesta sera del tipo:

{
    "status": "200",
    "description": "CatalogCountry",
    "detail": {
        "result": "ok",
        "detail": "Info adicional"
    }
}

donde:

Campo

Descripción

Tipo de Dato

Posibles valores

status

codigo de Respuesta

alfanumérico

200 (válido), 400 (errores de validación o de sintaxis json), 500 (error genérico)

description

identificador del catálogo

alfanumérico

Cada uno de los nombre de los catálogos importables por mensaje rest, o bien cadena vacía si no es posible obtenerlos (por ej. ante un error de sintaxis json).

detail

Información adicional

Objeto

Clave result, con los resultados posibles, es decir, ok o error.

Clave detail, con valor correspondiente al mensaje informativo de validación, error, o procesamiento válido.

Consideraciones

1. El número de registros por paquete (request) estará limitado a 1000 items para no afectar la performance y que las respuestas puedan ser procesadas.
2. En caso de error se informaran los registros erroneos pero los que han resultado correctos seran incorporados. Los resultados podrán visualizarse en la consola en la pantalla de Monitor de Importación.
3. En todos los casos se informara la cantidad total de lineas con error y las correctas. Los resultados podrán visualizarse en la consola en la pantalla de Monitor de Importación.
4. El proceso utiliza semaforos para evitar la concurrencia de clientes que pretendan procesar en paralelo ya que implica posibilidad de errores en las validaciones.

Servicio de CANJE DE PUNTOS POR CATALOGO

(Desde 6.5.2)

Como soporte al Nuevo beneficio de Canje de Puntos por Catalogo (ver mas arriba), se deben especificar la tabla de productos que poseen equivalente en puntos a través de un catalogo definido para tal uso.

Siguiendo el formato especificado anteriormente tendremos:

Campo	Valor
companyId	El código de la compañia correspondiente.
catalog	"CatalogRedeemBenefit". No se debe modificar.
params	Un listado vacío. No se debe modificar.
items	Un listado con cada item del catálogo de Canje de puntos.

Dentro de items, el formato es:

Campo	Valor
store	Código de tienda. Requerido. Alfanumérico. Si se aplica a todas las tiendas, el código de la tienda debe ser "-".
code	Código del producto. Requerido. Alfanumérico.
points	Puntos requeridos. Numérico con decimales.
discountValue	Valor descuento. Numérico con decimales.
discountType	Tipo descuento. Acepta sólo los valores "perc" (porcentaje), "fix" (descuento fijo), o bien, "nprice" (nuevo precio)
operation	La operación a realizar sobre el elemento. Ver tabla con valores posibles.

Así tendremos que un ejemplo de request para insertar registros en este catálogo será:

{
    "companyId": "napse",
    "catalog": "CatalogRedeemBenefit",
    "params": [],
    "items": [
        {
            "store": "1",
            "code": "10",
            "points": "10.5",
            "discountValue":"15" ,
            "discountType": "perc",
            "operation": "I"
        },
        {
            "store": "1",
            "code": "20",
            "points": "20.5",
            "discountValue":"20" ,
            "discountType": "fix",
            "operation": "I"
        },
		{
            "store": "-",
            "code": "30",
            "points": "50",
            "discountValue":"25" ,
            "discountType": "nprice",
            "operation": "I"
        }
	]
}

Servicio de Asignación de Tarjetas de Fidelidad

Esta operación es el equivalente a la función de asignacion/actualización de tarjetas, mas la importación de clientes nuevos (Ver proceso actual de asignación de convenios). En este caso los campos serán:.

{
    "companyId": "napse",
    "catalog": "CatalogCardAssign",
    "params": [
        {
            "cardType": "tipo1"
        },
        {
            "contract": "convenio1"
        }
    ],
    "items": [
        {
            "operation": "I",
            "id": "1111000000030",
            "customer": "codCliente1",
            "amount": "90.37",
            "name": "Juan",
            "surname": "Perez",
            "gender": "hom",
            "birthDate": "19900506",
            "idType": "dni",
            "identifier": "33334444",
            "idDate": "21001005",
            "nacionality": "Argentina",
            "email": "[email protected]",
            "customerType": "gold",
            "address": "Urquiza 20",
            "country": "ar",
            "state": "bsas",
            "city": "tig",
            "postalCode": "7669",
            "phone": "2222-4444"
        }
	,{otro item.......}
	,{otro item.......}
	,{otro item.......}
	,{otro item.......}
	,{otro item.......}
	,{otro item.......}
    ]
}

Los campos en negrita son obligatorios.

Campo	Descripción
params	cardType: Tipo de tarjeta a importar que sera validado. contract: codigo de convenio al que pertenecen estas tarjetas/clientes.
operation	I: Inserción / U: Actualización / R: Eliminación
id	La tarjeta debe existir. Requerido
customer	Si viene informado el cliente y en la DB la tarjeta no tiene un cliente asociado, se verificara si el cliente informado existe en la DB, y de ser así, se actualizara el campo con el valor informado en el archivo. Si el cliente informado, no existe en la DB, *se darà de alta con los datos correspondientes al cliente (ver name inclusive en adelante). Si viene informado el cliente, y en la DB la tarjeta tiene asociado el mismo cliente, queda el campo como esta. Si viene informado el cliente, y en la DB la tarjeta tiene asociado otro cliente, informara en el detalle de errores que la tarjeta tiene asociado otro cliente en la DB, y no permitirá procesar ese registro. Si no viene informado el cliente, informara un mensaje indicando que el campo cliente es mandatorio, y no permitirá procesar ese registro*.
amount	No puede contener un valor negativo Requerido Numérico con decimales. DESDE 6.5: Se agrega un operador a la izquierda del monto para que el mismo se sume o reste al monto actual de la tarjeta. Para reemplazar el monto, no debe especificarse un operador. Ejemplo, con tarjeta con 100 de monto: +100 resulta en monto de 200. -60 resulta en monto de 40. 70 resulta en monto de 70. Enviar el valor como string.
name	Nombre del Cliente. Cadena libre.
surname	Apellido. Cadena libre.
gender	Género. (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin.
birthDate	Fecha de nacimiento. Cadena en formato "yyyyMMdd". Más Información del formato
idType	Tipo de identificacion (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin.
identifier	Numero de Identificación del Cliente
idDate	Fecha de Expiración de la identificación. Cadena en formato "yyyyMMdd". Más Información del formato
nacionality	Nacionalidad. Cadena Libre.
email	Direccion de correo electrónico. Cadena libre.
customerType	Tipo de Cliente (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin.
address	Dirección. Cadena libre
country	País. (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin.
state	Estado/Provincia (ver valores por Catálogo). Depende de los valores cargados en el catálogo a tal fin.
city	Ciudad (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin.
postalCode	Codigo Postal
phone	Telefono

Árvore de páginas

PROMO - Manual de Integración 7.0 - Servicios

Acerca del manual

Propósito y alcance

Documentación de PROMO

Herramientas utilizadas

Seguridad: Atenticación de Sistemas Externos con los Servicios

Consola: Servicios REST de Consulta

Consulta de Datos de Clientes

Servicio de Consulta de Cupón

Servicio DE Consulta de Tarjetas

Tipos de Tarjetas

Servicio De Consulta de Mapas

Servicio De Consulta de Promociones Distribuidas

Servicio De Consulta de Promoción

Servicio Próximo Número de tarjeta

Servicio de Reporte de Promociones

Consola: Servicios REST de Carga de Datos

Precios: Servicio de Carga De Lista Cero

Servicio de Importación de Catálogos

Consideraciones

Servicio de CANJE DE PUNTOS POR CATALOGO

Servicio de Asignación de Tarjetas de Fidelidad