Manual de integración - Servicios
PROMO V7.2
Í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 los 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 Token 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" debe ser cambiado por la URL donde se encuentra la consola de Promo.
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".
Variable rabbitMq.date.UTC
Se agregó la nueva variable rabbitMq.date.UTC para que todos los mensajes que se devuelven a alguna de las consultas via Rest disponible en Promo, se informen con el formato del locale configurado en el servidor, que por default es GMT.
Servicios afectados:
- Clientes: http://localhost:8080/promo/api/rest/customer
- Estado de Limites del cliente: http://localhost:8080/promo/api/rest/limit/limitStatus
- Cupones: http://localhost:8080/promo/api/rest/coupon
- Elementos de Fidelidad: http://localhost:8080/promo/api/rest/card
- Mapas, promociones y promociones distribuidas: http://localhost:8080/promo/api/rest/promotions
- Próximo numero de elemento de fidelidad: http://localhost:8080/promo/api/rest/nextCardNumber
- Reporte de promociones: http://localhost:8080/promo/api/rest/reports/transaction/promotion
Nota
Tener en cuenta la configuración descripta en Información de Configuración
Consulta de Datos de Clientes
PROMO expone un servicio que permite consultar elementos de fidelidad y transacciones (ventas y devoluciones) a la BBDD utilizando el ID de cliente. Junto con los campos del cliente, también se devuelve un listado de Elementos de Fidelidad y Cupones, y sus últimas N transacciones..
Si no tiene elementos de Fidelidad, se devolverán los Elementos o Cupones vacíos; igualmente en el caso que no tengan transacciones, no traerá datos sobre las mismas.
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.
Este método accesible desde api/rest/customer es el encargado de devolver en formato JSON el customer o cliente solicitado por medio de la acción GET.
Tiene tres parámetros de ingreso:
Nombre | Valor |
|---|---|
companyId | El código de la compañía. String. Requerido. |
code | El código del cliente. String. No requerido. |
identificationType | El código del tipo de identificación del cliente (por ej, "dni"). String. No requerido. |
identifier | El nro. de identificación de cliente (por ej. nro de dni). String. No requerido. |
| lastSales | Con el valor configurado por el cliente, se habilita en la respuesta un listado con las últimas transacciones del cliente. No requerido |
Para buscar el cliente se debe enviar, o bien el parámetro "code", o bien el par de parámetros identifier e identificationType. En caso de no enviar ninguno, retorna [] con un mensaje de error en el log. Si envían code y el nuevo par de parámetros mencionados, buscará por code ya que tiene prioridad de búsqueda por el campo anterior en este caso particular.
El código debe ser exacto y solo se devolverá un resultado, si es que el cliente existe.
El campo “lastSales” es numérico, e indica la cantidad de transacciones que tiene un cliente. El usuario deberá ingresar la cantidad de transacciones que desea visualizar. Si pasan x números se retornan esas x últimas transacciones. Si pasan 0, o no lo pasan (vacío), no se retorna esa info.
Ejemplo, enviando a
http://{{SERVER}}:{{PORT}}/promo/api/rest/customer?companyId={{COMPANYID}}&identifier=12345&identificationType=dni
o bien http://{{SERVER}}:{{PORT}}/promo/api/rest/customer?companyId={{COMPANYID}}&code=1
o bien, para la consulta de las ultimas 10 transacciones asociadas al cliente, se debera enviar, por ej. http://URLPROMO:PUERTO/promo/api/rest/customer?code=0102909421&companyId=napse&lastSalesInfo=N
http://{server}:{port}/promo/api/rest/customer?code=12345&companyId={companyId}
se obtendría un resultado como el siguiente:
{
"_id": "5f5f8d16b51f3b3160021dac",
"code": "1",
"name": "JUAN",
"lastName": "Perez",
"gender": "h",
"birthDate": "1900-01-10T04:16:48Z",
"identificationType": "dni",
"identifier": "12345",
"identificationExpiration": "2050-10-10T03:00:00Z",
"nacionality": "arg",
"email": "",
"customerType": "EMPLEADO",
"address": "calle 1",
"addressCountry": "arg",
"addressState": "bsas",
"addressCity": "tig",
"addressPostalCode": "1",
"phone": "1555555555",
"isActive": true,
"segments": "",
"companyId": "napse",
"creationDate": "2020-09-14T15:32:38Z",
"cards": [
{
"_id": "5f5fa94db51f3b5b0c2cedc9",
"amount": 0.0,
"code": "2222000000013",
"customerId": "1",
"validFrom": "2020-08-14T03:00:00Z",
"type": "tipo2",
"validTo": "2021-07-14T03:00:00Z",
"status": "DISABLED",
"companyId": "napse",
"created": "2020-09-14T17:33:01Z",
"isConsumed": false,
"version": 1,
"typeName": "tipo2"
},
{
"_id": "5f5f8d88b51f3b3160021db1",
"amount": 0.0,
"code": "1111000000010",
"customerId": "1",
"type": "tipo1",
"status": "ENABLED",
"companyId": "napse",
"created": "2020-09-14T15:34:32Z",
"isConsumed": false,
"version": 2,
"activation": "2020-09-14T15:34:33Z",
"typeName": "tipo1"
},
{
"_id": "5f5f8d88b51f3b3160021db2",
"amount": 0.0,
"code": "1111000000011",
"customerId": "1",
"type": "tipo1",
"status": "ENABLED",
"companyId": "napse",
"created": "2020-09-14T15:34:32Z",
"isConsumed": false,
"version": 2,
"activation": "2020-09-14T15:34:34Z",
"typeName": "tipo1"
},
{
"_id": "5f5f8e3ab51f3b3160021db8",
"amount": 0.0,
"code": "2222000000012",
"customerId": "1",
"validFrom": "2020-08-14T03:00:00Z",
"type": "tipo2",
"validTo": "2021-07-14T03:00:00Z",
"status": "ENABLED",
"companyId": "napse",
"created": "2020-09-14T15:37:30Z",
"isConsumed": false,
"version": 2,
"activation": "2020-09-14T15:37:30Z",
"typeName": "tipo2"
}
],
"coupons": []
}
En caso de que el cliente no exista en la base la respuesta se devolverá vacía.-
La respuesta por cada elemento incluido en el atributo lastSales , tiene la siguiente estructura (estos datos se sumaran, en caso de corresponder, a los datos que ya se informan de tarjetas y cupones asociados al cliente):
Atributo | Descripción |
|---|---|
transactionId | Código de la transacción |
transactionType | Tipo de la transacción |
storeCode | Código de la tienda |
terminalCode | Código de terminal |
customerId | Código de cliente |
customerType | El código del tipo de cliente |
mapVersion | El nro. del mapa evaluado al realizar esta transacción |
offline | Con valor true determina si fué originada offline, y false determina que fué originada online. |
date | Fecha de la transacción. Formato equivalente al de la fecha de creación del cliente (campo creationDate). Por ej. 2021-06-24T20:34:39Z |
transactionStatus | El estado en que se encuentra la transacción actualmente. |
itemsTotalQuantity | Cantidad de unidades de productos vendidos al cliente. En el caso de venta por magnitud, al no enviar qty, suma un 1; por ej. vendiendo los siguientes items, daría como resultado "itemsTotalQuantity": 2.0 : <item-add code="1234" magnitude="1.5" seq="1" <otros atributos>/> <item-add code="2222" magnitude="5.5" seq="2" <otros atributos>/> |
summaryValues | Representan el resumen de valores de la transacción. Objeto que contiene cuatro atributos. Detalle a continuación. |
summaryValues.subtotal | Indica el subtotal de la transacción sin descuentos ni recargos |
summaryValues.discount | Indica el monto de los descuentos aplicados en la transacción |
summaryValues.surcharge | Indica el monto de los recargos aplicados en la transacción |
summaryValues.total | Indica el total de la transacción con descuentos y recargos aplicados |
payments | Representan los pagos presentados en la transacción. Es un listado de objetos que contienen tres atributos. Detalle a continuación. |
payments.type | El tipo del medio de pago |
El id del medio de pago | |
payments.amount | El monto del pago realizado con ese medio. |
loyaltyCards | Representan un detalle de los elementos de fidelidad presentadas en la transacción. Es un listado de objetos que contienen cinco atributos. Detalle a continuación. |
El código de elemento del elemento de fidelidad | |
loyaltyCards.obtainedPoints | Puntos obtenidos durante la transacción |
loyaltyCards.benefitedByPromotion | true en caso de haber obtenido puntos. |
loyaltyCards.redeemedPoints | Puntos redimidos durante la transacción |
loyaltyCards.redeemedByPromotion | true en caso de haberse redimido puntos. |
coupons | Representan un detalle de la cantidad de cupones emitidos y consumidos en la transacción. Es un objeto que contiene dos atributos. Detalle a continuación. |
coupons.obtained | Cantidad de cupones obtenidos. |
coupons.redeemed | Cantidad de cupones redimidos. |
Ejemplo
{
"_id": "60824eeecff31c4138ebf73d",
"code": "0102909421",
"identifier": "0102909421",
"email": "-",
"name": "john promo",
"lastName": "-",
"identificationType": "c",
"customerType": "c",
"creationDate": "2021-04-23T04:37:02Z",
"isActive": true,
"companyId": "napse",
"cards": [],
"coupons": [],
"lastSales": [
{
"transactionId": "napse_1_1_20210624173439",
"transactionType": "SALE",
"storeCode": "1",
"terminalCode": "1",
"customerId": "0102909421",
"customerType": "c",
"mapVersion": 5,
"offline": false,
"date": "2021-06-24T20:34:39Z",
"transactionStatus": "COMMIT",
"itemsTotalQuantity": 33.0,
"summaryValues": {
"subtotal": 2217.0,
"discount": 353.0,
"surcharge": 0.0,
"total": 1864.0
},
"payments": [
{
"type": "1",
"id": "1",
"amount": 100.25
},
{
"type": "2",
"id": "2",
"amount": 200.5
}
],
"loyaltyCards": [
{
"id": "1111000000010",
"obtainedPoints": 100.0,
"benefitedByPromotion": true,
"redeemedPoints": 3.0,
"redeemedByPromotion": true
}
],
"coupons": {
"obtained": 10,
"redeemed": 2
}
}
]
}
Jobs a ejecutar
Tener en cuenta que este servicio rest, en la sección lastSales, se alimenta de las colecciones transaction, transactionFlatten, y viewCustomer. Para que esté la info disponible es necesario que se hayan procesado los jobs: sts.console.job.LoyaltyJob (Finalización de transacciones) y sts.console.job.TransactionFlattenJob (Aplanado de Transacciones).
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=napse&code=85001"
Obteniéndose la siguiente respuesta:
Ejemplo {
"customerId": "85001",
"companyId": "napse",
"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": "napse",
"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 del elemento de fidelidad 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 |
| offset | Numérico | Permite navegar dentro del rango. Se usa en conjunto con el parámetro limit. Por ej: Se quiere navegar los primeros 10 registros, configurar offset=1 y limit=10. Se quiere ver los 10 siguientes, configurar offset=11 y limit 10. Cuando ya no hay más registros va a dar vacío. |
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 Estado de Cupón
PROMO expone un servicio que permite consultar el estado de cupones a la BBDD utilizando como parámetros el Id de cliente, Id de la compañía, el tipo de acción y el rango de fechas (Fecha_desde y Fecha_hasta) y como respuesta se obtienen los movimientos asociados a dicho cupón.
La Url para acceder al servicio es:
http://[server]:[port]/promo/api/rest/couponStatements
Los parámetros de entrada de la consulta son:
| Propiedad | Tipo de Dato | Descripción |
|---|---|---|
| customerId | Alfanumérico | Identificador único del cliente |
| companyId | Alfanumérico | Código de la compañía |
| actionType | string | Tipo de operación que se quiere consultar. Si no se especifica, Por defecto son todas las operaciones. Los valores disponibles son: CREATE, REDEEM, VOID |
| dateFrom | alfanumérico | Fecha de Inicio en formato YYYYMMDD. |
| dateTo | alfanumérico | Fecha de Final en formato YYYYMMDD |
Ej, se solicitan los cupones generados para el cliente Id = 1
y como respuesta se obtienen los datos del cupón asociado al cliente y su estado.
Respuesta:
[
{
"transactionId": "napse_napse_1_20220830120000",
"action": "Emisión",
"terminal": "1",
"couponType": "cimp",
"customerId": "1",
"amount": "-",
"store": "napse",
"datetime": "30/08/2022 11:08",
"couponCode": "116pse0018828"
},
{
"transactionId": "napse_napse_1_20220830120000",
"action": "Emisión",
"terminal": "1",
"couponType": "cimp",
"customerId": "1",
"amount": "-",
"store": "napse",
"datetime": "30/08/2022 11:08",
"couponCode": "116pse0015292"
}
]
Servicio de Consulta de Elementos de Fidelidad
PROMO expone un servicio que permite consultar elementos de fidelidad a la BBDD utilizando solo su número de elemento y como respuesta se obtienen los datos del elemento en cuestión y los movimientos asociados a dicho elemento. 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 del elemento que 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 elementos definidos. *ver ejemplo mas abajo |
| cardAction | 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: CHARGE, RECHARGE, AMOUNT_UPDATE, SALE, EXTENDED_POINTS |
| timeFrom | Numérico | Hora de Inicio en formato HHmm |
| timeTo | Numérico | Hora de final en formato HHmm |
| offset | Numérico | Permite navegar dentro del rango. Se usa en conjunto con el parámetro limit. Por ej: Se quiere navegar los primeros 10 registros, configurar offset=1 y limit=10. Se quiere ver los 10 siguientes, configurar offset=11 y limit 10. Cuando ya no hay más registros va a dar vacío. |
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 un elemento, se retornarán los datos y movimientos asociados a dicha elemento, pudiéndose opcionalmente especificar un rango de fechas y un limite en la cantidad de movimientos.
Si no se especifica el elemento, se debe especificar un rango de fechas y se retornaran todos los movimientos de los elementos en ese rango, incluyendo en ese caso el numero del elemento que se trata.
Para el caso de información de elementos, el Formato de la Respuesta será (JSON):
Propiedad | Tipo de dato | Descripción | ||||||
| _id* | Alfanumérico | Uso Interno | ||||||
| amount* | Numérico | Saldo Actual del elemento. | ||||||
code* | Alfanumérico | Número del Elemento | ||||||
Created* | Alfanumérico | Fecha de Creacion en formato ISODATE | ||||||
| customerId | Alfanumérico | Id de cliente asocido al elemento | ||||||
| activation | Numérico | Fecha de activacion | ||||||
isConsumed* | Booleano | Si ha sido consumida o no | ||||||
| status* | Alfanumérico | Estado actual del elemento | ||||||
| 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 Elemento | ||||||
| typeName | Alfanumérico | Nombre del tipo de elemento | ||||||
| amountPrev | Numérico | monto previo | ||||||
| version* | Numérico | Uso Interno | ||||||
| cardHistory | Colección | Conjunto de registros que corresponden a cada movimiento del elemento, con:
Conjunto de refistros que corresponden a la promocion que aplica al movimiento del elemento
|
- Estos datos son retornados solo si se consulta por un código de elemento determinado.
Para el caso de Tipos de elemento:
Propiedad | Tipo de dato | Descripción |
amountChargeLimit | Numérico | Limite de carga |
cardNumberLength | Numérico | Longitud del número del elemento |
cardTypePrefixRange | Array | definicion de rangos de prefijos para ese elemento. |
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 nominado |
isRechargeable | Booleano | True is es recargable |
name | Alfanumérico | Nombre del tipo |
EJEMPLO 1: se solicitan los datos del elemento 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": "napse",
"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": "napse_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": "napse_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 Elementos
Cuando se especifica el parámetro "isTypes" se retornarán solamente los tipos de elemento 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"
}
]
}
Estado de puntos de Elementos de Fidelidad
PROMO expone un servicio que permite consultar el estado de los puntos de un elemento de fidelidad a la BBDD utilizando solo su número del elemento y como respuesta se obtienen los datos del estado de los puntos del elemento en cuestión y los movimientos asociados a dicha elemento. Los datos que se devuelven son: número y tipo de elemento de fidelidad,Id de transacción, acción realizada, tienda, fecha de la transacción, cantidad de puntos involucrados en la acción y código del cliente.
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/statementPoints
Los parámetros de entrada de la consulta son:
| Propiedad | Tipo de Dato | Descripción |
|---|---|---|
| companyId | Alfanumérico | Código de la compañía |
ToDate | Numérico | Fecha de Final en formato YYYYMMDD |
fromDate | Numérico | Fecha de Inicio en formato YYYYMMDD |
customerId | Alfanumérico | Identificador único del cliente |
isConsumed* | Booleano | Si ha sido consumida o no |
Todos estos datos son requeridos; cuando falte alguno de ellos la aplicación enviará un mensaje como el ejemplo:
El rango de fechas no puede ser mayor a un mes:
El Formato de la Respuesta será (JSON):
| Propiedad | Tipo de Dato | Descripción |
|---|---|---|
| cardNumber | Alfanumérico | Número del elemento de fidelidad asociado al cliente |
| cardTypeCode | Alfanumérico | identificador único de tipo de elemento de fidelidad |
| transactionId | Numérico | Número de transacción |
| action | Alfanumérico | Acción llevada a cabo (otorga, consumo) |
| storeCode | Alfanumérico | Identificador único de Tienda donde se llevó a cabo la transacción |
| date | Numérico | Fecha y hora de la transacción |
| amount | Numérico | Cant. de puntos participantes en la transacción |
| customerCode | Alfanumérico | Identificador único del cliente |
| terminalCode | Alfanumérico | Terminal donde se realizó la transacción |
La respuesta al Ej 1 es:
[
{
"cardNumber": "6000011014",
"cardTypeCode": "10",
"transactionId": "napse_napse_1_20220831120500",
"action": "Consumo",
"storeCode": "napse",
"date": "31/08/2022 12:05",
"amount": 200.0,
"customerCode": "1",
"terminalCode": "1"
}
]
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 Promociones Disponibles
PROMO expone un servicio que permite consultar promociones disponibles utilizando un filtro por compañía y versión de mapa (obligatorios) y el código de Promoción como parámetro de filtro opcionales.
Para utilizar 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/promotionAvailable
La siguiente figura muestra el contenido del request de ejemplo:
Los parámetros de entrada son:
| Propiedad | Tipo de Dato | Descripción |
|---|---|---|
| mapVersion | Alfanumérico | Versión de Mapa que contiene la promocion |
| companyId | Alfanumérico | Identificador unico de la empresa |
| promotionCode | Alfanumérico | codigo de la promocion que forma parte del mapa |
El código de promocion no es requerido.
Los parámetros de salida son:
| Propiedad | Tipo de Dato | Descripción |
|---|---|---|
| mapVersion | Alfanumérico | Versión del mapa requerido |
| code | Alfanumérico | código de la promoción que está contenida en el mapa |
| name | String | nombre de la promoción |
| conditionSimple | String | condición simple de la promoción |
| conditionCombo | String | condición combo de la promoción |
| conditionDate | Alfanumérico | condición de fechas de la promoción |
| benefitTypeDescription | String | Descripción del tipo de beneficio de la promoción |
| benefitClassDescription | String | Descripción de la clase de beneficio de la promoción |
| benefit | String | Descripción del beneficio de la promoción |
la respuesta es el Json:
[
{
"mapVersion": "100",
"code": "47483",
"name": "Promo Paga con ptos.",
"conditionSimple": "Productos con Codigo (SKU) IGUAL a 3553",
"conditionCombo": "",
"conditionDate": "",
"benefitTypeDescription": "<p>1.- Monetario</p><br/>",
"benefitClassDescription": "<p>1.- Canje de Puntos</p><br/>",
"benefit": "<p>1.- Productos con Codigo (SKU) IGUAL a 3553. Tipo de Elemento de Fidelidad 10. Factor $1 = x Puntos 1. Valor de Recupero 0. Tipo de Recupero -. Prorratear entre Participantes false. Balance -</p> "
}
]
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 Prorrateo entre participantes
Cuando un beneficio, tenga tildada la opción de "Prorratear entre Participantes", el monto del descuento a otorgar será distribuido proporcionalmente entre los ítems participantes de la promoción.
Ejemplo de mensajería donde se visualiza la distribucion del descuento entre los participantes.
<?xml version="1.0" encoding="UTF-8"?> <message companyId="napse" store="1" terminal="1" date-time="2021-03-01 10:35:22" init-tck="true" messageId="1" void-trx="false" response="true" limitBalances="true" status="sales" evaluate="true" map-version="7" tckpath="Y" suggest="true"> <item-add seq="1" qty="1" code="123" level1="1121" magnitude="0" brand="Kumho" xprice="150" unitprice="150" /> <item-add seq="2" qty="1" code="456" level1="1121" magnitude="0" brand="Kumho" xprice="90" unitprice="90" /> <item-add seq="4" qty="1" code="789" level1="1121" magnitude="0" brand="Kumho" xprice="75" unitprice="75" /> </message>
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<message ack="0" companyId="napse" engine="7.0.0-SNAPSHOT#78" mapversion="7" messageId="1" store="1" terminal="1">
<optional>
<promo id="Prorratear entre Participantes" nro="603afe841082e836908173d1">
<benefit TLOGMessage="Prorratear entre Participantes" account="" applicationMethod="resume" baseAmount="75.0000" benefitType="PercentageDiscount" discountPercentage="100.0000" displayMessage="Prorratear entre Participantes" name="603afe841082e836908173d1" nro="603afed81082e836908173e1" order="1" printerMessage="Prorratear entre Participantes" prorateBCP="true" prorationMethod="PROPORTIONAL" unit="qty">
<apply>
<item magnitude="0.000" qty="1.000" seq="1" value="35.71" valueWithTaxes="150.00" xprice="150.00"/>
<item magnitude="0.000" qty="1.000" seq="2" value="21.43" valueWithTaxes="90.00" xprice="90.00"/>
<item magnitude="0.000" qty="1.000" seq="4" value="17.86" valueWithTaxes="75.00" xprice="75.00"/>
</apply>
</benefit>
</promo>
</optional>
</message>
Servicio Próximo Número de elemento de fidelidad
PROMO expone un servicio que permite consultar, para un determinado tipo de elemento cual es el próximo número de elemento disponible inactivo y sin cliente asociado. Por medio de este servicio de consulta, el POS podrá conocer el número del "siguiente elemento inactivo y sin cliente asociado" para ser asignada a un cliente desde línea de cajas. Promo devolverá el número de elemento y el POS lo asociará al cliente y le reenviará (LoyaltyAssign) el número y tipo de elemento, más los datos del cliente para que se active y asigne el elemento.
Cuando no se disponga de mas elementoss inactivos y sin cliente asociado en la base de datos para el tipo de elemento consultado, se devolverá el mensaje de error indicando que no se cuenta con mas elementos disponibles para ser asociadas.
Considerar que el tipo de nominación que utilizará es "Asociación por canal de Ventas" y los elementos deberán darse de alta vía archivo.
En el archivo de alta masiva solo se informará el nro. de elemento y el Tipo.
Al darse de alta los elementos, estas quedarán en estado INACTIVO.
La activación del elemento y asignación de cliente se debe realizar por medio del "Canal de Ventas".
Para ello, una vez dadas de alta los elementos de forma masiva, desde el POS, cuando se desee dar de alta un cliente y asignarle una cuenta "prepaga" (Monedero), se enviará el mensaje de consulta de próximo Elemento (NextCardNumber). Promo informará a este mensaje el número del próximo elemento inactivo y sin cliente asignado, disponible.
Luego el POS, enviará un mensaje de asociación (LoyaltyAssign) del cliente al elemento, quedando este último activo y con el cliente informado asociado al elemento.
Servicio REST
Para los ejemplos se realizaron las consultas de elementos utilizando la herramienta "PostMan" de Chrome. Deberá obtenerse un nuevo Token (cUrl), y luego podrá realizarse la consulta de próximo número de elemento
(PostMan).
El único método aceptado para realizar este pedido es POST.
Autenticación:
Para poder acceder al servicio rest se deberá solicitar un token de autorización que será utilizado posteriormente en el encabezado de la llamada al servicio. Los pasos para solicitar un token son los siguientes:
Una vez instalado el comando curl, ejecutar:
curl -v -X POST -u my-client: -d "grant_type=password" -d "username=<userName>" -d "password=<password>" -d "scope=read" http://<servername>:<port>/promo/oauth/token
Campo | Descripción |
<userName> | usuario (solicitado por Promo) |
<password> | password (solicitado por Promo) |
nombre o ip donde este alojado Promo | |
<port> | puerto http donde este corriendo Promo. |
Por 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
El token de acceso a utilizar está representado por el valor de access_token, que en este ejemplo corresponde a dcb8a705-8b04-409f-98b7-3cd93fc7be3f. Este token deberá ser utilizado posteriormente en la cabecera del servicio rest.
MENSAJE DE CONSULTA
El cuerpo del mensaje deberá ser un xml. A continuación se detallarán las posibles peticiones y sus respuestas involucradas.
REQUERIMIENTO
<promoCoreRequest>
<operation>NextCardNumber</operation>
<params>
<type="555">
</params>
</promoCoreRequest>
RESPUESTA OK
<promoCoreResponse>
<ack>0</ack>
<message>Id:"555000002200002"</message>
</promoCoreResponse>
RESPUESTA NO OK
<promoCoreResponse>
<ack>9503</ack>
<message>No se encontró el Tipo de tarjeta loyalty</message>
</promoCoreResponse>
Extensión en consulta de Elemento con el loyaltyValidation
Actualmente, desde el punto de venta puede enviarse una consulta de elemento utilizando el status LoyaltyValidation, en donde se informa el Id del elemento y el tipo, y la consola retorna todos los datos referentes al elemento consultada.
En caso de enviar solo el Type del elemento en una consulta de LoyaltyValidation, se devolverá el próximo número del elemento inactivo y sin cliente asociado disponible.
Por ejemplo, el último número de elemento activo para el tipo "aaa" es el 333000000000000007, al realizar la consulta solo con el tipo de elemento, Promo devolverá el id de tarjeta 333000000000000008 que corresponde al próximo número de elemento inactivo y sin cliente disponible.
<?xml version="1.0" encoding="UTF-8"?> <message companyId="napse" store="1" terminal="1" date-time="2018-07-18 10:16:00" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyValidation" evaluate="true" tckpath="Y" suggest="true"> <loyaltycard-add seq="5" type="2" /> </message>
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="napse" engine="6.2.0" mapversion="0" messageId="1" store="1" terminal="1" transaction="C2_1_1_20180718135406"> <loyalty> <loyaltycards> <loyaltycard ack="0" id="2220000000000019" type="2"/> </loyaltycards> <coupons/> <errors/> <customers/> </loyalty> </message>
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).
http://localhost:8080/promo/api/rest/reports/transaction/promotion?companyId=napse&limit=50000&offset=0&dateFrom=20210512&dateTo=20210519
Los parámetros de entrada de la consulta son:
Propiedad | Tipo de dato | Descripción |
| companyId | Alfanumérico | Código de la compañía |
limit | Numérico | Cantidad de registros de movimientos a retornar con un máximo 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 Transacción: 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) |
Ejemplo de parámetros de entrada de la consulta en Postman:
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 información adicional |
{
"records:": "[{\"transactionId\":\"napse_Tienda1_1_20210519110000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Descuento porcentaje\",\"itemCode\":\"456\",\"discountApply\":500.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"19/05/2021 11:00\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo limite1\",\"store\":\"Tienda1\",\"subTotal\":500.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210519100000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Descuento porcentaje\",\"itemCode\":\"456\",\"discountApply\":500.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"19/05/2021 10:00\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo limite1\",\"store\":\"Tienda1\",\"subTotal\":500.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210519091000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Descuento porcentaje\",\"itemCode\":\"456\",\"discountApply\":500.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"19/05/2021 09:10\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo limite1\",\"store\":\"Tienda1\",\"subTotal\":500.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210517091000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"555\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"17/05/2021 09:10\",\"transactionType\":\"Devolución\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo EMITE CUPON Impreso\",\"store\":\"Tienda1\",\"subTotal\":1000.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210517090000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"555\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"17/05/2021 09:00\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo EMITE CUPON Impreso\",\"store\":\"Tienda1\",\"subTotal\":1000.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210513100000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"555\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"13/05/2021 10:00\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo EMITE CUPON Impreso\",\"store\":\"Tienda1\",\"subTotal\":1000.0,\"conditionTimeRange\":\"Indefinida\"}]",
"header": {
"total": 6,
"offset": 0,
"limit": 50000
}
}
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 fue realizada en modo offline |
| unitPrice | Numérico | Precio unitario del producto |
benefitClass | Alfanumérico | Clase de beneficio |
itemCode | Alfanumérico | Código de Producto |
discountApply | Numérico | Descuento Aplicado |
| deploymentChannels | Alfanumérico | Canal de Publicación |
| date | Alfanumérico | Fecha de la transacción |
| transactionType | Alfanumérico | Tipo de Transacción |
| campaign | Alfanumérico | Campaña |
| quantity | Numérico | Cantidad del Producto |
| promotionCode | Alfanumérico | Código de Promoción |
| promotionName | Alfanumérico | Nombre de la Promoción |
| store | Alfanumérico | Tienda |
| subTotal | Numérico | Subtotal de la transacción |
| conditionTimeRange | Alfanumérico | Condición 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 información sirve para mantener una paginación como sucede en pantalla pero a nivel servicio. Digamos:
Primer consulta: offset: 0, limit: 25 → retorna la primer página 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 podrá ir pidiendo paginas hasta llegar a offset: 475, limit 25.
También se podría realizar un paginado de a 100 registros por consulta, etc. (limit: 100).
EJEMPLO 1:
Solicitamos un reporte de Promociones para la compañía myCompany, entre el 21/11/2020 y el 04/12/2020, limitado a 25 registros a partir del 500 (esto es el equivalente a la página 21 en pantalla), para el código de Promoción 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
}
}
|
.
Transaccional de Límite vía REST
Para acceder al informe transaccional vía Rest se debe acceder al request:
http://localhost:8180/promo/api/rest/limit/statements?companyId=exito&mapVersion=135&limit=20&offset=0&dateFrom=2018-01-01&dateTo=2021-12-02&promotionCode=12182
Localhost: dependerá de la versión con la cual se está trabajando
CompanyId: la compañía con la cual se está trabajando
N° de mapa: corres´pondiente a la promocion en la cual se distribuyó
ID de la promoción: identificador de la promoción que se está considerando y que debe poseer límites.
En Postman:
Si, en cambio, la consulta es por companyId y N° de mapa:
Cuando un mapa no se encuentre activo, debe enviar un mensaje de error:
Si el código de la promoción consultada no existe en el mapa informado.; en POSTMAN se observará el siguiente mensaje:
Si en cambio, la compañía no existe, no lo mostrará:
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 .......}]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": "napse",
"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 ítems para no afectar la performance y que las respuestas puedan ser procesadas.
- En caso de error se informaran los registros erróneos pero los que han resultado correctos serán 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 líneas con error y las correctas. Los resultados podrán visualizarse en la consola en la pantalla de Monitor de Importación.
- El proceso utiliza semáforos para evitar la concurrencia de clientes que pretendan procesar en paralelo ya que implica posibilidad de errores en las validaciones.
CATALOGO DE ELEMENTO DE FIDELIDAD
Para la importacion de elementos de fidelidad por medio del servicio Rest, debera considerarse el siguiete formato general:
{
"companyId": "napse",
"catalog":"Card",
"params":[
"param1":"param1value",
"paramN":"paramNvalue"
],
"items": [
{.... primer item .......},
{.... otro item .......},
{.... otro item .......},
{.... otro item .......},
{.... otro item .......},
]
}
(Ver detalles del request en la sección anterior "Importacion de Catálogos")
En la sección "items" deberán indicarse la colección de objetos dependientes de cada catálogo, en este caso, el de elementos, "Card"
| Campo | Valor |
|---|---|
code | El código del elemento. |
type | El código del tipo de elemento. |
validFrom | Fecha de inicio de vigencia (considerar los tipos de vigencia existentes en el tipo de elemento relacionado). Formato año-mes-día, 4 dígitos, 2 dígitos, 2 dígitos; por ej. "2020-05-14" |
validTo | Fecha de fin de vigencia (considerar los tipos de vigencia existentes en el tipo de elemento relacionado). Formato año-mes-día, 4 dígitos, 2 dígitos, 2 dígitos; por ej. "2020-05-14" |
cvv | Número cvv. |
customerId | El código de cliente al cual pertenece el elemento (considerar el campo nominado del tipo de elemento). Alfanumérico. |
amount | El monto del elemento (considerar el tipo de precarga del tipo del elemento). Numérico con decimales. |
status | El estado del elemento. Los valores posibles para el status son: ENABLED (elemento activo), DISABLED (elemento inactivo), CANCELED (elemento cancelado). |
operation | La operación a realizar sobre el elemento. Los valores posibles son: I: Inserción / U: Actualización / R: Eliminación |
Un mensaje de ejemplo para el uso de este servicio
Realizar un POST a http://URLPROMO:PUERTO/promo/api/rest/catalogs (por ej. http://promo.com:8080/promo/api/rest/catalogs)
En el siguiente mensaje el campo companyId contiene el código de la compañía, que en este ejemplo es napse.
El valor del campo catalog siempre debe ser Card, así como el valor de params, debe ser siempre una lista vacía.
En el primer item, se dará de alta el elemento código 4567000000000 con estado activo. Para este caso el campo operation tiene el valor de I.
En el segundo item, se actualizará el elemento código 3456000000001 asignándole el cliente 2233 e inactivándolo. Esta operación está representada con el campo operation en U.
En el tercer item, se cancelará la tarjeta código 3456000000002. La cancelación se especifica con el valor del campo operation en R.
{
"companyId": "napse",
"catalog": "Card",
"params": [],
"items": [
{
"code": "4567000000000",
"type": "tipo1",
"validFrom": "",
"validTo": "",
"cvv": "123",
"customerId": "1122",
"amount": 50,
"status": "ENABLED",
"operation": "I"
},
{
"code": "3456000000001",
"type": "tipo2",
"validFrom": "",
"validTo": "",
"cvv": "234",
"customerId": "2233",
"amount": 45.5,
"status": "DISABLED",
"operation": "U"
},
{
"code": "3456000000002",
"type": "tipo2",
"validFrom": "",
"validTo": "",
"cvv": "345",
"customerId": "2233",
"amount": 35.5,
"status": "ENABLED",
"operation": "R"
}
]
}
Desde allí podrá realizarse el seguimiento de los registros enviados y poder reprocesarlos en caso de ser necesario.
Vista de proceso satisfactorio
Vista de proceso con error.
CATALOGO DE CLIENTES
Borrado de atributos en catálogos en PROMO
A partir de esta versión Promo permite borrar de ciertos catálogos, algunos atributos con solo enviar el id de dicho atributo que se le envíe en el post, utilizando el servicio Rest.
No es necesario enviar el id y la descripción. Con enviar sólo el código se puede realizar el borrado.
Los catálogos que cumplen con este criterio son:
Catálogos dinámicos,
"CatalogAdditionalField00", "CatalogAdditionalField01", "CatalogAdditionalField02", "CatalogAdditionalField03",
"CatalogAdditionalField04", "CatalogAdditionalField05", "CatalogAdditionalField06", "CatalogAdditionalField07",
"CatalogAdditionalField08", "CatalogAdditionalField09", "CatalogAdditionalField10", "CatalogAdditionalField11",
"CatalogAdditionalField12", "CatalogAdditionalField13", "CatalogAdditionalField14", "CatalogAdditionalField15",
"CatalogAdditionalField16", "CatalogAdditionalField17", "CatalogAdditionalField18", "CatalogAdditionalField19",
"CatalogBrand", "CatalogChannel", "CatalogCreditCampaignCode",
"CatalogCurrencyCode", "CatalogCustomerType", "CatalogDepartment", "CatalogEventTransaction",
"CatalogEventTransactionType", "CatalogFamily", "CatalogFormat",
"CatalogPaymentBank", "CatalogPaymentCode", "CatalogPaymentPrefix", "CatalogItem", "CatalogSubCategory",
"CatalogPaymentType", "CatalogPocket", "CatalogProductBarcode", "CatalogProductCode", "CatalogCustomer",
"CatalogProfileCode", "CatalogStoreChain", "CatalogStore", "CatalogSubZone", "CatalogSupplier", "CatalogZone",
"CatalogGender", "CatalogIdType", "CatalogContractPriceList", "CatalogCountry", "CatalogCategory",
De los anteriores, estos no admiten repetición de registros:
"CatalogGender", "CatalogIdType", "CatalogContractPriceList", "CatalogCountry",
"CatalogCustomerType", "CatalogItem", "CatalogCustomer"
Y estos no son código-nombre pero igual cumplirán con el requerimiento porque su clave primaria incluye sólamente companyId y code
"CatalogItem", "CatalogCustomer", "CatalogSubCategory"
"CatalogCategory"
Estos catálogos no fueron afectados:
"Card", "CatalogCity" ,"CatalogState", "CatalogInfoFinancial", "CatalogItemStock" (si bien tiene clave primaria companyId-code, no tiene un campo name), "CatalogExtendWarranty" (idem anterior), "CatalogRedeemBenefit"
Se pueden presentar los siguientes casos:
La Url es:
http://{{SERVER}}:{{PORT}}/promo/api/rest/catalogs
- Se envía sólo el código del producto:
En la consola:
Se envia el mensaje por Postman:
{
"companyId" = "napse",
"catalog" = "CatalogChannel",
"params":[],
"items": [
{
"code"= "1",
"operacion" = "D"
}
]
}
Luego de ejecutarse el job Importación de Entidades , se observa que en la consola se ha eliminado el primer registro que coincidia con el sódigo solicitado:
2. Se envía sólo el código y nombre del producto:
{
"companyId" = "napse",
"catalog" = "CatalogChannel",
"params":[],
"items": [
{
"code"= "1",
"name"= "CATALOGCHANNEL2",
"operacion" = "D"
}
]
}
En la consola, se observa que se eliminó el registro con código y nombre solicitado:
Consola: Servicio REST de Eliminación de Datos del Cliente y sus datos de fidelidad
Este servicio rest permite eliminar al cliente y todos los datos de fidelidad relacionados con este si se desea.
| Campo | Valor |
|---|---|
companyId | Id de la compañía (requerido) |
| params | para dejarlo extensible, es una lista vacía |
| code | Código del cliente (requerido) |
| operation | D: es borrado parcial asignará rayita ( - ) en los datos del cliente (excepto el código, que se seguirá mostrando) o R: borrado total incluye fidelidad y borra también el código del cliente. |
Datos para el request
Método | Url base |
|---|---|
| DELETE | http://URLPROMO:PUERTO/promo/api/rest/customer/delete Por ej. http://promo.com:8080/promo/api/rest/customer/delete |
Servicio rest para eliminar total o parcialmente al cliente y si se desea sus datos de fidelidad:
{
"companyId": "<companyId>",
"params": [],
"items": [
{
"code": "<codigoCliente1>",
"operation": "D"
}
]
}
Se puede enviar varios clientes por vez.
{
"status": "200",
"description": "Cliente (s) Eliminado (s)",
"detail": [
{
"result": "ok",
"detail": "Cliente (s) Eliminado (s)"
}
]
}
Ejemplo:
Ejemplo:
En la consola de Promo, en la pantalla "Gestión de clientes" antes de ejecutar el Servicio REST de eliminación de datos del cliente y sus datos de fidelidad los clientes se visualizan de la siguiente forma:
Luego de ejecutar el Servicio REST se verá de la siguiente forma:
En la vista Registro de auditoría se detallará la eliminación parcial:
y la eliminación total:
Se observará que en la consola se ha eliminado el primer registro que encontró con los datos solicitados:
Servicio de Importación Masiva de Promociones vía REST
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
Datos para el request
Método | Url base |
|---|---|
| POST | http://URLPROMO:PUERTO/promo/api/rest/promotion/import Por ej. http://promo.com:8080/promo/api/rest/promotion/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": "promo import10",
"code": "promo import10",
"promotionType": "tipo 1",
"promotionSubType": "tipo 1",
"promotionApplicationForm": "tipo 1",
"reportParticipants": "false",
"suggest": "not",
"sets": {
"set": {
"name": "631642d4cfaa7738300ff981",
"type": "item"
}
},
"condition": {
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "631642d4cfaa7738300ff981"
}
},
"benefits": {
"benefit": {
"instance": "PercentageDiscount",
"parameter": [
{
"key": "displayMessage",
"value": "promo import"
},
{
"key": "printerMessage",
"value": "promo import"
},
{
"key": "TLOGMessage",
"value": "promo import"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "name",
"value": "631642c3cfaa7738300ff97e"
},
{
"key": "percent",
"value": "10"
},
{
"key": "unit",
"value": "qty"
},
{
"key": "prorateBCP",
"value": "false"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {"name": "631642d4cfaa7738300ff981"}
}
}
}
}
]
}
Importante
Al momento de insertar una promoción por servicio REST va a generar un nuevo id para el Beneficio, no va a considerar el id del beneficio asignado por el usuario en el json, eso es para evitar que se asignen id duplicados.
Por lo que al actualizar de nuevo la promoción el usuario deberá tener en cuenta el id del beneficio generado y actualizarlo en el json antes de enviar su cambio, de lo contrario ese beneficio se tomara como nuevo y se insertara, generando como consecuencia que se duplique el beneficio, ya que al no conseguir el id cuando hace la busqueda de los beneficios en la promoción, lo tomara como un nuevo beneficio para la promoción.
- Para operaciones I (insertar) se generara un nuevo id para el beneficio.
- Por lo que para U (Modificar) la promoción se deberá indicar el numero del nuevo id generado.
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: Cancelación |
| 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
Si la solicitud ha sido exitosa, se podrá visualizar la siguiente respuesta:
Request exitoso
{
"status": "Información Recibida OK",
"description": "La importación de promociones será procesada"
}
En el caso de indicar un código de compañía que no existe, visualizará la siguiente respuesta:
Error con compañía indicada
{
"status": "companyId is Invalid",
"description": "Debe enviar el campo companyId válido"
}
Ejemplo 1: 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/promotion/import"
Se enviará el siguiente request:
{
"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:
{
"status": "Información Recibida OK",
"description": "La importación de promociones será procesada"
}
IMPORTACIÓN DE UNA PROMOCIÓN DESDE UN MAPA (.xml):
Pasos a seguir para convertir un mapa (.xml) en un json de entrada del servicio de Importación Masiva de Promociones vía REST:
Dado el siguiente mapa .xml:
<?xml version="1.0" encoding="UTF-8"?> <promo-engine start-date="19/05/2022 00:00" end-date="26/05/2022 23:59" map-version="1" suggest="not"> <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="62867033c9512b0184381178" name="Promos con limites 1" code="30" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not"> <sets> <set name="62867340c9512b01843811b5" type="item" attribute="code" comparator="Into" value="111"/> </sets> <condition type="composite" name="And"> <condition type="basic" name="Exists"> <parameter key="use-set" value="62867340c9512b01843811b5"/> </condition> <condition type="basic" name="Header"> <parameter key="attribute" value="store"/> <parameter key="value" value="napse,napse2"/> </condition> </condition> <benefits> <benefit instance="FixedDiscount" nro="628670c9c9512b018438117f"> <parameter key="displayMessage" value="Promos con limites 1"/> <parameter key="printerMessage" value="Promos con limites 1"/> <parameter key="TLOGMessage" value="Promos con limites 1"/> <parameter key="applicationMethod" value="resume"/> <parameter key="prorationMethod" value="proportional"/> <parameter key="applicationPriceType" value="benefited-price"/> <parameter key="hasLimit" value="true"/> <parameter key="name" value="62867033c9512b0184381178"/> <parameter key="amount" value="300"/> <parameter key="unit" value="qty"/> <parameter key="prorateBCP" value="false"/> <parameter key="recoveryValue" value="0"/> <parameter key="recoveryType" value=""/> <applied-elements> <use-set name="62867340c9512b01843811b5"/> </applied-elements> </benefit> </benefits> </promotion> </promotions> <evaluation-algorithm> <step> <function name="ALL"> <function name="SIMPLE"> <promotion-usage name="Promos con limites 1"/> </function> </function> </step> </evaluation-algorithm> </promo-engine>
- Se deberá tomar solo la sección del bloque <promotion ....>, tal como se ve en la siguiente imagen:
<promotion nro="62867033c9512b0184381178" name="Promos con limites 1" code="30" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not"> <sets> <set name="62867340c9512b01843811b5" type="item" attribute="code" comparator="Into" value="111"/> </sets> <condition type="composite" name="And"> <condition type="basic" name="Exists"> <parameter key="use-set" value="62867340c9512b01843811b5"/> </condition> <condition type="basic" name="Header"> <parameter key="attribute" value="store"/> <parameter key="value" value="napse,napse2"/> </condition> </condition> <benefits> <benefit instance="FixedDiscount" nro="628670c9c9512b018438117f"> <parameter key="displayMessage" value="Promos con limites 1"/> <parameter key="printerMessage" value="Promos con limites 1"/> <parameter key="TLOGMessage" value="Promos con limites 1"/> <parameter key="applicationMethod" value="resume"/> <parameter key="prorationMethod" value="proportional"/> <parameter key="applicationPriceType" value="benefited-price"/> <parameter key="hasLimit" value="true"/> <parameter key="name" value="62867033c9512b0184381178"/> <parameter key="amount" value="300"/> <parameter key="unit" value="qty"/> <parameter key="prorateBCP" value="false"/> <parameter key="recoveryValue" value="0"/> <parameter key="recoveryType" value=""/> <applied-elements> <use-set name="62867340c9512b01843811b5"/> </applied-elements> </benefit> </benefits> </promotion>
2. Luego, ir al sitio web https://www.oxygenxml.com/xml_json_converter.html, para convertir el xml a formato json.
3. Pegar el xml dentro del campo XML y generar el Json presionando el botón con la ->
4. Esto generará el siguiente resultado, del cual solo se deberá copiar lo que está dentro de "promotion": { marcado en azul, tal como se muestra en el siguiente ejemplo:
Ejemplo:
{
"promotion": {
"nro": "62867033c9512b0184381178",
"name": "Promos con limites 1",
"code": "30",
"className": "com.synthesis.promo.engine.promotion.ModularPromotion",
"reportParticipants": "false",
"suggest": "not",
"sets": {
"set": {
"name": "62867340c9512b01843811b5",
"type": "item",
"attribute": "code",
"comparator": "Into",
"value": "111"
}
},
"condition": {
"type": "composite",
"name": "And",
"condition": [
{
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "62867340c9512b01843811b5"
}
},
{
"type": "basic",
"name": "Header",
"parameter": [
{
"key": "attribute",
"value": "store"
},
{
"key": "value",
"value": "napse,napse2"
}
]
}
]
},
"benefits": {
"benefit": {
"instance": "FixedDiscount",
"nro": "628670c9c9512b018438117f",
"parameter": [
{
"key": "displayMessage",
"value": "Promos con limites 1"
},
{
"key": "printerMessage",
"value": "Promos con limites 1"
},
{
"key": "TLOGMessage",
"value": "Promos con limites 1"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "hasLimit",
"value": "true"
},
{
"key": "name",
"value": "62867033c9512b0184381178"
},
{
"key": "amount",
"value": "300"
},
{
"key": "unit",
"value": "qty"
},
{
"key": "prorateBCP",
"value": "false"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {"name": "62867340c9512b01843811b5"}
}
}
}
}
}
5. Una vez copiado todo el contenido marcado en azul, se deberá actualizar el formato estándar de importación de promociones. Por ejemplo:
Deberá pegar el contenido copiado dentro después de “operation”: I, tal como se ve en la siguiente imagen.
Esto da el siguiente resultado con el formato de importación ya completo y listo para usar desde POSTMAN (el contenido pegado está marcado en azul):
Resultado del JSON de importación de promoción:
{
"companyId": "napse",
"promotions": [
{
"operation": "I",
"nro": "62867033c9512b0184381178",
"name": "Promos con limites 1",
"code": "30",
"className": "com.synthesis.promo.engine.promotion.ModularPromotion",
"reportParticipants": "false",
"suggest": "not",
"sets": {
"set": {
"name": "62867340c9512b01843811b5",
"type": "item",
"attribute": "code",
"comparator": "Into",
"value": "111"
}
},
"condition": {
"type": "composite",
"name": "And",
"condition": [
{
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "62867340c9512b01843811b5"
}
},
{
"type": "basic",
"name": "Header",
"parameter": [
{
"key": "attribute",
"value": "store"
},
{
"key": "value",
"value": "napse,napse2"
}
]
}
]
},
"benefits": {
"benefit": {
"instance": "FixedDiscount",
"nro": "628670c9c9512b018438117f",
"parameter": [
{
"key": "displayMessage",
"value": "Promos con limites 1"
},
{
"key": "printerMessage",
"value": "Promos con limites 1"
},
{
"key": "TLOGMessage",
"value": "Promos con limites 1"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "hasLimit",
"value": "true"
},
{
"key": "name",
"value": "62867033c9512b0184381178"
},
{
"key": "amount",
"value": "300"
},
{
"key": "unit",
"value": "qty"
},
{
"key": "prorateBCP",
"value": "false"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {"name": "62867340c9512b01843811b5"}
}
}
}
}
]
}
6. Importación del json desde POSTMAN:
Resultado:
Promo importada y creada correctamente:
Tipo, subtipo y Forma de Aplicación
Promo admite tanto por servicio Rest como por importación de promociones en xml, importar promociones con tipo, subtipo y forma de aplicación.
Ej:
Json:
{
"companyId": "napse",
"promotions": [{
"operation": "I",
"name": "Promo Import4",
"code": "Promo Import4",
"promotionType": "tipo 1",
"promotionSubType": "tipo 1",
"promotionApplicationForm": "tipo 1",
"reportParticipants": "false",
"suggest": "not",
"sets": {
"set": {
"name": "6324b5f8be13d734e87ccc14",
"type": "item"
}
},
"condition": {
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "6324b5f8be13d734e87ccc14"
}
},
"benefits": {
"benefit": {
"instance": "PercentageDiscount",
"parameter": [{
"key": "displayMessage",
"value": "promo import"
},
{
"key": "printerMessage",
"value": "promo import"
},
{
"key": "TLOGMessage",
"value": "promo import"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "name",
"value": "6324b5a1be13d734e87ccc0e"
},
{
"key": "percent",
"value": "10"
},
{
"key": "unit",
"value": "qty"
},
{
"key": "prorateBCP",
"value": "false"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {
"name": "6324b5f8be13d734e87ccc14 "
}
}
}
}
}]
}
Desde Postman:
Promo importada y creada exitosamente:
Servicio de importación de promociones con los atributos de cabecera deshabilitados
Es posible insertar promociones, cuando se deshabiliten e inactiven los atributos de cabecera, en la consola:
EJ. Json:
{
"companyId": "napse",
"promotions": [
{
"nro": "",
"name": "promoIT1",
"code": "",
"className": "com.synthesis.promo.engine.promotion.ModularPromotion",
"reportParticipants": "false",
"suggest": "not",
"sets": {
"set": {
"name": "627b93e926a51910c877b0e5",
"type": "item",
"attribute": "code",
"comparator": "Into",
"value": "1234"
}
},
"combo": {
"combo-component": {
"min": "1",
"max": "4",
"attribute": "qty",
"use-set": "627b93e926a51910c877b0e9"
}
},
"benefits": {
"benefit": {
"instance": "FixedDiscount",
"nro": "627b953326a51910c877b0f1",
"parameter": [
{
"key": "displayMessage",
"value": "Bug305863-Limite_71-47440-47573"
},
{
"key": "printerMessage",
"value": "Bug305863-Limite_71-47440-47573"
},
{
"key": "TLOGMessage",
"value": "Bug305863-Limite_71-47440-47573"
},
{
"key": "applicationMethod",
"value": "lineByLine"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "original-price"
},
{
"key": "hasLimit",
"value": "true"
},
{
"key": "name",
"value": "627b939926a51910c877b0e4"
},
{
"key": "amount",
"value": "1000"
},
{
"key": "unit",
"value": "qty"
},
{
"key": "recoveryValue",
"value": "100"
},
{
"key": "recoveryType",
"value": "p"
},
{
"key": "margengasto",
"value": "1"
},
{
"key": "prorateBCP",
"value": "false"
}
],
"applied-elements": {
"use-set": {"name": "627b93e926a51910c877b0e9"}
},
"staggered": {
"unit": "qty",
"staggeredStep": [
{
"nro": "627b947426a51910c877b0ed",
"min": "1",
"max": "1",
"applyValue": "50000"
},
{
"nro": "627b949c26a51910c877b0f0",
"min": "4",
"max": "4",
"applyValue": "1000"
}
]
}
}
},
"operation":"I"
}
]
}
Desde Postman:
Promo importada y creada correctamente:
Si se activan y habilitan los atributos de cabecera:
la promocion fue importada y creada correctamente:
Si los atributos de cabecera sólo son requeridos, pero no activos, la promocion se importa y crea correctamente:
Pero los atributos no se mostrarán en la Promocion:
Por último, se pueden importar promociones cuyos atributos de cabecera estan activos, pero no son requeridos:
se importaron y crearon exitosamente:
En este caso los campos se crearan vacíos:
Servicio de Exclusión de Fechas para no ser ejecutada una promoción
Servicio que permite tener la posibilidad de configurar una exclusión de fechas determinadas durante todo el período de vigencia para NO ser ejecutada una promoción por sucursal. Esta opción va a permitir controlar que en determinadas fechas(que son días especiales) no se aplique las promociones que tienen productos que participan en estos días.
Este método accesible desde api/rest/catalogs es el encargado de devolver en formato JSON las fechas en que deben excluirse las promociones y en las tiendas informadas solicitado por medio de la acción POST.
http://{{SERVER}}:{{PORT}}/promo/api/rest/catalogs
Ej:
http://localhost:8080/promo/api/rest/catalogs
El formato para el servicio será:
| Campo | Ejemplos | Tipo de dato | Detalle |
| companyId | napse | Alfanumérico | Código de la compañía - Requerido |
| catalog | Listado | Listado de limites - Requerido | |
| params | [ ] | Listado | Parámetros adicionales - Requerido |
| storeCode | napse | Alfanumérico | Código de la tienda - Requerido |
| promotionNames | Promo test | Alfanumérico | Nombre de la promoción que será excluida para la tienda y fecha indicada. No obligatorio para la operación R, solo en los casos en que se quiera eliminar todas las exclusiones de días específicos, este campo podrá quedar como vacío es decir "", indicando que todas las exclusiones de promociones en las fechas indicadas serán removidas. |
| exclusionDates | ["2022-07-21", "2022-07-22"] | Listado de fechas | Fechas en las que será excluida la promoción, cada fecha deberá seguir el formato de "año-mes-día" - Requerido |
| operation | I | Alfanumérico | Identifica el tipo de operación a realizar por cada limite a procesar (requerido), dentro de las opciones disponibles están:
|
Ej:
{
"companyId": "napse",
"catalog": "CatalogExclusionDates",
"params": [],
"items": [
{
"storeCode": "napse",
"promotionName": "Promo 001",
"exclusionDates": ["2022-07-25","2022-07-27","2022-07-29"],
"operation": "I" //Tipo de operación asociada a I (insertar), U (actualizar) y R (remover)
},
{
"storeCode": "napse",
"promotionName": "Promo 002",
"exclusionDates": ["2022-07-21"],
"operation": "U"
},
{
"storeCode": "napse",
"promotionName": "Promo 002",
"exclusionDates": ["2022-07-21"],
"operation": "R"
}
]
}
Formato de una exclusión con operación I
El siguiente json representa el formato para el registro de nuevas exclusiones de promociones por fecha para una tienda y promoción especifica.
- Tenga en cuenta que en el campo exclusionDates solo podrá indicar datos de la fecha con el formato "año-mes-día"
- Solo se crearan las exclusiones con las fechas que sean validas, es decir que tengan el formato del punto anterior y que no sean menor a la fecha actual.
- Si la promoción sobre la cual se procesaran las exclusiones tiene vigencia definida (Fecha inicio y fin), las fechas incluidas en el campo exclusionDates deberá estar dentro del rango de vigencia de la promo, de lo contrario las exclusiones fuera de la vigencia serán ignoradas, creando solo las exclusiones sobre las fechas que estén dentro de la vigencia.
{
"companyId": "napse",
"catalog": "CatalogExclusionDates",
"params": [],
"items": [
{
"storeCode": "napse",
"promotionName": "Promo 001",
"exclusionDates": ["2022-07-25","2022-07-27","2022-07-29"],
"operation": "I"
}
]
}
Formato de una exclusión con operación U
El proceso de actualización de la exclusión de promociones por fecha, considera los puntos indicados para la operación I, teniendo solo las siguientes particularidades:
- El proceso de actualización incorporara nuevos registros de fechas de exclusión para la promoción siempre y cuando ya no exista un registro previo sobre esa misma promoción, tienda y fecha.
{
"companyId": "napse",
"catalog": "CatalogExclusionDates",
"params": [],
"items": [
{
"storeCode": "napse",
"promotionName": "Promo 001",
"exclusionDates": ["2022-07-25"],
"operation": "U"
}
]
}
Formato de limite con operación R
El proceso de remover exclusiones contempla dos casos:
1- Cuando se quiere remover la exclusión de una promoción en una fecha especifica, deberá indicar el siguiente formato.
{
"companyId": "napse",
"catalog": "CatalogExclusionDates",
"params": [],
"items": [
{
"storeCode": "napse",
"promotionName": "Promo 001",
"exclusionDates": ["2022-07-25"],
"operation": "R"
}
]
}
Cuando se quiere remover la exclusión de todas las promociones en una fecha especifica, deberá indicar el siguiente formato.
- La diferencia con el formato anterior es que el valor del campo promotionName se deja como un string vacío igual a ""
{
"companyId": "napse",
"catalog": "CatalogExclusionDates",
"params": [],
"items": [
{
"storeCode": "napse",
"promotionName": "",
"exclusionDates": ["2022-07-25"],
"operation": "R"
}
]
}
Respuesta del servicio
Si la solicitud ha sido exitosa, se podrá visualizar la siguiente respuesta (Interfaz Rest):
Request exitoso
{
"status": "200",
"description": "CatalogExclusionDates",
"detail": {
"result": "ok",
"detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
}
}
En el caso de indicar un código de compañía que no existe, visualizara la siguiente respuesta
Error con compañia indicada
{
"status": "400",
"description": "CatalogExclusionDates",
"detail": {
"result": "error",
"detail": "El código de compañía test no pertenece a una compañía existente."
}
}
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 Elementos de Fidelidad
Esta operación es el equivalente a la función de asignacion/actualización de elementos, mas la importación de clientes nuevos (Ver proceso actual de asignación de convenios). En este caso los campos serán:.
ASIGNACIÓN A UN ELEMENTO DE UN CLIENTE, UN CONVENIO, Y SU MONTO.
Esta operación realiza la asignación de elemento, cliente, convenio, y monto. Debe existir previamente el elemento (activo o inactivo), un convenio activo, y el cliente, en caso de no existir, se da de alta. En relación al monto, se puede asignar un valor, ingresando el valor del monto; sumar un valor al monto que el elemento tiene, especificando el operador +; y para el caso de restar saldo se debe especificar el operador - (ver más abajo el ejemplo del campo amount).
Un esquema de ejemplo es el siguiente:
{
"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 elemento de fidelidad a importar que sera validado. contract: codigo de convenio al que pertenecen estos elementos/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 |
Asignación de ejemplo
Teniendo en cuenta que existe un convenio activo con código c1, y que hay un elemento existente, con código 1234000000000, y pertenece al tipo de elemento de código verano, se asigna al elemento el convenio mencionado, el monto de 100, y un nuevo cliente. Al no existir se da de alta en la base de datos.
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogCardAssign",
"params": [
{"cardType": "verano"},
{"contract": "c1"}
],
"items": [{
"operation": "I",
"id": "1234000000000",
"customer": "emc",
"amount": "100",
"name": "Eugenia",
"surname": "Molina",
"gender": "M",
"birthDate": "19900101",
"idType": "dni",
"identifier": "77778888",
"idDate": "20500101",
"nacionality": "Argentina",
"email": "[email protected]",
"customerType": "vip",
"address": "Urquiza 5050",
"country": "ar",
"state": "bsas",
"city": "tig",
"postalCode": "4433",
"phone": "2222-9999"
}]
}
Incremento de saldo
Para incrementar el saldo al elemento se especifica un operador + con el valor a sumar. Siguiendo el ejemplo anterior, donde el elemento tenía un saldo de 100, se le suman 50 en este ejemplo. Después de esta operación el saldo resultante será de 150.
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogCardAssign",
"params": [
{"cardType": "verano"},
{"contract": "c1"}
],
"items": [{
"operation": "I",
"id": "1234000000000",
"customer": "emc",
"amount": "+50",
"name": "Eugenia",
"surname": "Molina",
"gender": "M",
"birthDate": "19900101",
"idType": "dni",
"identifier": "77778888",
"idDate": "20500101",
"nacionality": "Argentina",
"email": "[email protected]",
"customerType": "vip",
"address": "Urquiza 5050",
"country": "ar",
"state": "bsas",
"city": "tig",
"postalCode": "4433",
"phone": "2222-9999"
}]
}
Decremento de saldo
Similar al incremento. Para restar saldo se usa el operador - y luego el valor del monto a restar. Si el elemento anteriormente tenía 150, al restar 20 queda en 130 de monto.
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogCardAssign",
"params": [
{"cardType": "verano"},
{"contract": "c1"}
],
"items": [{
"operation": "I",
"id": "1234000000000",
"customer": "emc",
"amount": "-20",
"name": "Eugenia",
"surname": "Molina",
"gender": "M",
"birthDate": "19900101",
"idType": "dni",
"identifier": "77778888",
"idDate": "20500101",
"nacionality": "Argentina",
"email": "[email protected]",
"customerType": "vip",
"address": "Urquiza 5050",
"country": "ar",
"state": "bsas",
"city": "tig",
"postalCode": "4433",
"phone": "2222-9999"
}]
}
Transferencia de saldos.
Una transferencia de saldos puede ser total, cuando se transfiere todo el monto, o parcial, si sólo se realiza el intercambio de una parte del valor. En el caso de una transferencia total, hay que considerar que dar de baja el primer elemento de fidelidad, del cual se obtiene el monto.
Para poder realizar una transferencia de saldos, tanto el elemento de origen (el que da saldo) como el de destino (el que recibe saldo) deben ser del mismo tipo.
En la seq=1 enviada por el POS se informara el elemento origen, es decir, a quien se le descontaran los puntos, dinero, millas, etc.
En la seq=2 enviada por el POS se informara el elemento destino, es decir, la que recibirá los puntos, dinero, millas, etc.
(Ver también Manual de Usuario, "Conceptos de Tarjetas de Fidelidad" para más detalle sobe los distintos tipos de transferencia posible,)
Transferencia parcial
Teniendo ya un elemento de código 2345000000000 con monto de 100 y 2345000000001 con monto de 25, se le transfiere, al segundo elemento, 50 de monto. El resultado es que el elemento 2345000000000 quedará con 50 de monto, y la segunda 2345000000001 con 75. El tipo de elemento, invierno, especifica que la transferencia es parcial.
Al operar con postman, como el mensaje correspondiente será en formato xml, la cabecera content type tendrá el valor application/xml en lugar de application/json.
Tener en cuenta que la url cambia para hacer esta operación, ya que se interactúa contra el motor. El valor que aparece a la derecha de evaluate, en la dirección, es autocompletado por postman. El cuerpo del mensaje (body) tendrá que estar vacío. Los mensajes se enviarán como un parámetro en la dirección. Este parámetro es request. Separar el valor con dos puntos. Presionar, para facilitar el ingreso de datos, en bulk edit (a la derecha de la solicitud) que luego cambia a key-value edit. El valor del parámetro request es el xml a enviar al motor, el cual no deberá tener ningún espacio entre etiquetas.
En la respuesta aparece como quedarían estas tarjetas de confirmarse la operación. Se confirma la operación con el mismo mensaje, pero con el atributo status en "commit" en lugar de "loyaltyTransfer" o "rollback" para cancelar.
Al confirmar la operación....
se verá en la consola reflejado el cambio.
Alta del Elemento de Fidelidad asociada al cliente identificado en la transacción (al momento de aplicar el beneficio de acumulación)
Para la asignación y carga de un elemento de fidelidad que acumule stickers deberá considerarse la siguiente secuencia entre el pos y Promo:
- Pre-Requisitos:
Para que el alta de clientes pueda efectuarse al momento de procesarse una transacción, deberá de habilitarse en el archivo de configuraciones de la Consola de Promo (“promoplus.properties”) el siguiente atributo:
# Habilita el alta de clientes on the fly promo.allowNonExistingCustomers = true |
Una vez actualizado, deberá de reiniciarse el Wildfly para que los cambios sean tomados correctamente.
- Alta de Cliente
Los clientes serán creados utilizando el estado "loyaltyValidation" en el caso de enviarse los datos mínimos y al mismo tiempo Promo detecte que el cliente no existe. Los datos mínimos mencionados son (marcados en Rojo):
<customer-add
seq="1" id="10090504" identifier="10090504" type="test" name="pepe" lastName="rodrigues" identifierType="cpf" email="mimail@test.com" />
Input
Input
|
En la respuesta al loyaltyValidation no se informarán tarjetas ya que el cliente esta recién ingresado en la consola de Promo.
Output
|
Ingreso de ítem
Input
|
Se devuelve promoción que aplica puntos el elemento Stickers A
Output
|
Dado que el cliente no tiene elementos asociados, se deberá dar de alta en Promo un nro. de elemento del mismo tipo que recibe el beneficio informado, y asociarla al cliente.
NOTA
Los beneficios del tipo Loyalty que informen en su tipo (“type”) la palabra “external”, corresponderan a tipos de elementos no gestionadas por promo, las cuales no participan en Stickers.
Actualizacion: Se utilizara, para el alta de elementos durante la transaccion el status “loyaltyActivation”, enviando el tag <loyaltyCard-add/> el parámetro status=”CREATE”, el campo Type del mismo tag deberá corresponderse con el tipo de elemento que es beneficiado durante la transacción, y en el campo id deberá indicarse el numero de elemento que se desea asignar.
Este número no necesariamente debe corresponderse con el largo y prefijo indicado en el tipo de elemento, podrá indicarse un código libre y se controlará que para dicho tipo de elemento no existan dos números de elementos iguales.
Input
|
|
Esta operación no requiere FINISH ni COMMIT.
Para confirmar la correcta asociacion, debera realizarse un LoyaltyValidation del cliente y aquí debera de modificarse el TimeStamp de la transaccion a fin de que los puntos otorgados luego por el beneficio sean asignados correctamente al elemento recientemente creado.
Input
|
Output
|
Una vez que el cliente ya tiene el elemento asociado y activo, podrá ingresarse ésta en la transacción para asi asignarle los puntos otorgados por el beneficio.
Input
|
Output
|
Input
|
Output
|
Input
|
Output
|
Input
|
Output
|
Para confirma la correcta imputación, podrá realizarse un LoyaltyValidation del cliente y/o elemento y verificar los datos.
Input
|
Output
|
Luego de cerrada la transacción, podrá visualizarse desde la consola de Promo el nuevo elemento creado con el saldo asignado.
Servicio de Importacion de Segmentos
(v 6.5) Sincrónico
Servicio Rest que opera de forma sincrónica para administrar clientes asociados a segmentos.
Una vez obtenido el token de acceso, el servicio puede ser invocado utilizando el método POST, desde la URL: <promo>/api/rest/segments
Servicio de Administración de Elementos de Fidelidad
Servicio Rest que opera de forma sincrónica para administrar elementos de fidelidad.
Una vez obtenido el token de acceso, el servicio puede ser invocado utilizando el método POST, desde la URL: <promo>/api/rest/cards/admin**
Servicio de Administración de Cupones
Crear, Activar y redimir Cupones
Servicio Rest que opera de forma sincrónica para administrar Cupones.
Una vez obtenido el token de acceso, el servicio puede ser invocado utilizando el método POST, desde la URL: <promo>/api/rest/coupons/admin**
Servicio de Administración de Clientes
Crear, Modificar y Eliminar Clientes y Creación automática de elementos de fidelidad asociados
Servicio rest sincrónico de clientes (alta, baja y modificación) además crea y asocia elementos (el número de elemento se genera con el prefijo más el identificador del cliente).
Se pueden generar hasta 100 clientes.
Utilizando el método POST : promo/api/rest/customer
El campo “autoCard” contendrá un tipo de elemento, que si el cliente no posee será creada.
Ese elemento seguirá la definición de su tipo pero en el número asignará el nro de documento del cliente además del prefijo y largo de numeración.
Si el elemento existe no es creado. Si se crea, respeta el saldo inicial, vencimientos y todos los datos definidos en el tipo de elemento. Queda asociado al cliente en el mismo acto en que se crea.
{
"companyId": "napse",
"catalog": "CatalogCustomer",
"params": [],
"items": [
{ "code": "codigo32", "name": "Ricardo", "lastName": "Pérez", "gender": "m", "birthDate": "2012-04-23", "identificationType": "dni", "identifier": "28710943", "identificationExpiration": "2050-01-01", "nacionality": "arg", "email": "[email protected]", "customerType": "EMPLEADO", "address": "diagonal 12 2233", "addressCountry": "arg", "addressState": "bsas", "addressCity": "tig", "addressPostalCode": "22223", "phone": "1111111123", "isActive": "true", "operation": "U", "autoCard":"cardType1" }
,
{ "code": "codigo33", "name": "Ricardo", "lastName": "Pérez", "gender": "m", "birthDate": "2012-04-23", "identificationType": "dni", "identifier": "28710944", "identificationExpiration": "2050-01-01", "nacionality": "arg", "email": "[email protected]", "customerType": "EMPLEADO", "address": "diagonal 12 2233", "addressCountry": "arg", "addressState": "bsas", "addressCity": "tig", "addressPostalCode": "22223", "phone": "1111111123", "isActive": "true", "operation": "I", "autoCard":"cardType2" }
,
{ "code": "codigo34", "name": "Ricardo", "lastName": "Pérez", "gender": "m", "birthDate": "2012-04-23", "identificationType": "dni", "identifier": "28710944", "identificationExpiration": "2050-01-01", "nacionality": "arg", "email": "[email protected]", "customerType": "EMPLEADO", "address": "diagonal 12 2233", "addressCountry": "arg", "addressState": "bsas", "addressCity": "tig", "addressPostalCode": "22223", "phone": "1111111123", "isActive": "true", "operation": "I", "autoCard":"cardType2" }
,
{ "code": "codigo35", "name": "Ricardo", "lastName": "Pérez", "gender": "m", "birthDate": "2012-04-23", "identificationType": "dni", "identifier": "28710945", "identificationExpiration": "2050-01-01", "nacionality": "arg", "email": "[email protected]", "customerType": "EMPLEADO", "address": "diagonal 12 2233", "addressCountry": "arg", "addressState": "bsas", "addressCity": "tig", "addressPostalCode": "22223", "phone": "1111111123", "isActive": "true", "operation": "U", "autoCard":"cardType1" }
]
}
Servicio de Administración de Límites
Crear, Modificar y Eliminar Límites de Promociones por tiendas
Se pueden dar de alta masiva de limites vía api rest. El Json en este caso será:
{
"companyId":"napse",
"limits": [
{
"operation":"I",
"promotionName":"Promo limites 3",
"benefitId": "62d575e6c1ac1f2fe0707033",
"limitId": "",
"limitScope":"RETAILER",
"storeCode": "",
"description": "",
"limitPeriod":"DAY",
"numberDays":"2",
"limitTypeCode": "benefiedProductCount",
"value": "4"
},
{
"operation":"I",
"promotionName":"Promo limites 3",
"benefitId": "62d575e6c1ac1f2fe0707033",
"limitId": "",
"limitScope":"STORE",
"storeCode": "napse",
"description": "",
"limitPeriod":"DAY",
"numberDays":"5",
"limitTypeCode": "benefiedProductCount",
"value": "2"
}
]
}
{
"companyId":"napse",
"limits": [
{
"operation":"U",
"limitId": "62d57724c1ac1f2fe0707038",
"limitScope":"RETAILER",
"storeCode": "",
"description": "",
"limitPeriod":"DAY",
"numberDays":"2",
"limitTypeCode": "benefiedProductCount",
"value": "5"
}
]
}
{
"companyId":"napse",
"limits": [
{
"operation":"R",
"limitId": "62d57724c1ac1f2fe0707038"
}
]
}
Cada vez que se ejecute un Json con límites para las promociones esto generará un registro de importación, cuyo estado será visible desde Soporte/ Monitor de Importación.