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: Autenticació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 aquí.
Primero deberá de solicitarse el Tocken de acceso, que utilizando CURL el comando sería:
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:
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
Aquí se presentan los servicios provistos para consulta de información contenida en PROMO.
Antes de consumir el servicio debe obtenerse el TOKEN de identificación como se explica en "Seguridad: Autenticació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á:
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.-
Consulta de Estado de limites de Clientes
PROMO expone un servicio que permite consultar para un cliente, cuales son las promociones con limites que se le han aplicado en las transacciones que haya podido realizar, a la BBDD utilizando el ID de cliente.
Si no tiene limites asociados el cliente consultado. el campo "limitsDetail" se devolverá vacío.
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á:
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/limit/limitStatus?companyId=exito&code=85001"
Obteniéndose la siguiente respuesta:
Ejemplo { "customerId": "85001", "companyId": "exito", "limitsDetail": [ { "_id": "603a437c1082e83690817050", "promotionId": "603a319c1082e83690816f95", "benefitId": "603a31b81082e83690816f9c", "promotionCode": "3", "promotionName": "limite cliente", "limitId": "603a31b61082e83690816f9b", "scope": "CUSTOMER", "period": "UNDEFINED", "maxValue": 5.0, "customerId": "85001", "storeId": "-", "numberDays": 0, "nextReset": "2021-02-27T03:00:00+0000", "lastReset": "2021-02-27T03:00:00+0000", "companyId": "exito", "limitTypeCode": "benefitApplicationCount", "description": null, "lastUpdate": "2021-02-27T13:05:00+0000", "active": true, "currentValue": 1.0 } ] } |
En caso de que el cliente no exista en la base la respuesta informara "El cliente especificado no existe".-
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ñía |
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 máximo 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 | Código 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 |
timeFrom | Numérico | (desde 7EP2) Hora de Inicio con formato HHmm |
timeTo | Numérico | (desde 7EP2) Hora de Fin con formato HHmm |
Aclaración
Se pueden enviar el dateFrom y dateTo sin cargar los datos de timeFrom y timeTo, estos serán opcionales. Pero solo se utilizarán los parámetros timeFrom y timeTo si tiene cargados los parámetros de dateFrom y dateTo, caso contrario no serán utilizados.
EJEMPLO 1: se solicitan los datos del cupon 1020000000007
La misma pero utilizando CURL:
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:
{ "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 transacción, tipo de operación, monto, tienda.
Para consumir este servicio se debe realizar una solicitud del tipo GET con los parámetros 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ñía |
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 máximo de 100.000 por consulta. |
dateFrom | Numérico | Fecha de Inicio en formato YYYYMMDD |
dateTo | Numérico | Fecha de Final en formato YYYYMMDD |
requestTypes | Booleano | (desde 7.EP2.1) Si se especifica el valor true se retornarán solamente los tipos de tarjetas definidos. *ver ejemplo mas abajo |
cardAction | Alfanumérico | (desde 7.0.4) Código de Operación que se quiere consultar. Si no se especifica code. Por defecto son todas las operaciones. Los valores disponibles son: CHARGE, RECHARGE, AMOUNT_UPDATE, SALE, EXTENDED_POINTS |
timeFrom | Numérico | (desde 7.0.4) Hora de Inicio en formato HHmm |
timeTo | Numérico | (desde 7.0.4) Hora de final en formato HHmm |
Aclaración
Se pueden enviar el dateFrom y dateTo sin cargar los datos de timeFrom y timeTo, estos serán opcionales. Pero solo se utilizarán los parámetros timeFrom y timeTo si tiene cargados los parámetros de dateFrom y dateTo, caso contrario no serán utilizados.
Si se especifica una tarjeta, se retornarán los datos y movimientos asociados a dicha tarjeta, pudiéndose 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 las 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 | ||||||
customerId | Alfanumérico | Id de cliente asocido a la tarjeta | ||||||
activation | Numérico | Fecha de activacion | ||||||
isConsumed* | Booleano | Si ha sido consumida o no | ||||||
status* | Alfanumérico | Estado actual de la tarjeta | ||||||
storeCode* | Alfanumérico | Codigo de Tienda de generación (si aplica) | ||||||
terminalCode* | Alfanumérico | Codigo de terminal de generación (si aplica) | ||||||
transactionId* | Alfanumérico | Codigo de Transacción que la genero (si aplica) | ||||||
lastPurchaseDate | Numérico | Fecha del ultimo movimiento | ||||||
type* | Alfanumérico | Tipo de Tarjeta | ||||||
typeName | Alfanumérico | Nombre del tipo de tarjeta | ||||||
amountPrev | Numérico | monto previo | ||||||
version* | Numérico | Uso Interno | ||||||
cardHistory | Colección | Conjunto de registros que corresponden a cada movimiento de la tarjeta, con:
Conjunto de refistros que corresponden a la promocion que aplica al movimiento de tarjeta
|
- Estos datos son retornados solo si se consulta por un código 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
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 del tipo:
{ "_id": "6054129516f79ab3103ad3ac", "companyId": "exito", "code": "s_verdes3095535912", "status": "ENABLED", "type": "s_verdes", "amount": 20.0, "customerId": "3095535912", "created": "2021-03-19T02:55:17Z", "activation": "2021-03-19T02:55:17Z", "transactionId": "exito_1_1_20210319203011", "storeCode": "1", "terminalCode": "1", "isConsumed": false, "version": 2, "lastPurchaseDate": "2021-03-19T02:56:30Z", "typeName": "Stickers Verdes", "cardHistory": [ { "date": "2021-03-19T23:30:15Z", "createdAt": "2021-03-19T02:56:30Z", "card": "-", "cardAction": "SALE", "storeCode": "1", "terminalCode": "1", "appliedPromotionDetails": [ { "promotionName": "otorga Stickers Verdes-54", "promotionCode": "54", "conditionDateRangeDescription": null } ], "customerCode": "-", "amount": "20.0", "amountPrev": "0.0", "transactionId": "exito_1_1_20210319203015", "reasonName": null }, { "date": "2021-03-19T02:55:17Z", "createdAt": "2021-03-19T02:55:17Z", "card": "-", "cardAction": "ACTIVATION", "storeCode": "1", "terminalCode": "1", "customerCode": "3095535912", "amount": "0.0", "amountPrev": "0", "appliedPromotionDetails": null, "transactionId": null, "reasonName": null } ], "amountPrev": 0 }
EJEMPLO 2: se solicitan todos los movimientos del 29/04/2020 al 29/04/2020 con un maximo de 100.000 movimientos.
Via CURL:
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 del tipo:
{ "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
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 recibirá una respuesta del tipo:
{ "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:
<?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:
<?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.
<promoCoreRequest> <operation>NextCardNumber</operation> <params> <type>nominada</type> </params> </promoCoreRequest>
<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
Aquí 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: Autenticació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 será 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 catálogos que, hasta la presente versión, podía realizarse únicamente vía archivos. Para comprender esta sección se recomienda referirse al manejo de catálogos en el manual del usuario.
El esquema de autenticación es el mismo que en los demás servicios REST presentados aquí (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 |
| 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:
[...] "params": [ [...] Importante No aplica a tarjetas de fidelidad y asignación de convenios. |
items | Registros a importar | Colección de objetos dependientes de cada catálogo Atributos dinamicos. Para el Catalogo de Ítems (catalogItem) podrán incorporarse a la carga de los atributos dinámicos de los ítems que se estén dando de alta. Para ello deberá especificarse el nombre de los atributos dinámicos dados de alta por consola dentro del tag "items": [ {.... primer item .......}] Nota: El campo "Sublinea" corresponde al atributo dinámico del item
Los Atributos dinámicos cargados vía Servicio serán tomados para la validación entre atributos del elemento Producto en la definición de condiciones de una promoción, cuando ésta funcionalidad se encuentre habilitada en consola. (Ver PROMO - Manual de Usuario Final - 7) Ejemplo de catalogItem con Atributos dinámicos. { "companyId": "exito", "catalog": "catalogItem", "params": [], "items": [{ "operation": "U", "code": "111", "name": "item A", "unitprice": 5000, "level1": "depart-1", "level2": "family-1", "level3": "category-1", "level4": "subcategory-1", "supplier": "tecno-1", "brand": "Marca-1", "detail": "detalle-1", "sublinea":"sublinea1" }] } |
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:
| Alfanumérico |
La respuesta será 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
- 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.
- 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.
- 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.
- 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 Importación Masiva de Promociones vía REST
(Desde 7.0.2)
Este servicio permite realizar la importación de promociones en forma masiva a través de REST a la consola de PROMO.
El esquema de autenticación es el mismo que en los demás servicios REST presentados aquí (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/import
Es importante que al momento de importar, se definan plantillas específicas, esto facilitará mucho la tarea del armado del servicio.
Ejemplo: si vamos a importar descuentos por porcentaje, lo mas importante es definir la plantilla en JSON.
El armado de la plantilla es un proceso que debe realizar una persona con conocimiento de la plataforma.
Un ejemplo de creación, inactivación o actualización de un conjunto de promociones, es el siguiente:
{ "companyId": "napse", "promotions": [ { "operation": "I", "name": "Entrega de un cupon para proxima compra", "code": "P2002", "sets": { "set": [ { "name": "5feaf1324b10b84760e83f37", "type": "item", "attribute": "level1", "comparator": "Into", "value": "maderas" }, { "name": "5feaf13a4b10b84760e83f3a", "type": "payment", "attribute": "type", "comparator": "Into", "value": "card" } ] }, "condition": { "type": "composite", "name": "And", "condition": [ { "type": "basic", "name": "Exists", "parameter": { "key": "use-set", "value": "5feaf1324b10b84760e83f37" } }, { "type": "basic", "name": "Exists", "parameter": { "key": "use-set", "value": "5feaf13a4b10b84760e83f3a" } } ] }, "benefits": { "benefit": { "instance": "CouponBenefit", "parameter": [ { "key": "displayMessage", "value": "Entrega de un cupon para proxima compra" }, { "key": "printerMessage", "value": "Entrega de un cupon para proxima compra" }, { "key": "TLOGMessage", "value": "Entrega de un cupon para proxima compra" }, { "key": "applicationMethod", "value": "resume" }, { "key": "prorationMethod", "value": "proportional" }, { "key": "applicationPriceType", "value": "benefited-price" }, { "key": "name", "value": "5feaf1224b10b84760e83f34" }, { "key": "qty", "value": "1" }, { "key": "couponid", "value": "001" }, { "key": "infoPos", "value": "0" }, { "key": "recoveryValue", "value": "0" }, { "key": "recoveryType", "value": "" } ], "applied-elements": { "use-set": { "name": "5feaf1324b10b84760e83f37" } } } } }, { "operation": "U", "name": "Entrega de puntos llevando 2 furadeiras", "code": "3003", "sets": { "set": { "name": "5feaf18c4b10b84760e83f45", "type": "item", "attribute": "level3", "comparator": "Into", "value": "furadeiras" } }, "combo": { "combo-component": { "min": "2", "max": "2", "attribute": "qty", "use-set": "5feaf18c4b10b84760e83f45" } }, "benefits": { "benefit": { "instance": "PercentLoyaltyBenefit", "nro": "5feaf1cd4b10b84760e83f4a", "parameter": [ { "key": "displayMessage", "value": "Entrega de puntos llevando 2 furadeiras" }, { "key": "printerMessage", "value": "Entrega de puntos llevando 2 furadeiras" }, { "key": "TLOGMessage", "value": "Entrega de puntos llevando 2 furadeiras" }, { "key": "applicationMethod", "value": "resume" }, { "key": "prorationMethod", "value": "proportional" }, { "key": "applicationPriceType", "value": "benefited-price" }, { "key": "name", "value": "5feaf1794b10b84760e83f40" }, { "key": "percent", "value": "50" }, { "key": "type", "value": "3003" }, { "key": "recoveryValue", "value": "0" }, { "key": "recoveryType", "value": "" } ], "applied-elements": { "use-set": { "name": "5feaf18c4b10b84760e83f45" } } } } }, { "operation": "R", "code": "P2001", }, { "operation": "I", "name": "Descuento Fijo $ 20 en Marca Adidas", "code": "P1001", "sets": { "set": { "name": "5feaf0c44b10b84760e83f2f", "type": "item", "attribute": "brand", "comparator": "Into", "value": "adidas" } }, "condition": { "type": "basic", "name": "Exists", "parameter": { "key": "use-set", "value": "5feaf0c44b10b84760e83f2f" } }, "benefits": { "benefit": { "instance": "FixedDiscount", "nro": "5feaf0d04b10b84760e83f32", "parameter": [ { "key": "displayMessage", "value": "Descuento Fijo $ 20 en Marca Adidas" }, { "key": "printerMessage", "value": "Descuento Fijo $ 20 en Marca Adidas" }, { "key": "TLOGMessage", "value": "Descuento Fijo $ 20 en Marca Adidas" }, { "key": "applicationMethod", "value": "resume" }, { "key": "prorationMethod", "value": "proportional" }, { "key": "applicationPriceType", "value": "benefited-price" }, { "key": "name", "value": "5feaf0bc4b10b84760e83f2c" }, { "key": "amount", "value": "20" }, { "key": "unit", "value": "qty" }, { "key": "recoveryValue", "value": "0" }, { "key": "recoveryType", "value": "" } ], "applied-elements": { "use-set": { "name": "5feaf0c44b10b84760e83f2f" } } } } }, { "operation": "I", "name": "30% de descuento, llevando mas de 12 con prefijo 6447", "code": "0002", "sets": { "set": { "name": "5fe236da14b8fc698cfd63d7", "type": "item", "attribute": "level3", "comparator": "Into", "value": "6447" } }, "combo": { "combo-component": { "min": "12", "max": "12", "attribute": "qty", "use-set": "5fe236da14b8fc698cfd63d7" } }, "benefits": { "benefit": { "instance": "PercentageDiscount", "nro": "5fddeba114b8fc9724882991", "parameter": [ { "key": "displayMessage", "value": "30% de descuento, llevando mas de 12 con prefijo 6447" }, { "key": "printerMessage", "value": "30% de descuento, llevando mas de 12 con prefijo 6447" }, { "key": "TLOGMessage", "value": "30% de descuento, llevando mas de 12 con prefijo 6447" }, { "key": "applicationMethod", "value": "resume" }, { "key": "prorationMethod", "value": "proportional" }, { "key": "applicationPriceType", "value": "benefited-price" }, { "key": "name", "value": "5fddeb8414b8fc972488298a" }, { "key": "percent", "value": "30" }, { "key": "unit", "value": "qty" }, { "key": "recoveryValue", "value": "0" }, { "key": "recoveryType", "value": "" } ], "applied-elements": { "use-set": { "name": "5fe236da14b8fc698cfd63d7" } } } } } ] }
PARÁMETROS DE ENTRADA
Campo | Descripción |
---|---|
companyId | Código de la compañía |
promotions | Conjunto de promociones a actualizar, pueden ser nuevas, actualizaciones o promociones que deseamos inactivar. |
operation | I: Insertar / U: Actualizar / R: Eliminar |
name | Nombre de la promoción |
code | Código univoco de la promoción |
sets | Hace referencia a los conjuntos que definirán la condición y el beneficio de la promoción, por ejemplo:
|
conditions | Hace referencia a la combinación de conjuntos que forman parte de la condición para obtener el beneficio. Ejemplo: Conjunto 1 AND conjunto 2. Productos con Marca X y Familia Y Ejemplo 2: Conjunto 1 AND conjunto 3 Productos con marca X y Medio de pago VISA |
benefits | Hace referencia a los beneficios que se otorgarán si se cumplen las condiciones Los beneficios posibles son: NewPrice : Nuevo precio |
RESPUESTA DEL SERVICIO
Campo | Description |
---|---|
Code | El código de la promoción enviada |
ack | 0 si es correcto, diferente de 0 hubo un error. |
message | Descripción del mensaje de error |
Ejemplo invocando el servicio de importación masiva de promociones 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/import"
{ "companyId": "napse", "promotions": [ { "code": "P002", "sets": { "set": [ { "name": "5feaf1324b10b84760e83f37", "type": "item", "attribute": "level1", "comparator": "Into", "value": "maderas" }, { "name": "5feaf13a4b10b84760e83f3a", "type": "payment", "attribute": "type", "comparator": "Into", "value": "card" } ] }, "condition": { "type": "composite", "name": "And", "condition": [ { "type": "basic", "name": "Exists", "parameter": { "key": "use-set", "value": "5feaf1324b10b84760e83f37" } }, { "type": "basic", "name": "Exists", "parameter": { "key": "use-set", "value": "5feaf13a4b10b84760e83f3a" } } ] }, "benefits": { "benefit": { "instance": "CouponBenefit", "parameter": [ { "key": "displayMessage", "value": "Entrega de un cupon para proxima compra" }, { "key": "printerMessage", "value": "Entrega de un cupon para proxima compra" }, { "key": "TLOGMessage", "value": "Entrega de un cupon para proxima compra" }, { "key": "applicationMethod", "value": "resume" }, { "key": "prorationMethod", "value": "proportional" }, { "key": "applicationPriceType", "value": "benefited-price" }, { "key": "name", "value": "5feaf1224b10b84760e83f34" }, { "key": "qty", "value": "1" }, { "key": "couponid", "value": "001" }, { "key": "infoPos", "value": "0" }, { "key": "recoveryValue", "value": "0" }, { "key": "recoveryType", "value": "" } ], "applied-elements": { "use-set": { "name": "5feaf1324b10b84760e83f37" } } } } }, { "operation": "u", "name": "Entrega de puntos llevando 2 furadeiras", "code": "P003", "sets": { "set": { "name": "5feaf18c4b10b84760e83f45", "type": "item", "attribute": "level3", "comparator": "Into", "value": "furadeiras" } }, "combo": { "combo-component": { "min": "2", "max": "2", "attribute": "qty", "use-set": "5feaf18c4b10b84760e83f45" } }, "benefits": { "benefit": { "instance": "PercentLoyaltyBenefit", "nro": "5feaf1cd4b10b84760e83f4a", "parameter": [ { "key": "displayMessage", "value": "Entrega de puntos llevando 2 furadeiras" }, { "key": "printerMessage", "value": "Entrega de puntos llevando 2 furadeiras" }, { "key": "TLOGMessage", "value": "Entrega de puntos llevando 2 furadeiras" }, { "key": "applicationMethod", "value": "resume" }, { "key": "prorationMethod", "value": "proportional" }, { "key": "applicationPriceType", "value": "benefited-price" }, { "key": "name", "value": "5feaf1794b10b84760e83f40" }, { "key": "percent", "value": "50" }, { "key": "type", "value": "3003" }, { "key": "recoveryValue", "value": "0" }, { "key": "recoveryType", "value": "" } ], "applied-elements": { "use-set": { "name": "5feaf18c4b10b84760e83f45" } } } } } ] }
El cual recibirá una respuesta del tipo:
{ "promotions": [ { "code": "P2002", "ack": 0, "message": "" }, { "code": "P3003", "ack": 999, "message": "Benefit has not been informed" }, ] }
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 |
|
customer |
|
amount |
|
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. |
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 |