PROMO 7.4 - Manual de Integración - Servicios
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 básicamente 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 línea de comandos para enviar/recibir mensajes http.
- POSTMAN (https://www.postman.com) "The Collaboration Platform for API Development": Herramienta Grafica para la creación, envío y recepción de mensajes.
- SOAPUI (https://www.soapui.org/) "Accelerating API Quality Through Testing": Otra herramienta Gráfica para la definición, envío 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, para obtener el Token en POSTMAN, sería:
- Debe seleccionar Type 0Auth 2.0
- Indicar la URL de la versión a la cual se quiere conectar
- Indicar ClientID
- Indicar nombre de usuario y password
Luego presionar el botón "Get New Access Token"
Por último presionar el botón "Use Token"
Una vez obtenido el token, se puede enviar una solicitud, por ejemplo realizamos un GET:
Al presionar el botón "Send", se obtiene el siguiente resultado:
{
"_id": "64ac2a4ea62e431d30370c98",
"addressCountry": "arg",
"lastName": "Pérez",
"identifier": "28710944",
"code": "11",
"identificationExpiration": "2050-01-01T03:00:00Z",
"address": "diagonal 12 2233",
"gender": "m",
"autoCard": "cardType2",
"identificationType": "dni",
"addressState": "bsas",
"isActive": true,
"birthDate": "2012-04-23T03:00:00Z",
"addressPostalCode": "22223",
"customerType": "EMPLEADO",
"phone": "1111111123",
"nacionality": "arg",
"name": "RICARDO",
"email": "[email protected]",
"addressCity": "tig",
"companyId": "2",
"creationDate": "2023-07-10T15:57:02Z",
"cards": [],
"coupons": []
}
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://[SERVER]:[PORT]/promo/api/rest/customer
- Estado de Limites del cliente: http://[SERVER]:[PORT]/promo/api/rest/limit/limitStatus
- Cupones: http://[SERVER]:[PORT]/promo/api/rest/coupon
- Elementos de Fidelidad: http://[SERVER]:[PORT]/promo/api/rest/card
- Mapas, promociones y promociones distribuidas: http://[SERVER]:[PORT]/promo/api/rest/promotions
- Próximo numero de elemento de fidelidad: http://[SERVER]:[PORT]/promo/api/rest/nextCardNumber
- Reporte de promociones: http://[SERVER]:[PORT]/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 fue originada offline, y false determina que fue 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 ítems, 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. Requerido |
| barcode | Alfanumérico | Código del elemento de fidelidad la cual se quiere consultar. Opcional |
limit | Numérico | Cantidad de registros de movimientos a retornar (default: 5) con un máximo de 100.000 por consulta. Opcional |
dateFrom | Numérico | Fecha de Inicio en formato YYYYMMDD. Si no se especifica barcode. Opcional |
dateTo | Numérico | Fecha de Final en formato YYYYMMDD. Si no se especifica barcode. Opcional |
couponAction | Alfanumérico | Código de Operación que se quiere consultar. Si no se especifica barcode. Por defecto son todas las operaciones. Los valores disponibles son: CREATE, REDEEM, VOID. Opcional |
| timeFrom | Numérico | Hora de Inicio con formato HHmm. Opcional |
| timeTo | Numérico | Hora de Fin con formato HHmm. Opcional |
| 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. Opcional |
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 cupón 1040BC005233
http://localhost:8073/promo/api/rest/coupon?companyId=2&barcode=1040BC005233
La misma pero utilizando CURL:
curl -X GET -H "Authorization: Bearer c4349afa-2c2e-46a8-b768-f89a4cb334bf'" -H "Content-type: application/json" -H "Accept: application/json" http://localhost:8073/promo/api/rest/coupon?companyId=2&barcode=1040BC005233
Obteniéndose la siguiente respuesta:
Ejemplo {
"_id": "6435a371a62e43505468c39d",
"barcode": "1040BC005233",
"companyId": "napse",
"consumed": false,
"couponFormat": "PRE_PRINTED",
"couponStatus": "ACTIVE",
"couponType": "5",
"issuedDate": "2023-04-11T18:14:09Z",
"maxUsageTimes": 1,
"storeCode": "BC",
"terminalCode": "5",
"transactionId": "BC_202304111514814",
"usedTimes": 0,
"validFrom": "2023-04-11T03:00:00Z",
"validTo": "2123-03-18T03:00:00Z",
"version": 1,
"amount": null,
"customerId": null,
"email": null,
"emitPromotion": null,
"generatedHTML": null,
"lastRedeemedDate": null,
"redeemPromotion": null,
"couponHistory": [
{
"date": "2023-04-11T19:00:00Z",
"couponAction": "ACTIVE",
"storeCode": "BC"
},
{
"couponAction": "CREATE",
"date": "2023-04-11T18:14:09Z",
"storeCode": "BC"
}
]
}
|
EJEMPLO 2: Se solicitan todos los cupones creados en el periodo 01/03/2024-25/03/2024, para la empresa napse con un limite de 100.000 registros.
http://localhost:8073/promo/api/rest/coupon?companyId=napse&dateFrom=20240301&dateTo=20240325&limit=100000&couponAction=create
(curl -X GET -H "Authorization: Bearer ea41e16c-6070-4a05-82c1-6d54ae70a225" -H "Content-type: application/json" -H "Accept: application/json"http://localhost:8073/promo/api/rest/coupon?dateFrom=20240301&dateTo=20240325&companyId=napse&limit=100000&couponAction=create
La respuesta será del tipo:
{
"couponHistory": [
{
"transactionId": "napse_1_1_20240419173500",
"date": "2024-03-19T20:29:30Z",
"coupon": "1170010016472",
"couponAction": "CREATE",
"storeCode": "1",
"terminalCode": "1",
"customerCode": "-"
},
{
"transactionId": "napse_1_1_20240419173500",
"date": "2024-03-19T20:29:30Z",
"coupon": "1190010016470",
"couponAction": "CREATE",
"storeCode": "1",
"terminalCode": "1",
"customerCode": "-"
},
{
"transactionId": "napse_1_1_20240419173500",
"date": "2024-03-19T20:29:30Z",
"coupon": "1180010016471",
"couponAction": "CREATE",
"storeCode": "1",
"terminalCode": "1",
"customerCode": "-"
}
]
}
EJEMPLO 3: Con la siguiente consulta se obtienen todos los movimientos de todos los cupones dentro del rango de fechas: desde 01 de enero de 2024, hasta el 19 de marzo de 2024, que ocurrieron en la compañía Napse.
http://localhost:8073/promo/api/rest/coupon?dateFrom=20240101&dateTo=20240319&companyId=napse
Obteniéndose la siguiente respuesta:
{
"couponHistory": [
{
"transactionId": "-",
"date": "2024-01-02T14:00:00Z",
"coupon": "1030BCeso0000",
"couponAction": "EXPIRATE",
"storeCode": "BC",
"terminalCode": "pre-impreso",
"customerCode": "null"
},
{
"transactionId": "-",
"date": "2024-01-02T14:00:00Z",
"coupon": "1030BCeso6472",
"couponAction": "EXPIRATE",
"storeCode": "BC",
"terminalCode": "pre-impreso",
"customerCode": "null"
},
{
"transactionId": "-",
"date": "2024-01-02T14:00:00Z",
"coupon": "1030BCeso2948",
"couponAction": "EXPIRATE",
"storeCode": "BC",
"terminalCode": "pre-impreso",
"customerCode": "null"
},
{
"transactionId": "-",
"date": "2024-01-02T14:00:00Z",
"coupon": "1030BCeso9411",
"couponAction": "EXPIRATE",
"storeCode": "BC",
"terminalCode": "pre-impreso",
"customerCode": "null"
},
{
"transactionId": "-",
"date": "2024-01-02T14:00:00Z",
"coupon": "1030BCeso5888",
"couponAction": "EXPIRATE",
"storeCode": "BC",
"terminalCode": "pre-impreso",
"customerCode": "null"
}
]
}
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. Requerido |
| companyId | Alfanumérico | Código de la compañía. Requerido |
| 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. Requerido |
| dateFrom | alfanumérico | Fecha de Inicio en formato YYYYMMDD. Opcional |
| dateTo | alfanumérico | Fecha de Final en formato YYYYMMDD. Opcional |
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. Requerido |
| code | Alfanumérico | Código del elemento que se quiere consultar. Requerido |
limit | Numérico | Cantidad de registros de movimientos a retornar (default: 5) con un máximo de 100.000 por consulta. Opcional |
dateFrom | Numérico | Fecha de Inicio en formato YYYYMMDD. Opcional |
dateTo | Numérico | Fecha de Final en formato YYYYMMDD. Opcional |
| 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. Opcional |
| 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. Opcional |
| timeFrom | Numérico | Hora de Inicio en formato HHmm. Opcional |
| timeTo | Numérico | Hora de final en formato HHmm. Opcional |
| 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. Opcional |
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 Creación en formato ISODATE | ||||||
| customerId | Alfanumérico | Id de cliente asociado al elemento | ||||||
| activation | Numérico | Fecha de activación | ||||||
isConsumed* | Booleano | Si ha sido consumida o no | ||||||
| status* | Alfanumérico | Estado actual del elemento | ||||||
| storeCode* | Alfanumérico | Código de Tienda de generación (si aplica) | ||||||
| terminalCode* | Alfanumérico | Código de terminal de generación (si aplica) | ||||||
| transactionId* | Alfanumérico | Código 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 registros que corresponden a la promoción 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 | definición de rangos de prefijos para ese elemento. |
code | Alfanumérico | Código del tipo |
customerValidation | Alfanumérico | Si es Nominado, el tipo de validación de customer (NO, API, FILE) |
description | Alfanumérico | Descripción 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ñía napse y con movimientos del 01/04/2020 al 31/04/2020 sin especificar limites con lo cual serán los 5 últimos 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": "Tarjetas Verdes",
"cardHistory": [
{
"date": "2021-03-19T23:30:15Z",
"createdAt": "2021-03-19T02:56:30Z",
"card": "-",
"cardAction": "SALE",
"storeCode": "1",
"terminalCode": "1",
"appliedPromotionDetails": [
{
"promotionName": "otorga Tarjetas 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 máximo 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. Requerido |
toDate | Numérico | Fecha de Final en formato YYYYMMDD. Requerido |
fromDate | Numérico | Fecha de Inicio en formato YYYYMMDD. Requerido |
customerCode | Alfanumérico | Identificador único del cliente. Requerido |
isConsume | Booleano | Si ha sido consumida o no. Requerido |
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 vía OAuth2.
La siguiente figura muestra el contenido del request de ejemplo:
Donde:
operation: valor getMaps para obtener el mapa solicitado. Requerido
companyId: identificación o código de empresa la cual realiza el request. Requerido
mapNumber: Numero de mapa solicitado. Requerido.
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 códigos 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 vía OAuth2.
La siguiente figura muestra el contenido del GET del ejemplo:
http://[SERVER]:[PORT]/promo/api/rest/promotions
<promoCoreRequest>
<operation>getPromotions</operation>
<companyId>2</companyId>
<params>
<promoCode>canje</promoCode>
<store>3</store>
<region>1</region>
</params>
</promoCoreRequest>
Donde:
Operation (obligatorio): valor getPromotions para obtener promociones.
companyId (obligatorio): identificación o código de empresa la cual realiza el request.
store (opcional): Tienda/s a la que pertenece la / las promociones.
region (opcional): Zona/s 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="64d140e6b29c1e1764334c1f" name="Promo Canje" code="canje" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="true" suggest="not" promotionType="1" promotionSubType="1" promotionApplicationForm="1"> <sets> <set name="64d140ecb29c1e1764334c23" type="item" /> </sets> <condition type="basic" name="Exists"> <parameter key="use-set" value="64d140ecb29c1e1764334c23" /> </condition> <benefits> <benefit instance="RedeemPointsBenefit" nro="64d14116b29c1e1764334c26"> <parameter key="displayMessage" value="Promo Canje" /> <parameter key="printerMessage" value="Promo Canje" /> <parameter key="TLOGMessage" value="Promo Canje" /> <parameter key="applicationMethod" value="resume" /> <parameter key="prorationMethod" value="proportional" /> <parameter key="applicationPriceType" value="benefited-price" /> <parameter key="name" value="64d140e6b29c1e1764334c1f" /> <parameter key="type" value="5" /> <parameter key="factor" value="1" /> <parameter key="recoveryValue" value="0" /> <parameter key="recoveryType" value="" /> <parameter key="prorateBCP" value="false" /> <applied-elements> <use-set name="64d140ecb29c1e1764334c23" /> </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 promoción. Requerido |
| companyId | Alfanumérico | Identificador único de la empresa. Requerido |
| promotionCode | Alfanumérico | código de la promoción que forma parte del mapa. No 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. |
| promotionType | String | Tipo al que pertenece la promoción. |
| promotionSubType | String | Subtipo al que pertenece la promoción. |
| promotionApplicationForm | String | Forma de aplicación de la promoción. |
la respuesta es el Json:
[
{
"mapVersion": "86",
"code": null,
"name": "Promo P1",
"conditionSimple": "Productos con Aplica a TODOS",
"conditionCombo": "",
"conditionDate": "",
"benefitTypeDescription": "<p>1.- Monetario</p><br/>",
"benefitClassDescription": "<p>1.- Descuento porcentaje</p><br/>",
"benefit": "<p>1.- Productos con Aplica a TODOS. El siguiente porcentaje (%) 100. Por cada unidad de Cantidad. Prorratear entre Participantes No. Valor de Recupero 0. Tipo de Recupero -. Balance -</p> ",
"promotionType": "1",
"promotionSubType": "1",
"promotionApplicationForm": "1"
}
]
Servicio De Consulta de Promoción
PROMO expone cuatro 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 o nombre 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.
Se puede acceder al servicio desde:
http://[Server]:[Port]/promo/api/rest/promotions
Las siguientes figuras muestran los contenidos de los request mencionados:
Promoción por Numero <promoCoreRequest> <operation>getPromotionsByNro</operation> <companyId>2</companyId> <nro>64d140e6b29c1e1764334c1f</nro> </promoCoreRequest> Promoción por Numero <?xml version="1.0" encoding="iso-8859-1"?> <promoCoreResponse> <ack>0</ack> <message value="" /> <promotions> <promotion nro="64d140e6b29c1e1764334c1f" name="Promo Canje" code="canje" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not" promotionType="1" promotionSubType="1" promotionApplicationForm="1"> <sets> <set name="64d140ecb29c1e1764334c23" type="item" /> </sets> <condition type="basic" name="Exists"> <parameter key="use-set" value="64d140ecb29c1e1764334c23" /> </condition> <benefits> <benefit instance="RedeemPointsBenefit" nro="64d14116b29c1e1764334c26"> <parameter key="displayMessage" value="Promo Canje" /> <parameter key="printerMessage" value="Promo Canje" /> <parameter key="TLOGMessage" value="Promo Canje" /> <parameter key="applicationMethod" value="resume" /> <parameter key="prorationMethod" value="proportional" /> <parameter key="applicationPriceType" value="benefited-price" /> <parameter key="name" value="64d140e6b29c1e1764334c1f" /> <parameter key="type" value="5" /> <parameter key="factor" value="1" /> <parameter key="recoveryValue" value="0" /> <parameter key="recoveryType" value="" /> <parameter key="prorateBCP" value="false" /> <applied-elements> <use-set name="64d140ecb29c1e1764334c23" /> </applied-elements> </benefit> </benefits> </promotion> </promotions> </promoCoreResponse> | Promoción por Código <promoCoreRequest> <operation>getPromotionsByCode</operation> <companyId>2</companyId> <promoCode>redes</promoCode> </promoCoreRequest> Promoción por Código <?xml version="1.0" encoding="iso-8859-1"?> <promoCoreResponse> <ack>0</ack> <message value="" /> <promotions> <promotion nro="64d0fb1db29c1e1764334bc6" name="Promo Redes" code="redes" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not" promotionType="1" promotionSubType="1" promotionApplicationForm="1"> <sets /> <benefits /> </promotion> </promotions> </promoCoreResponse> | Promocion por Numero de Beneficio <promoCoreRequest> <operation>getPromotionsByBenefitNro</operation> <companyId>2</companyId> <nro>6489c122a62e4343b821cc9d</nro> </promoCoreRequest> Promocion por Numero de Beneficio <?xml version="1.0" encoding="iso-8859-1"?> <promoCoreResponse> <ack>0</ack> <message value="" /> <promotions> <promotion nro="64cbfc85a62e430ec443b4d5" name="Promo Limites Clientes Cant. de aplicaciones" code="" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not" promotionType="1" promotionSubType="1" promotionApplicationForm="1"> <sets> <set name="64cbfc85a62e430ec443b4d2" type="item" /> </sets> <condition type="basic" name="Exists"> <parameter key="use-set" value="64cbfc85a62e430ec443b4d2" /> </condition> <benefits> <benefit instance="PercentageDiscount" nro="64cbfc85a62e430ec443b4d4"> <parameter key="displayMessage" value="Promo Limites Clientes Cant. de aplicaciones" /> <parameter key="printerMessage" value="Promo Limites Clientes Cant. de aplicaciones" /> <parameter key="TLOGMessage" value="Promo Limites Clientes Cant. de aplicaciones" /> <parameter key="applicationMethod" value="resume" /> <parameter key="prorationMethod" value="proportional" /> <parameter key="applicationPriceType" value="benefited-price" /> <parameter key="name" value="64cbfc85a62e430ec443b4d5" /> <parameter key="percent" value="50" /> <parameter key="unit" value="qty" /> <parameter key="prorateBCP" value="false" /> <parameter key="recoveryValue" value="0" /> <parameter key="recoveryType" value="" /> <applied-elements> <use-set name="64cbfc85a62e430ec443b4d2" /> </applied-elements> </benefit> </benefits> </promotion> </promotions> </promoCoreResponse> | Promocion por Nombre <promoCoreRequest> <operation>getPromotionsByName</operation> <companyId>2</companyId> <promoName>Promo Limite Clientes Cant. de Dinero</promoName> </promoCoreRequest> Promoción por Nombre ?xml version="1.0" encoding="iso-8859-1"?> <promoCoreResponse> <ack>0</ack> <message value="" /> <promotions> <promotion nro="64cbfc85a62e430ec443b4d1" name="Promo Limite Clientes Cant. de Dinero" code="" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not" promotionType="1" promotionSubType="1" promotionApplicationForm="1"> <sets> <set name="64cbfc85a62e430ec443b4ce" type="item" /> </sets> <condition type="basic" name="Exists"> <parameter key="use-set" value="64cbfc85a62e430ec443b4ce" /> </condition> <benefits> <benefit instance="PercentageDiscount" nro="64cbfc85a62e430ec443b4d0"> <parameter key="displayMessage" value="Promo Limite Clientes" /> <parameter key="printerMessage" value="Promo Limite Clientes" /> <parameter key="TLOGMessage" value="Promo Limite Clientes" /> <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="64cbfc85a62e430ec443b4d1" /> <parameter key="percent" value="50" /> <parameter key="unit" value="qty" /> <parameter key="prorateBCP" value="false" /> <parameter key="recoveryValue" value="0" /> <parameter key="recoveryType" value="" /> <applied-elements> <use-set name="64cbfc85a62e430ec443b4ce" /> </applied-elements> </benefit> </benefits> </promotion> </promotions> </promoCoreResponse> |
|---|
Donde:
- Operation (obligatorio): valor getPromotionsByNro, getPromotionsByCode, getPromotionsByBenefitNro o getPromotionsByName.
- 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-
- promoName(obligatorio): para una búsqueda mediante el nombre de la promoción.
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.
Si el código de la promoción no es único, en la respuesta se detallará el listado de todas las promociones que tengan ese código.
Caso contrario la respuesta mostrará la información de la promoción que corresponde a ese código.
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>
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. Requerido |
limit | Numérico | Cantidad de registros de movimientos a retornar con un máximo de 50.000 por consulta. Default: 25.Opcional |
| offset | Numérico | Registro desde el cual comenzar el conteo hasta "limit" registros. Default: 0. Opcional |
dateFrom | Numérico | Fecha de Inicio en formato YYYYMMDD. Requerido |
dateTo | Numérico | Fecha de Final en formato YYYYMMDD. Requerido |
transactionType | Alfanumérico | Opcionalmente se puede filtrar por tipo de Transacción: SALES o RETURN. Default: '' (Todas). Requerido |
| store | Alfanumérico | Código de Tienda por el cual se quiere filtrar. Default: '' (Todas). Opcional |
| pname | Alfanumérico | El nombre de la Promoción por el cual se desea filtrar. Default: '' (Todas). Requerido |
| pcode | Alfanumérico | El código de la Promoción por la cual se desea filtrar. Default: '' (Todas). Requerido |
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 Récords 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
PROMO expone un servicio que permite devolver la información referente al transaccional de limites para una determinada compañía.
Para ello deberá enviarse un GET a la siguiente URL: http://[SERVER]:[PORT]/promo/api/rest/limit/statements
Tiene tres parámetros de ingreso:
| Nombre | Valor |
|---|---|
| companyId | El código de la compañía. String. Requerido. |
| mapVersion | n° de mapa. Requerido |
| promoCode | Código de la promoción. String. Requerido |
Deberá validarse que el mapa consultado se encuentre activo en alguno de los motores conectados a la consola.
Ejemplo:
se obtendría un resultado como el siguiente:
Se espera obtener como respuesta un Json que informe los movimientos de limites que hayan tenido las promociones con limites definidas en el mapa consultado.
Los datos a informar deberán ser:
| Nombre | Valor |
|---|---|
| PromotionName | Nombre de la promoción que interviene en la transacción. |
| PromotionCode | Código de la promoción que interviene en la transacción. |
| benefitType | Tipo de Beneficio que otorga la promoción. |
| benefitClass | Clase de beneficio que otorga la transacción. |
| limitScope | Tipo de Límite que tiene el beneficio de la promoción |
| limitType | Indica el criterio por el cual se aplicará el límite. |
| store | Id de la tienda sobre las que se distribuyó el mapa donde se encuentra la promoción |
| customer | id de cliente que llevó a cabo la transacción. |
| limitOriginalValue | Valor original del límite |
| limitCurrentValue | Valor actual del límite |
| storeCode | código de la tienda donde se llevó a cabo la transacción |
| date | día en que se llevó a cabo la transacción |
| transaction | id de la transacción que aplicó esa promoción con límite |
| operation | Tipo de operación |
| store | Id de la tienda donde se llevó a cabo la transacción |
| terminal | Terminal donde se llevó a cabo la transacción. |
| customer | Id del cliente que llevó a cabo la transacción |
| initialValue | valor inicial de la transacción |
| transactionValue | valor del limite aplicado en la transacción |
| finalValue | valor final del limite aplicado en la transacción. |
Ej de consulta con companyId y mapVersion:
[
{
"promotionName": "PromoLimite",
"promotionCode": null,
"benefitType": "Monetario",
"benefitClass": "Descuento porcentaje",
"limitScope": "General",
"limitType": "Cantidad de productos beneficiados",
"store": "",
"customer": "",
"limitOriginalValue": "3.00",
"limitCurrentValue": "1.00",
"storeCode": "-",
"detail": [
{
"date": "09/11/2022 10:37",
"transaction": "napse_napse_1_20221109120000",
"operation": "Venta",
"store": "napse",
"terminal": "1",
"customer": "",
"initialValue": "0.00",
"transactionValue": "1.00",
"finalValue": "1.00"
}
]
}
]
Ej con companyId inexistente:
Ej. con un mapa invadido:
otros errores:
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"
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. Requerido |
catalog | identificador del catálogo | alfanumérico. Requerido |
| params | Parámetros que dependerán del catálogo | Listado de objetos de tipo clave, valor. Cada catalogo puede tener sus parámetros específicos, pero como valor genérico tenemos:
[...] "params": [ [...] cuando se importa un nuevo catálogo, el usuario que realizó la modificación es informado en el log de la consola:
Importante No aplica a elementos de fidelidad y asignación de convenios. Requerido |
| items | Registros a importar | Colección de objetos dependientes de cada catálogo Atributos dinamicos. Para el Catalogo de Clientes (catalogCustomer.catalog) 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.3) Ejemplo de catalogItem con Atributos dinámicos. {
"companyId": "napse",
"catalog": "catalogCustomer",
"params": [],
"items": [{
"operation": "I",
"code":"949450",
"name":"John",
"lastName":"Promo",
"gender":"2",
"birthDate":"03-05-1959",
"identificationType":"01",
"identifier":"4688779900",
"identificationExpiration":"31-12-2030",
"nacionality":"Arg",
"email":"[email protected]",
"customerType":"111",
"address":"Av.Livertad 123",
"addressCountry":"100",
"addressState":"200",
"addressCity":"300",
"addressPostalCode":"9999",
"phone":"457896203",
"isActive":"true",
"prof":"Ingeniero"
}
]
}
En el ejemplo anterior "prof" es el atributo dinámico creado para importar las profesiones de los clientes. Requerido |
Cada uno de los ítems 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. Requerido |
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 | código 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.
Los catálogos a importar son:
Un cliente está conformado por los siguientes datos.
(Datos como gender, identificationType, customerType, addressCountry, addressState, y addressCity, corresponden al código de cada uno de ellos y deberán importarse previamente antes de realizar cualquier operación sobre un cliente. En el caso particular de addressCountry, addressState, y addressCity, deberán importarse en ese orden debido a que se validará que una provincia/estado esté dentro de un país, y que una ciudad esté dentro de una provincia.).
A partir de la versión 7.3.0 se agregaron tres atributos al elemento Cliente:
- Cumpleaños
- Años
- Datos Incompletos
| Campo | Tipo de dato | Observaciones |
|---|---|---|
| code | string | Corresponde al código que se le asignara al cliente en Promo. (requerido) |
| name | string | Nombre de cliente. (requerido) |
| lastName | string | Apellido del cliente. (requerido) |
| gender | string | Genero del cliente (en caso de "Validar catálogos relacionados al catálogo de clientes" este en "true", el dato definido en este campo deberá coincidir con alguno de los códigos de género "catalogGender" previamente cargados.) Opcional |
| birthDate | string | Fecha de nacimiento del cliente. Formato: año-mes-día siendo el año de cuatro dígitos, y el mes y el día de dos dígitos |
| identificationType | string | Tipo de identificación del cliente. (en caso de "Validar catálogos relacionados al catálogo de clientes" este en "true", el dato definido en este campo deberá coincidir con alguno de los códigos de tipo de identificación "catalogIdType" previamente cargados.). Opcional |
| identifier | string | Numero de identificación del cliente. (requerido) |
| identificationExpiration | string | Fecha de expiración de la identificación del cliente. Opcional |
| nacionality | string | Nacionalidad del cliente. Opcional |
| string | e-Mail del cliente. Opcional | |
| customerType | string | Tipo de cliente (requerido) / / (en caso de "Validar catálogos relacionados al catálogo de clientes" este en "true", el dato definido en este campo deberá coincidir con alguno de los códigos de tipo cliente "catalogIdType" previamente cargados.). Opcional |
| address | string | Dirección del cliente. Opcional |
| addressCountry | string | País del cliente. (en caso de "Validar catálogos relacionados al catálogo de clientes" este en "true", el dato definido en este campo deberá coincidir con alguno de los códigos de Pais "catalogCoutry" previamente cargados.). Opcional |
| addressState | string | Provincia de residencia del cliente. (en caso de "Validar catálogos relacionados al catálogo de clientes" este en "true", el dato definido en este campo deberá coincidir con alguno de los códigos de Provincia "catalogState" previamente cargados.). Opcional |
| addressCity | string | Ciudad de residencia del cliente. (en caso de "Validar catálogos relacionados al catálogo de clientes" este en "true", el dato definido en este campo deberá coincidir con alguno de los códigos de Ciudad "catalogCity" previamente cargados.). Opcional |
| addressPostalCode | string | Código Postal. Opcional |
| phone | string | Teléfono. Opcional |
| isActive | booleano | Indicara si al momento del alta el cliente estará Activo o Inactivo. Deberá definirse como true o false. Opcional |
| segments | string | Segmento/s asociado al cliente. Opcional |
| birthday | booleano | Indicará si al momento del alta del cliente es su cumpleaños. Deberá definirse como true o false. Opcional |
| Age | integer | Indicará la edad del cliente. Acepta valores nulos o cero. Opcional |
| incompleteData | booleano | Indicará si el cliente tiene datos incompletos. Deberá definirse como true o false. Opcional |
{"companyId":"napse",
"catalog":"CatalogCustomer",
"params":[],
"items":[{
"operation":"I",
"name":"Manuel Jose",
"lastName":"Mendoza",
"code":"95540610",
"identifier":"95540610",
"addressCountry":"arg",
"identificationExpiration":"2050-01-01",
"address":"diagonal 12 2233",
"gender":"h",
"identificationType":"le",
"addressState":"bsas",
"isActive":"true",
"birthDate":"2001-01-01",
"segments":"SEG1,SEG2",
"addressPostalCode":"",
"customerType":"STANDARD",
"phone":"",
"nacionality":"argentino",
"email":"",
"addressCity":"tig",
"birthday":true,
"age": 36,
"incompleteData":false
}
]
}
Si los atributos del elemento cliente: cumpleaños y datos incompletos tienen valor null; se importarán como false.
Cuando desde la consola se indique que deben de Validar catálogos relacionados al catálogo de clientes, será requerida la carga de los catálogos relacionados previo a la carga del catalogo de cliente.
Se importan entonces las entidades relacionadas previo a la importación de los clientes.
Catálogo IDTYPE. Este catálogo define los tipos de documento o identificación válidos.
{
"companyId": "napse",
"catalog": "CatalogIdType",
"params": [],
"items": [
{
"code": "dni",
"description": "Documento de identidad",
"operation": "I"
},
{
"code": "le",
"description": "Libreta de enrolamiento",
"operation": "I"
}
]
}
Catálogo GENDER. Este catálogo define los tipos de género válidos.
{
"companyId": "napse",
"catalog": "CatalogGender",
"params": [],
"items": [
{
"code": "M",
"description": "Male",
"operation": "I"
},
{
"code": "F",
"description": "Female",
"operation": "I"
}
]
}
Catálogo CUSTOMERTYPE. Este catálogo define los tipos de clientes válidos
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogCustomerType",
"params": [],
"items": [
{
"code": "vip",
"description": "Cliente vip",
"operation": "I"
},
{
"code": "gold",
"description": "Cliente gold",
"operation": "I"
},
{
"code": "silver",
"description": "Cliente silver",
"operation": "I"
}
]
}
Importación de nuevos clientes.
Una vez realizadas las importaciones anteriores, y considerando sus códigos, se pueden realizar altas, modificaciones, y eliminaciones de clientes.
Por ej. en este caso se dan de alta dos clientes:
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogCustomer",
"params": [],
"items": [
{
"code": "cod1",
"name": "Alberto",
"lastName": "Pérez",
"gender": "M",
"birthDate": "1950-01-01",
"identificationType": "le",
"identifier": "11112222",
"identificationExpiration": "2050-01-01",
"nacionality": "argentino",
"email": "[email protected]",
"customerType": "vip",
"address": "diagonal 12 2233",
"addressCountry": "ar",
"addressState": "bsas",
"addressCity": "tig",
"addressPostalCode": "2222",
"phone": "11111111",
"isActive": "true",
"birthday":false,
"age": 73,
"incompleteData":false,
"operation": "I"
},
{
"code": "cod2",
"name": "Ángela",
"lastName": "Gonzales",
"gender": "F",
"birthDate": "1960-01-01",
"identificationType": "dni",
"identifier": "99998888",
"identificationExpiration": "2050-01-01",
"nacionality": "argentina",
"email": "[email protected]",
"customerType": "gold",
"address": "diagonal 50 2211",
"addressCountry": "ar",
"addressState": "cor",
"addressCity": "lm",
"addressPostalCode": "5050",
"phone": "55555555",
"isActive": "true",
"birthday":false,
"age": 63,
"incompleteData":"",
"operation": "I"
}
]
}
Importante
Cuando se agrega un atributo de elemento a un cliente; éste se debe agregar en el Json al importar el catálogo de cliente.
{
"companyId": "2",
"catalog": "catalogCustomer",
"params": [],
"items": [{
"operation": "I",
"code":"8",
"name":"John",
"lastName":"Promo",
"gender":"h",
"birthDate":"03-05-1959",
"identificationType":"dni",
"identifier":"4688779900",
"identificationExpiration":"31-12-2030",
"nacionality":"Arg",
"email":"[email protected]",
"customerType":"EMPLEADO",
"address":"Av.Livertad 123",
"addressCountry":"arg",
"addressState":"bsas",
"addressCity":"tig",
"addressPostalCode":"9999",
"phone":"457896203",
"isActive":"true",
"segments":"4650",
"birthday":false,
"age": 64,
"incompleteData":"",
"condiva":"Responsable Inscripto"
}]
}
Eliminación y actualización de clientes.
En el siguiente ejemplo, se elimina el primer cliente (campo operation en R) y se actualiza el segundo cliente (campo operation en U) cambiando el email y el teléfono
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogCustomer",
"params": [],
"items": [
{
"code": "cod1",
"name": "Alberto",
"lastName": "Pérez",
"gender": "M",
"birthDate": "1950-01-01",
"identificationType": "le",
"identifier": "11112222",
"identificationExpiration": "2050-01-01",
"nacionality": "argentino",
"email": "[email protected]",
"customerType": "vip",
"address": "diagonal 12 2233",
"addressCountry": "ar",
"addressState": "bsas",
"addressCity": "tig",
"addressPostalCode": "2222",
"phone": "11111111",
"isActive": "true",
"birthday":"",
"age": 73,
"incompleteData":"",
"operation": "R"
},
{
"code": "cod2",
"name": "Ángela",
"lastName": "Gonzales",
"gender": "F",
"birthDate": "1960-01-01",
"identificationType": "dni",
"identifier": "99998888",
"identificationExpiration": "2050-01-01",
"nacionality": "argentina",
"email": "[email protected]",
"customerType": "gold",
"address": "diagonal 50 2211",
"addressCountry": "ar",
"addressState": "cor",
"addressCity": "lm",
"addressPostalCode": "5050",
"phone": "90909090",
"isActive": "true",
"birthday":"",
"age":"",
"incompleteData":"",
"operation": "U"
}
]
}
Borrado de atributos en catálogos en PROMO
La aplicación 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", "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:
Se envía el mensaje por Postman:
{
"companyId" = "napse",
"catalog" = "CatalogChannel",
"params":[],
"items": [
{
"code"= "1",
"operacion" = "D"
}
]
}
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"
}
]
}
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. Requerido |
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:
Ej:
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.
Importante
Las promociones deben estar en estado Completa para poder importarlas a través de este servicio. Promo limita a 3000 la cantidad de condiciones simples que se puden agregar por promoción.
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. Requerido |
promotions | Conjunto de promociones a actualizar, pueden ser nuevas, actualizaciones o promociones que deseamos inactivar. Requerido |
| operation | I: Insertar / U: Actualizar / R: Cancelación. Requerido |
| name | Nombre de la promoción. Requerido |
code | Código univoco de la promoción. Requerido |
| 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"
}
Para cancelar una promoción, a través del servicio Rest se debe informar:
- Nombre de la Promoción
{
"companyId": "1",
"promotions": [
{
"operations": "R",
"name": "Promo4"
}
]
}
La respuesta es:
{
"status": "Información Recibida OK",
"description": "La importación de promociones será procesada"
}
2. Código de la Promoción
{
"companyId": "1",
"promotions":[
{
"operation": "R",
"code": "Promo1"
}
]
}
La respuesta es:
{
"status": "Información Recibida OK",
"description": "La importación de promociones será procesada"
}
3. Código y Nombre de la Promoción
{
"companyId": "1",
"promotions":[
{
"operation": "R",
"code":"Promo7",
"name":"Promo7"
}
]
}
La respuesta es:
{
"status": "Información Recibida OK",
"description": "La importación de promociones será procesada"
}
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"
}
Importante
Si se desea cancelar y/o actualizar una promoción cuyo código se repite en otras promociones; se debe tener en cuenta informar el nombre de la que se desea cancelar y /o actualizar.
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" tal como se muestra en el siguiente 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):
{
"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:
Al importar una promoción, la misma se importará con el workflow general por default.
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 el servicio Rest:
Request:
{
"status":"Informacion recibida OK",
"description":"La importacion de Promociones será procesada"
}
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 (Módulo de Administración/Atributos de cabecera)::
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:
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:8073/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 | CatalogExclusionDates | string | Catálogo de Fechas de Exclusión - 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": "3",
"promotionName": "Promo Puntos I",
"exclusionDates": ["2023-07-10","2023-07-11","2023-07-12"],
"operation": "I" //Tipo de operación asociada a I (insertar), U (actualizar) y R (remover)
},
{
"storeCode": "3",
"promotionName": "Promo Puntos I",
"exclusionDates": ["2023-07-13"],
"operation": "U"
},
{
"storeCode": "3",
"promotionName": "Promo Puntos I",
"exclusionDates": ["2023-07-13"],
"operation": "R"
}
]
}
{
"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."
}
}
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": "3",
"promotionName": "Promo A",
"exclusionDates": ["2023-07-10","2023-07-11","2023-07-12"],
"operation": "I"
}
]
}
{
"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."
}
}
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 Puntos I",
"exclusionDates": ["2023-07-14"],
"operation": "U"
}
]
}
{
"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."
}
}
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 Puntos I",
"exclusionDates": ["2023-07-14"],
"operation": "R"
}
]
}
{
"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."
}
}
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": "3",
"promotionName": "",
"exclusionDates": ["2023-07-10"],
"operation": "R"
}
]
}
Respuesta del servicio
Si la solicitud ha sido exitosa, se podrá visualizar la siguiente respuesta (Interfaz Rest):
{
"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
{
"status": "400",
"description": "CatalogExclusionDates",
"detail": {
"result": "error",
"detail": "El código de compañía napse no pertenece a una compañía existente."
}
}
Servicio de Canje de Puntos por Catalogo
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.
http://localhost:8073/promo/api/rest/catalogs
Siguiendo el formato especificado anteriormente tendremos:
| Campo | Valor |
|---|---|
| companyId | El código de la compañia correspondiente. Requerido. |
| catalog | "CatalogRedeemBenefit". No se debe modificar. Requerido. |
params | Un listado vacío. No se debe modificar. Requerido. |
| items | Un listado con cada item del catálogo de Canje de puntos. Requerido. |
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": "3",
"code": "10",
"points": "10.5",
"discountValue":"15" ,
"discountType": "perc",
"operation": "I"
},
{
"store": "3",
"code": "20",
"points": "20.5",
"discountValue":"20" ,
"discountType": "fix",
"operation": "I"
},
{
"store": "3",
"code": "30",
"points": "50",
"discountValue":"25" ,
"discountType": "nprice",
"operation": "I"
}
]
}
{
"status": "200",
"description": "CatalogRedeemBenefit",
"detail": {
"result": "ok",
"detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
}
}
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 fidelidad de un cliente, un convenio y su monto
Esta operación realiza la asignación de tarjeta, cliente, convenio, y monto. Debe existir previamente la tarjeta (activa o inactiva), un convenio activo, y el cliente, en caso de no existir, se da de alta. En relación al monto, se le puede asignar o no un operador adelante del monto; especificando el operador + suma un valor al monto que la tarjeta tiene; especificando el operador - resta saldo al monto que la tarjeta tiene; si no se pone operador reemplaza el monto que la tarjeta tiene (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.......}
]
}
Donde:
| Campo | Descripción |
|---|---|
| params | cardType: Tipo de elemento de fidelidad a importar que sera validado. Requerido contract: codigo de convenio al que pertenecen estos elementos/clientes. Requerido |
operation | I: Inserción / U: Actualización / R: Eliminación. Requerido |
id |
|
customer |
|
amount |
|
name | Nombre del Cliente. Cadena libre. Requerido |
surname | Apellido. Cadena libre. Requerido |
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 identificación (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin. Requerido |
identifier | Numero de Identificación del Cliente. Requerido |
idDate | Fecha de Expiración de la identificación. Cadena en formato "yyyyMMdd". Más Información del formato |
nacionality | Nacionalidad. Cadena Libre. |
Dirección 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 | Código Postal |
phone | Teléfono |
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"
}]
}
Servicio de Importación de Segmentos
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
Para cualquier tipo de Programa de Objetivos, si un cliente no ha consumido durante un período igual o mayor a la frecuencia máxima y por el proceso ha sido quitado del segmento en que se encontraba; puede ser restituido al mismo segmento, a través del servicio Rest.
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 Transferencia de saldos entre Elementos de Fidelidad
Transferencia parcial
Se puede realizar una transferencia parcial desde un elemento de fidelidad a otro.
Importante
Para permitir una transferencia parcial, el tipo de elemento de fidelidad debe tener seleccionada esta opción.
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.
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....
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**
Modificar Fecha de vigencia de cupones:
Se debe hacer la consulta en: POST http://{{SERVER}}:{{PORT}}/promo/api/rest/coupon/admin
Para la modificación de la vigencia de cupones se debe enviar bajo la operación "UPDATE" (solo se puede realizar con esta operación) un nuevo campo dentro del listado ítems: campo validTo.
Ej:
{
"companyId": "{{COMPANY}}",
"params": [],
"items": [
{
"operation": "UPDATE",
"barcode": "3335",
"type": "tipo123",
"email": "",
"amount": "",
"customerId": ""
"validTo": "2022-01-15"
}
]
}
La respuesta será:
{
"status": 200,
"description": "rest::couponAdmin",
"detail": {
"result": "ok",
"detail": "",
"updated": 0,
"ignored": 0,
"inserted": 0,
"removed": 0,
"errors": 1,
"processed": 1,
"errorDetails": [ <--------- Caso de error
{
"rec": 1,
"code": "9520",
"info": null
}
],
"successDetails": [{ <--------- Caso satisfactorio
{
"rec": 1,
"code": "12345678"
}
}]
}
}
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 :
http://localhost:8073/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": "2",
"catalog": "CatalogCustomer",
"params": [],
"items": [
{
"code": "8",
"name": "Marcela",
"lastName": "Sanchez",
"gender": "m",
"birthDate": "1972-12-07",
"identificationType": "dni",
"identifier": "21563286",
"identificationExpiration": "2050-01-01",
"nacionality": "arg",
"email": "[email protected]",
"customerType": "EMPLEADO",
"address": "calle1",
"addressCountry": "arg",
"addressState": "bsas",
"addressCity": "tig",
"addressPostalCode": "3053",
"phone": "46517131",
"isActive": "true",
"operation": "I"
},
{
"code": "1",
"name": "Juan",
"lastName": "Perez",
"gender": "m",
"birthDate": "1900-05-31",
"identificationType": "dni",
"identifier": "12345",
"identificationExpiration": "2050-01-01",
"nacionality": "arg",
"email": "[email protected]",
"customerType": "EMPLEADO",
"address": "Avda. Libertador 3400",
"addressCountry": "arg",
"addressState": "bsas",
"addressCity": "tig",
"addressPostalCode": "2000",
"phone": "1555555555",
"isActive": "true",
"operation": "U"
},
{
"code": "13",
"name": "JOAQUIN",
"lastName": "Torres",
"gender": "m",
"birthDate": "1972-03-23",
"identificationType": "dni",
"identifier": "20587777",
"identificationExpiration": "2050-01-01",
"nacionality": "arg",
"email": "[email protected]",
"customerType": "EMPLEADO",
"address": "diagonal 12 2233",
"addressCountry": "arg",
"addressState": "bsas",
"addressCity": "tig",
"addressPostalCode": "3053",
"phone": "46667134",
"isActive": "true",
"operation": "R",
"autoCard":"Tipo1"
}
]
}
{
"status": 200,
"description": "catalogCustomer",
"detail": {
"result": "ok",
"detail": "[]",
"updated": 1,
"ignored": 0,
"inserted": 1,
"removed": 1,
"errors": 0,
"processed": 3,
"errorDetails": [],
"successDetails": []
}
}
También se puede administrar clientes a través del servicio de Importación de Catálogos/Catálogos de Clientes
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, utilizando el método POST:
http://localhost:8073/promo/api/rest/limits/import
El Json para insertar límites será:
{
"companyId":"2",
"limits": [
{
"operation":"I",
"promotionName":"Promo P1",
"benefitId": "64ddfc2d92889f36286c9d8f",
"limitId": "",
"limitScope":"RETAILER",
"storeCode": "3",
"description": "",
"limitPeriod":"DAY",
"numberDays":"2",
"limitTypeCode": "benefiedProductCount",
"value": "4"
},
{
"operation":"I",
"promotionName":"Promo P1",
"benefitId": "64ddfc2d92889f36286c9d8f",
"limitId": "",
"limitScope":"STORE",
"storeCode": "3",
"description": "",
"limitPeriod":"DAY",
"numberDays":"5",
"limitTypeCode": "benefiedProductCount",
"value": "2"
}
]
}
{
"status": "Información Recibida OK",
"description": "La importación de limites será procesada"
}
Donde:
Campo | Descripción | Tipo de Dato | Valores posibles |
|---|---|---|---|
operation |
| string | I(Insert), U(Update), R (Remove) |
| promotionName | Nombre de la promoción, en la que se va a ingresar el límite o si ya existe se va a modificar o remover | string | |
| benefitId | Identificador único del beneficio en el cual se va a ingresar, modificar o remover el/los limite/s | string | |
| limitdId | Identificador único del limite que se quiere modificar o remover. Sólo se informa cuando la operacion sea U o R | string | |
| limitScope | Tipo de límite | string | General, Tienda, Cliente |
| storeCode | Código de la tienda. Sólo se informa si el tipo de límite seleccionado fue por tienda | ||
| description | Descripción del limite | string | |
| limitPeriod | Período a contabilizar del límite | string | Indefinido, Día |
| numerDays | Cantidad de días si el período a contabilizar seleccionado fue días | integer | |
| limitTypeCode | Tipo de variable a la que se va a aplicar el limite. | string |
|
| value | valor del limite | double |
El json para modificar límites será:
{
"companyId":"2",
"limits": [
{
"operation":"U",
"limitId": "64ae87ceab7b185554057c7c",
"limitScope":"RETAILER",
"storeCode": "3",
"description": "",
"limitPeriod":"DAY",
"numberDays":"2",
"limitTypeCode": "benefiedProductCount",
"value": "5"
}
]
}
{
"status": "Informacion Recibida OK",
"description": "La importación de limites será procesada"
}
El json para eliminar límites será:
{
"companyId":"napse",
"limits": [
{
"operation":"R",
"limitId": "64ae87ceab7b185554057c7c"
}
]
}
{
"status": "Informacion Recibida OK",
"description": "La importación de limites será procesada"
}
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.