PROMO - Manual de Integración 7.0 - 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 basicamente tres herramientas que son de dominio público:
- CURL (https://curl.haxx.se/) "command line tool and library for transferring data with URLs": Es una herramienta por linea de comandos para enviar/recibir mensajes http.
- POSTMAN (https://www.postman.com) "The Collaboration Platform for API Development": Herramienta Grafica para la creación, envio y recepción de mensajes.
- SOAPUI (https://www.soapui.org/) "Accelerating API Quality Through Testing": Otra herramienta Gráfica para la definición, envio y recepción de mensajes.
Seguridad: Autenticación de Sistemas Externos con los Servicios
Antes de consumir un servicio provisto por Promo, deberá realizarse un Proceso de autenticación OAuth2. El mismo consiste en obtener un TOKEN que luego debe ser enviado en los subsiguientes mensajes.
Entonces como primer paso a comenzar la comunicación con los servicios de Promo, el sistema externo debe realizar el proceso descripto aquí.
Primero deberá de solicitarse el Token de acceso, que utilizando CURL el comando sería:
curl –v –X POST –u my-client: -d "grant_type=password" –d "username=sender" –d "password=mate" –d "scope=read" http://localhost:8080/promo/oauth/token
Donde "http://localhost:8080/promo" debe ser cambiado por la URL donde se encuentra la consola de Promo.
La respuesta ejemplo se puede ver en la siguiente ventana:
Una vez obtenido el token, se deberá enviar en las subsiguientes solicitudes. Por ejemplo realizamos un GET con la herramienta CURL:
curl -X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8" -H "Content-type: application/json" -H "Accept: application/json" "http://localhost:8080/promo/api/rest/customer?code=1"
De la misma forma, 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
5. Luego presionar el botón "Get New Access Token"
6. 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": "64415ac9a62e433e0436b84b",
"code": "2",
"name": "sofia",
"lastName": "gonzalez",
"gender": "m",
"birthDate": "1950-05-05T03:00:00Z",
"identificationType": "le",
"identifier": "222233",
"identificationExpiration": "2060-06-06T03:00:00Z",
"nacionality": "br",
"email": "[email protected]",
"customerType": "frecuente",
"address": "calle 2",
"addressCountry": "arg",
"addressState": "bsas",
"addressCity": "tig",
"addressPostalCode": "2",
"phone": "1566666666",
"isActive": true,
"segments": "",
"companyId": "2",
"creationDate": "2023-04-20T15:31:21Z",
"cards": [
{
"_id": "649c76f7b29c1e11cc02cc2a",
"amount": 200000.0,
"code": "1000000019",
"companyId": "2",
"created": "2023-06-28T18:07:51Z",
"isConsumed": false,
"status": "ENABLED",
"storeCode": "BLC",
"terminalCode": "1_1-100",
"transactionId": "BLC_202306281507861",
"type": "1",
"version": 3,
"customerId": "2",
"contractCode": "1",
"activation": "2023-06-28T18:20:09Z",
"typeName": "Tipo 1"
},
{
"_id": "64d2acb914e33806ecc54531",
"amount": 6000.0,
"code": "1000000048",
"companyId": "2",
"created": "2023-08-08T20:59:37Z",
"isConsumed": false,
"status": "ENABLED",
"storeCode": "BLC",
"terminalCode": "1_1-100",
"transactionId": "BLC_202308081759646",
"type": "1",
"version": 6,
"activation": "2023-08-08T21:00:41Z",
"customerId": "2",
"contractCode": "1",
"lastPurchaseDate": "2023-08-11T18:19:00Z",
"typeName": "Tipo 1"
}
],
"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"
Consulta de Datos de Clientes
PROMO expone un servicio que permite consultar tarjetas a la BBDD utilizando el ID de cliente. Junto con los campos del cliente, también se devuelve un listado de Tarjetas y Cupones, elementos de Fidelidad.
Si no tiene elementos de Fidelidad, se devolverán las Tarjetas o Cupones vacías.
El código de la consulta debe ser exacto y solo se devolverá un resultado, si es que el cliente existe.
El formato en que se responde es en JSON.
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. 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. |
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.
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&withSalesInfo=true
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.-
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.
La URL es:
http://[SERVER]:[PORT]/promo/api/rest/cupon
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 de la tarjeta la cual 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. Requerido |
dateFrom | Numérico | Fecha de Inicio en formato YYYYMMDD. Si no se especifica code. Opcionales |
dateTo | Numérico | Fecha de Final en formato YYYYMMDD. Si no se especifica code. Opcionales |
couponAction | Alfanumérico | Código de Operación que se quiere consultar. Si no se especifica code. Por defecto son todas las operaciones. Los valores disponibles son: CREATE, REDEEM, VOID. Opcionales |
| timeFrom | Numérico | (desde 7EP2) Hora de Inicio con formato HHmm. Opcionales |
| timeTo | Numérico | (desde 7EP2) Hora de Fin con formato HHmm. Opcionales |
| 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. Opcionales |
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 1030BC0049405
http://localhost:8070/promo/api/rest/coupon?companyId=2&barcode=1030BC0049405
La misma pero utilizando CURL:
curl -X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8" -H "Content-type: application/json" -H "Accept: application/json" http://localhost:8070/promo/api/rest/coupon?companyId=napse&barcode=1030BC0049405
Obteniéndose la siguiente respuesta:
Ejemplo {
"_id": "64b16801ab7b18202cfee567",
"barcode": "1030BC0049405",
"companyId": "napse",
"consumed": false,
"couponFormat": "PRE_PRINTED",
"couponStatus": "DISABLED",
"couponType": "4",
"issuedDate": "2023-07-14T15:21:37Z",
"maxUsageTimes": 1,
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221326",
"usedTimes": 0,
"validFrom": "2023-04-20T03:00:00Z",
"validTo": "2023-05-21T02:59:59Z",
"version": 0,
"amount": null,
"customerId": null,
"emitPromotion": null,
"generatedHTML": null,
"lastRedeemedDate": null,
"redeemPromotion": null,
"couponHistory": [
{
"couponAction": "CREATE",
"date": "2023-07-14T15:21:37Z",
"storeCode": "BC"
}
]
}
|
En caso de que el cliente no exista en la base la respuesta se devolverá vacía.-
EJEMPLO 2: Se solicitan todos los cupones creados en el periodo 01/01/2023-14/07/2023, para la empresa napse con un limite de 100.000 registros.
http://localhost:8070/promo/api/rest/cupon?dateFrom=20230101&dateTo=20230621&companyId=2&limit=10000&couponAction=CREATE
(curl -X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8" -H "Content-type: application/json" -H "http://localhost:8070/promo/api/rest/coupon?dateFrom=20230101&dateTo=20230714&companyId=napse&limit=100000&couponAction=CREATE')
La respuesta será del tipo:
{
"couponHistory": [
{
"coupon": "1030BC0040006",
"couponAction": "CREATE",
"date": "2023-04-20T15:24:00Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202304201223837"
},
{
"coupon": "1030BC0046473",
"couponAction": "CREATE",
"date": "2023-04-20T15:24:00Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202304201223837"
},
{
"coupon": "1030BC0042949",
"couponAction": "CREATE",
"date": "2023-04-20T15:24:00Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202304201223837"
},
{
"coupon": "1030BC0049412",
"couponAction": "CREATE",
"date": "2023-04-20T15:24:00Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202304201223837"
},
{
"coupon": "1030BC0045889",
"couponAction": "CREATE",
"date": "2023-04-20T15:24:00Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202304201223837"
},
{
"coupon": "1030BC0042352",
"couponAction": "CREATE",
"date": "2023-04-20T15:24:00Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202304201223837"
},
{
"coupon": "1030BC0048828",
"couponAction": "CREATE",
"date": "2023-04-20T15:24:00Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202304201223837"
},
{
"coupon": "1030BC0045292",
"couponAction": "CREATE",
"date": "2023-04-20T15:24:00Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202304201223837"
},
{
"coupon": "1030BC0041768",
"couponAction": "CREATE",
"date": "2023-04-20T15:24:00Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202304201223837"
},
{
"coupon": "1030BC0048231",
"couponAction": "CREATE",
"date": "2023-04-20T15:24:00Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202304201223837"
},
{
"coupon": "1030BC0044707",
"couponAction": "CREATE",
"date": "2023-06-21T14:05:39Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202306211105635"
},
{
"coupon": "1030BC0041171",
"couponAction": "CREATE",
"date": "2023-06-21T14:05:39Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202306211105635"
},
{
"coupon": "1030BC0047647",
"couponAction": "CREATE",
"date": "2023-06-21T14:05:39Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202306211105635"
},
{
"coupon": "1030BC0044110",
"couponAction": "CREATE",
"date": "2023-06-21T14:05:39Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202306211105635"
},
{
"coupon": "1030BC0040587",
"couponAction": "CREATE",
"date": "2023-06-21T14:05:39Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202306211105635"
},
{
"coupon": "1030BC0047050",
"couponAction": "CREATE",
"date": "2023-06-21T14:05:39Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202306211105635"
},
{
"coupon": "1030BC0043526",
"couponAction": "CREATE",
"date": "2023-06-21T14:05:39Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202306211105635"
},
{
"coupon": "1030BC0049993",
"couponAction": "CREATE",
"date": "2023-06-21T14:05:39Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202306211105635"
},
{
"coupon": "1030BC0046466",
"couponAction": "CREATE",
"date": "2023-06-21T14:05:39Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202306211105635"
},
{
"coupon": "1030BC0042932",
"couponAction": "CREATE",
"date": "2023-06-21T14:05:39Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202306211105635"
},
{
"coupon": "1040BC0060003",
"couponAction": "CREATE",
"date": "2023-06-21T14:34:59Z",
"storeCode": "BC",
"terminalCode": "6",
"transactionId": "BC_202306211134940"
},
{
"coupon": "1040BC0066470",
"couponAction": "CREATE",
"date": "2023-06-21T14:34:59Z",
"storeCode": "BC",
"terminalCode": "6",
"transactionId": "BC_202306211134940"
},
{
"coupon": "1040BC0062946",
"couponAction": "CREATE",
"date": "2023-06-21T14:34:59Z",
"storeCode": "BC",
"terminalCode": "6",
"transactionId": "BC_202306211134940"
},
{
"coupon": "1040BC0069419",
"couponAction": "CREATE",
"date": "2023-06-21T14:34:59Z",
"storeCode": "BC",
"terminalCode": "6",
"transactionId": "BC_202306211134940"
},
{
"coupon": "1040BC0065886",
"couponAction": "CREATE",
"date": "2023-06-21T14:34:59Z",
"storeCode": "BC",
"terminalCode": "6",
"transactionId": "BC_202306211134940"
},
{
"coupon": "1040BC0062359",
"couponAction": "CREATE",
"date": "2023-06-21T14:34:59Z",
"storeCode": "BC",
"terminalCode": "6",
"transactionId": "BC_202306211134940"
},
{
"coupon": "1040BC0068825",
"couponAction": "CREATE",
"date": "2023-06-21T14:34:59Z",
"storeCode": "BC",
"terminalCode": "6",
"transactionId": "BC_202306211134940"
},
{
"coupon": "1040BC0065299",
"couponAction": "CREATE",
"date": "2023-06-21T14:34:59Z",
"storeCode": "BC",
"terminalCode": "6",
"transactionId": "BC_202306211134940"
},
{
"coupon": "1040BC0061765",
"couponAction": "CREATE",
"date": "2023-06-21T14:34:59Z",
"storeCode": "BC",
"terminalCode": "6",
"transactionId": "BC_202306211134940"
},
{
"coupon": "1040BC0068238",
"couponAction": "CREATE",
"date": "2023-06-21T14:34:59Z",
"storeCode": "BC",
"terminalCode": "6",
"transactionId": "BC_202306211134940"
},
{
"coupon": "1030BC0049405",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:37Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221326"
},
{
"coupon": "1030BC0045872",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:37Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221326"
},
{
"coupon": "1030BC0042345",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:37Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221326"
},
{
"coupon": "1030BC0048811",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:37Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221326"
},
{
"coupon": "1030BC0045285",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:38Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221326"
},
{
"coupon": "1030BC0041751",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:38Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221326"
},
{
"coupon": "1030BC0048224",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:38Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221326"
},
{
"coupon": "1030BC0044691",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:38Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221326"
},
{
"coupon": "1030BC0041164",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:38Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221326"
},
{
"coupon": "1030BC0047630",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:38Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221326"
},
{
"coupon": "1030BC0044103",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:47Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221936"
},
{
"coupon": "1030BC0040570",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:47Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221936"
},
{
"coupon": "1030BC0047043",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:47Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221936"
},
{
"coupon": "1030BC0043519",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:47Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221936"
},
{
"coupon": "1030BC0049986",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:47Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221936"
},
{
"coupon": "1030BC0046459",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:47Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221936"
},
{
"coupon": "1030BC0042925",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:47Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221936"
},
{
"coupon": "1030BC0049399",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:47Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221936"
},
{
"coupon": "1030BC0045865",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:47Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221936"
},
{
"coupon": "1030BC0042338",
"couponAction": "CREATE",
"date": "2023-07-14T15:21:47Z",
"storeCode": "BC",
"terminalCode": "4",
"transactionId": "BC_202307141221936"
}
]
}
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 Tarjetas
PROMO expone un servicio que permite consultar tarjetas a la BBDD utilizando solo su número de tarjeta y como respuesta se obtienen los datos de la tarjeta en cuestión y los movimientos asociados a dicha tarjeta. Los datos que se devuelven son: fecha, id de transacción, tipo de operación, monto, tienda.
Para consumir este servicio se debe realizar una solicitud del tipo GET con los parámetros correspondientes a la siguiente URL: http://servidor:puerto/promo/api/rest/card
Los parámetros de entrada de la consulta son:
Propiedad | Tipo de dato | Descripción |
| companyId | Alfanumérico | Código de la compañía. Requerido |
| code | Alfanumérico | Código de la tarjeta la cual 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. Requerido |
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 tarjetas definidos. *ver ejemplo mas abajo. Opcional |
| cardAction | Alfanumérico | (desde7.0.4) Código de Operación que se quiere consultar. Si no se especifica code. Por defecto son todas las operaciones. Los valores disponibles son: CHARGE, RECHARGE, AMOUNT_UPDATE, SALE, EXTENDED_POINTS. Opcional |
| timeFrom | Numérico | (desde 7.0.4) Hora de Inicio en formato HHmm. Opcional |
| timeTo | Numérico | (desde 7.0.4) 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 una tarjeta, se retornarán los datos y movimientos asociados a dicha tarjeta, pudiéndose opcionalmente especificar un rango de fechas y un limite en la cantidad de movimientos.
Si no se especifica tarjeta, se debe especificar un rango de fechas y se retornaran todos los movimientos de las tarjetas en ese rango, incluyendo en ese caso el numero de tarjeta que se trata.
Para el caso de información de tarjetas, el Formato de la Respuesta será (JSON):
Propiedad | Tipo de dato | Descripción | ||||||
| _id* | Alfanumérico | Uso Interno | ||||||
| amount* | Numérico | Saldo Actual de la tarjeta. | ||||||
code* | Alfanumérico | Número de Tarjeta | ||||||
Created* | Alfanumérico | Fecha de Creacion en formato ISODATE | ||||||
| customerId | Alfanumérico | Id de cliente asocido a la tarjeta | ||||||
| activation | Numérico | Fecha de activacion | ||||||
isConsumed* | Booleano | Si ha sido consumida o no | ||||||
| status* | Alfanumérico | Estado actual de la tarjeta | ||||||
| storeCode* | Alfanumérico | Codigo de Tienda de generación (si aplica) | ||||||
| terminalCode* | Alfanumérico | Codigo de terminal de generación (si aplica) | ||||||
| transactionId* | Alfanumérico | Codigo de Transacción que la genero (si aplica) | ||||||
| lastPurchaseDate | Numérico | Fecha del ultimo movimiento | ||||||
| type* | Alfanumérico | Tipo de Tarjeta | ||||||
| typeName | Alfanumérico | Nombre del tipo de tarjeta | ||||||
| amountPrev | Numérico | monto previo | ||||||
| version* | Numérico | Uso Interno | ||||||
| cardHistory | Colección | Conjunto de registros que corresponden a cada movimiento de la tarjeta, con:
Conjunto de refistros que corresponden a la promocion que aplica al movimiento de tarjeta
|
- Estos datos son retornados solo si se consulta por un código de tarjeta determinado.
Para el caso de Tipos de tarjeta:
Propiedad | Tipo de dato | Descripción |
amountChargeLimit | Numérico | Limite de carga |
cardNumberLength | Numérico | Longitud del número de tarjeta |
cardTypePrefixRange | Array | definición de rangos de prefijos para esa tarjeta. |
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 nominada |
isRechargeable | Booleano | True is es recargable |
name | Alfanumérico | Nombre del tipo |
EJEMPLO 1: se solicitan los datos de la tarjeta 1000000000001 para la compañí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 Tarjetas
Cuando se especifica el parámetro "isTypes" se retornarán solamente los tipos de tarjeta definidos.
EJEMPLO 3:
Via CURL
curl -X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8 -H "Content-type: application/json" -H "Accept: application/json" "http://localhost:8080/promo/api/rest/card?companyId=napse&isTypes=true"
El cual recibirá una respuesta del tipo:
{
"cardTypes": [
{
"amountChargeLimit": 0.0,
"cardNumberLength": 16,
"cardTypePrefixRange": [
{
"_id": "5f45547d830a697a4012df3c",
"creationAt": "2020-08-25T18:12:13Z",
"isSuggested": false,
"prefixEnd": 1000,
"prefixStart": 1
},
{
"_id": "5f45547d830a697a4012df3d",
"creationAt": "2020-08-25T18:12:13Z",
"isSuggested": false,
"prefixEnd": 2000,
"prefixStart": 1001
}
],
"code": "tc01",
"customerValidation": "NO",
"description": "TC01",
"isActive": true,
"isCVVRequired": false,
"isNominated": false,
"isRechargeable": true,
"name": "TC01"
},
{
"amountChargeLimit": 5000.0,
"cardNumberLength": 11,
"cardTypePrefixRange": [
{
"_id": "5f45575d830a697a4012df40",
"creationAt": "2020-08-25T18:24:29Z",
"isSuggested": false,
"prefixEnd": 3000,
"prefixStart": 3000
}
],
"code": "tc02",
"customerValidation": "FILE",
"description": "TC02",
"isActive": false,
"isCVVRequired": true,
"isNominated": true,
"isRechargeable": true,
"name": "TC02"
}
]
}
Estado de puntos de Tarjetas
PROMO expone un servicio que permite consultar el estado de los puntos de una tarjeta de fidelidad a la BBDD utilizando solo su número de la tarjeta y como respuesta se obtienen los datos del estado de los puntos de la tarjeta en cuestión y los movimientos asociados a dicha tarjeta. Los datos que se devuelven son: número y tipo de tarjeta, 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:
EJ: se solicitan los datos de los puntos consumidos de la tarjeta asociada al cliente cuyo Id = 1:
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 opción de "descargar".
Como en el caso de los servicios REST previamente descriptos se necesita una authorizacion via OAuth2.
La siguiente figura muestra el contenido del GET de ejemplo:
http://localhost:8070/promo/api/rest/promotions
<promoCoreRequest> <operation>getMaps</operation> <companyId>napse</companyId> <params> <mapNumber>5</mapNumber> </params> </promoCoreRequest>
Donde:
operation: valor getMaps para obtener el mapa solicitado. Requerido
companyId: identificacion o codigo 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 via OAuth2.
La siguiente figura muestra el contenido del GET de ejemplo:
http://localhost:8070/promo/api/rest/promotions
<promoCoreRequest>
<operation>getPromotions</operation>
<companyId>2</companyId>
<params>
<promoCode>p70</promoCode>
<store>1</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="64fb3542a62e43409cd6f32c" name="Promo prueba 7.0" code="p70" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="true" suggest="not"> <sets> <set name="64fb354ea62e43409cd6f32f" type="item" /> </sets> <condition type="basic" name="Exists"> <parameter key="use-set" value="64fb354ea62e43409cd6f32f" /> </condition> <benefits> <benefit instance="PercentageDiscount" nro="64fb3564a62e43409cd6f332"> <parameter key="displayMessage" value="Promo prueba 7.0" /> <parameter key="printerMessage" value="Promo prueba 7.0" /> <parameter key="TLOGMessage" value="Promo prueba 7.0" /> <parameter key="applicationMethod" value="resume" /> <parameter key="prorationMethod" value="proportional" /> <parameter key="applicationPriceType" value="benefited-price" /> <parameter key="name" value="64fb3542a62e43409cd6f32c" /> <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="64fb354ea62e43409cd6f32f" /> </applied-elements> </benefit> </benefits> </promotion> </promotions> </promoCoreResponse>
Donde se observa:
ack: resultado del request, donde 0 es procesamiento correcto. (Ver códigos de respuesta ack mas arriba en este documento).
message: es el mensaje de error resultante.
promotions: tag general que contiene los elementos promotion retornados en la respuesta. Cada elemento promotion, contiene todos los elementos y tags que contiene una promoción.
Servicio De Consulta de Promoción
PROMO expone 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 ( a partir de la versión 7.0.33) 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 vía OAuth2.
Se puede acceder al servicio desde:
http://[Server]:[Port]/promo/api/rest/promotions
Las siguientes figuras muestran los contenidos de los GET mencionados:
Promoción por número <promoCoreRequest> <operation>getPromotionsByNro</operation> <companyId>2</companyId> <nro>647dd435a62e4330f8c8fa61</nro> </promoCoreRequest> Promocion por número <?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>
<ack>0</ack>
<message value="" />
<promotions>
<promotion nro="647dd435a62e4330f8c8fa61" name="Promo Puntos I" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not">
<sets>
<set name="647dd443a62e4330f8c8fa64" type="item" attribute="code" comparator="Into" value="111" />
</sets>
<condition type="basic" name="Exists">
<parameter key="use-set" value="647dd443a62e4330f8c8fa64" />
</condition>
<benefits>
<benefit instance="LoyaltyBenefit" nro="647dd45fa62e4330f8c8fa67">
<parameter key="displayMessage" value="Promo Puntos I" />
<parameter key="printerMessage" value="Promo Puntos I" />
<parameter key="TLOGMessage" value="Promo Puntos I" />
<parameter key="applicationMethod" value="resume" />
<parameter key="prorationMethod" value="proportional" />
<parameter key="applicationPriceType" value="benefited-price" />
<parameter key="name" value="647dd435a62e4330f8c8fa61" />
<parameter key="value" value="100" />
<parameter key="type" value="1" />
<parameter key="unit" value="qty" />
<parameter key="recoveryValue" value="0" />
<parameter key="recoveryType" value="" />
<applied-elements>
<use-set name="647dd443a62e4330f8c8fa64" />
</applied-elements>
</benefit>
</benefits>
</promotion>
</promotions>
</promoCoreResponse>
| Promoción por código <promoCoreRequest> <operation>getPromotionsByCode</operation> <companyId>2</companyId> <promoCode>MDCIII</promoCode> </promoCoreRequest> Promocion por Código <?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>
<ack>0</ack>
<message value="" />
<promotions>
<promotion nro="647dcba5a62e4330f8c8fa34" name="Promo MDC III" code="MDCIII" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not">
<sets>
<set name="647dcbb4a62e4330f8c8fa37" type="item" />
</sets>
<condition type="basic" name="Exists">
<parameter key="use-set" value="647dcbb4a62e4330f8c8fa37" />
</condition>
<benefits>
<benefit instance="PercentageDiscount" nro="647dcbc2a62e4330f8c8fa3a">
<parameter key="displayMessage" value="Promo MDC III" />
<parameter key="printerMessage" value="Promo MDC III" />
<parameter key="TLOGMessage" value="Promo MDC III" />
<parameter key="applicationMethod" value="resume" />
<parameter key="prorationMethod" value="proportional" />
<parameter key="applicationPriceType" value="benefited-price" />
<parameter key="name" value="647dcba5a62e4330f8c8fa34" />
<parameter key="percent" value="15" />
<parameter key="unit" value="qty" />
<parameter key="prorateBCP" value="false" />
<parameter key="recoveryValue" value="0" />
<parameter key="recoveryType" value="" />
<applied-elements>
<use-set name="647dcbb4a62e4330f8c8fa37" />
</applied-elements>
</benefit>
</benefits>
</promotion>
</promotions>
</promoCoreResponse>
| Promoción por número de Beneficio <promoCoreRequest> <operation>getPromotionsByBenefitNro</operation> <companyId>2</companyId> <nro>6489c122a62e4343b821cc9d</nro> </promoCoreRequest> Promoción por Número de Beneficio <?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>
<ack>0</ack>
<message value="" />
<promotions>
<promotion nro="6489c0f7a62e4343b821cc97" name="Promo simulacion" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not">
<sets>
<set name="6489c0fda62e4343b821cc9a" type="item" />
</sets>
<condition type="basic" name="Exists">
<parameter key="use-set" value="6489c0fda62e4343b821cc9a" />
</condition>
<benefits>
<benefit instance="PercentageDiscount" nro="6489c122a62e4343b821cc9d">
<parameter key="displayMessage" value="Promo simulacion" />
<parameter key="printerMessage" value="Promo simulacion" />
<parameter key="TLOGMessage" value="Promo simulacion" />
<parameter key="applicationMethod" value="resume" />
<parameter key="prorationMethod" value="proportional" />
<parameter key="applicationPriceType" value="benefited-price" />
<parameter key="name" value="6489c0f7a62e4343b821cc97" />
<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="6489c0fda62e4343b821cc9a" max="1.0" attribute="qty" />
</applied-elements>
</benefit>
</benefits>
</promotion>
</promotions>
</promoCoreResponse>
| Promociones por Nombre <promoCoreRequest> <operation>getPromotionsByName</operation> <companyId>2</companyId> <promoName>Promo Cupon</promoName> </promoCoreRequest> Promoción por Nombre <?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>
<ack>0</ack>
<message value="" />
<promotions>
<promotion nro="6477a08ba62e430db08b021c" name="Promo Cupon" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not">
<sets>
<set name="6477a097a62e430db08b021f" type="item" />
</sets>
<condition type="basic" name="Exists">
<parameter key="use-set" value="6477a097a62e430db08b021f" />
</condition>
<benefits>
<benefit instance="CouponBenefit" nro="6477a0ada62e430db08b0222">
<parameter key="displayMessage" value="Promo Cupon" />
<parameter key="printerMessage" value="Promo Cupon" />
<parameter key="TLOGMessage" value="Promo Cupon" />
<parameter key="applicationMethod" value="resume" />
<parameter key="prorationMethod" value="proportional" />
<parameter key="applicationPriceType" value="benefited-price" />
<parameter key="name" value="6477a08ba62e430db08b021c" />
<parameter key="qty" value="1" />
<parameter key="couponid" value="1" />
<parameter key="infoPos" value="0" />
<parameter key="recoveryValue" value="0" />
<parameter key="recoveryType" value="" />
<applied-elements>
<use-set name="6477a097a62e430db08b021f" />
</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 (cuando el servicio es getPromotionsByNro) o para una búsqueda mediante el número de benefició de promoción(cuando el servicio es getPromotionsByBenefitNro).
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.
En la respuesta 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 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 opcional.
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. Opcional |
Los parámetros de salida son:
| Propiedad | Tipo de Dato | |
|---|---|---|
| mapVersion | Alfanumérico | Versión del mapa requerido |
| code | Alfanumérico | código de la promoción que está contenida en el mapa |
| name | String | nombre de la promoción |
| conditionSimple | String | condición simple de la promoción |
| conditionCombo | String | condición combo de la promoción |
| conditionDate | Alfanumérico | condición de fechas de la promoción |
| benefitTypeDescription | String | Descripción del tipo de beneficio de la promoción |
| benefitClassDescription | String | Descripción de la clase de beneficio de la promoción |
| benefit | String | Descripción del beneficio de la promoción |
la respuesta es el Json:
[{"mapVersion":"40",
"code":null,
"name":"Promo simulacion",
"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 (%) No. Por cada unidad de Cantidad. Prorratear entre Participantes No. Valor de Recupero No. Tipo de Recupero No</p> "
},
{"mapVersion":"40",
"code":null,
"name":"Promo Puntos I",
"conditionSimple":"Productos con Codigo (SKU) IGUAL a 111",
"conditionCombo":"","conditionDate":"",
"benefitTypeDescription":"<p>1.- No Monetario</p><br/>",
"benefitClassDescription":"<p>1.- Puntos de fidelizaci\u00f3n</p><br/>",
"benefit":"<p>1.- Productos con Codigo (SKU) IGUAL a 111. Otorgar puntos (cantidad) No. De tipo No. Por cada unidad de Cantidad. M\u00e1ximo de puntos por transacci\u00f3n No. Valor del Recupero No. Tipo de Recupero No</p> "
},
{"mapVersion":"40",
"code":null,
"name":"Promo Cupon","conditionSimple":"Productos con Aplica a TODOS",
"conditionCombo":"","conditionDate":"",
"benefitTypeDescription":"<p>1.- No Monetario</p><br/>",
"benefitClassDescription":"<p>1.- Cup\u00f3n</p><br/>",
"benefit":"<p>1.- Productos con Aplica a TODOS. Otorgar cupones (cantidad) No. De tipo/identificador No. Datos para el POS Indistinto. Valor del Recupero No. Tipo de Recupero No</p> "},
{"mapVersion":"40",
"code":null,
"name":"Promo A",
"conditionSimple":"Productos con Codigo (SKU) IGUAL a 111 y Familia IGUAL a Electro",
"conditionCombo":"",
"conditionDate":"",
"benefitTypeDescription":"<p>1.- Monetario</p><br/>",
"benefitClassDescription":"<p>1.- Descuento fijo</p><br/>",
"benefit":"<p>1.- Productos con Codigo (SKU) IGUAL a 111 y Familia IGUAL a Electro. El siguiente monto ($) No. Por cada unidad de Cantidad. Prorratear entre Participantes No. Valor de Recupero No. Tipo de Recupero No</p> "
},
{"mapVersion":"40",
"code":null,
"name":"Promo 1",
"conditionSimple":"Productos con Categoria IGUAL a pantalones",
"conditionCombo":"",
"conditionDate":"",
"benefitTypeDescription":"<p>1.- Monetario</p><br/>",
"benefitClassDescription":"<p>1.- Descuento porcentaje</p><br/>",
"benefit":"<p>1.- Productos con Categoria IGUAL a pantalones. El siguiente porcentaje (%) No. Por cada unidad de Cantidad. Prorratear entre Participantes No. Valor de Recupero No. Tipo de Recupero No</p> "
}]
Servicio Próximo Número de tarjeta
PROMO expone un servicio que permite consultar, para un determinado tipo de tarjeta cual es el próximo número de tarjeta disponible inactivo y sin cliente asociado. Por medio de este servicio de consulta, el POS podrá conocer el número de la "siguiente tarjeta inactiva y sin cliente asociado" para ser asignada a un cliente desde línea de cajas. Promo devolverá el número de tarjeta y el POS lo asociará al cliente y le reenviará (LoyaltyAssign) el número y tipo de tarjeta, más los datos del cliente para que se active y asigne la tarjeta.
Cuando no se disponga de mas tarjetas inactivas y sin cliente asociado en la base de datos para el tipo de tarjeta consultado, se devolverá el mensaje de error indicando que no se cuenta con mas tarjetas disponibles para ser asociadas.
Considerar que el tipo de nominación que utilizará es "Asociación por canal de Ventas" y las tarjeta deberán darse de alta vía archivo.
En el archivo de alta masiva solo se informará el nro. de tarjeta y el Tipo.
Al darse de alta las tarjetas, estas quedarán en estado INACTIVO.
La activación de tarjeta y asignación de cliente se debe realizar por medio del "Canal de Ventas".
Para ello, una vez dadas de alta las tarjetas 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óxima Tarjeta (NextCardNumber). Promo informará a este mensaje el número de la próxima tarjeta inactiva y sin cliente asignado, disponible.
Luego el POS, enviará un mensaje de asociación (LoyaltyAssign) del cliente a la tarjeta, quedando esta última activa y con el cliente informado asociado a la tarjeta.
Servicio REST
Para los ejemplos se realizaron las consultas de tarjetas utilizando la herramienta "PostMan" de Chrome. Deberá obtenerse un nuevo Token (cUrl), y luego podrá realizarse la consulta de próximo número de tarjeta (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 Records contendrá los siguientes parámetros correspondientes a cada una de las columnas del informe:
Propiedad | Tipo de dato | Descripción |
| transactionId | Alfanumérico | Código de la transacción |
offline | Booleano | Verdadero si la transacción fue realizada en modo offline |
| unitPrice | Numérico | Precio unitario del producto |
benefitClass | Alfanumérico | Clase de beneficio |
itemCode | Alfanumérico | Código de Producto |
discountApply | Numérico | Descuento Aplicado |
| deploymentChannels | Alfanumérico | Canal de Publicación |
| date | Alfanumérico | Fecha de la transacción |
| transactionType | Alfanumérico | Tipo de Transacción |
| campaign | Alfanumérico | Campaña |
| quantity | Numérico | Cantidad del Producto |
| promotionCode | Alfanumérico | Código de Promoción |
| promotionName | Alfanumérico | Nombre de la Promoción |
| store | Alfanumérico | Tienda |
| subTotal | Numérico | Subtotal de la transacción |
| conditionTimeRange | Alfanumérico | Condición de Fecha/hora si aplica. |
Cada elemento del Vector Header contendrá los siguientes parámetros Informativos:
Propiedad | Tipo de dato | Descripción |
| total | Numérico | Total de Registros disponibles |
offset | Numérico | offset solicitado actualmente |
| limit | Numérico | Limite solicitado actualmente |
Esta información sirve para mantener una paginación como sucede en pantalla pero a nivel servicio. Digamos:
Primer consulta: offset: 0, limit: 25 → retorna la primer página de 25 registros y me informa un total de 500.
Segunda consulta: offset: 25, limit 25 → retorna la segunda pagina, es decir registros 26 a 50.
En lo sucesivo se podrá ir pidiendo paginas hasta llegar a offset: 475, limit 25.
También se podría realizar un paginado de a 100 registros por consulta, etc. (limit: 100).
EJEMPLO 1:
Solicitamos un reporte de Promociones para la compañía myCompany, entre el 21/11/2020 y el 04/12/2020, limitado a 25 registros a partir del 500 (esto es el equivalente a la página 21 en pantalla), para el código de Promoción 10549
Obteniéndose la siguiente respuesta:
Ejemplo {
"records:": "[{\"transactionId\":\"xx_0621_002_20201202123540\",\"offline\":false,\"unitPrice\":10400.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"1580203\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"02/12/2020 04:35\",\"transactionType\":\"Venta\",\"campaign\":\"Mercadeo\",\"quantity\":1.0,\"promotionCode\":\"10549\",\"promotionName\":\"MY PROMO-10549\",\"store\":\"0621 - MY STORE \",\"subTotal\":10400.0,\"conditionTimeRange\":\"\r\nEntre las fechas con horario 26/11/2020 02:00-06/12/2020 01:59\r\n\"},{\"transactionId\":\"xx_0621_001_20201202112635\",\"offline\":false,\"unitPrice\":5600.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"720190\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"02/12/2020 03:26\",\"transactionType\":\"Venta\",\"campaign\":\"Mercadeo\",\"quantity\":1.0,\"promotionCode\":\"10549\",\"promotionName\":\"MY PROMOTION-10549\",\"store\":\"0621 - MY STORE\",\"subTotal\":5600.0,\"conditionTimeRange\":\"\r\nEntre las fechas con horario 26/11/2020 02:00-06/12/2020 01:59\r\n\"}]",
"header": {
"total": 504,
"offset": 500,
"limit": 25
}
}
|
.
Consola: Servicios REST de Carga de Datos
Aquí se presentan los servicios provistos para enviar o cargar información en PROMO.
Antes de consumir el servicio debe obtenerse el TOKEN de identificación como se explica en "Seguridad: Autenticación de Sistemas Externos con los Servicios"
Precios: Servicio de Carga De Lista Cero
Se creo un Servicio Rest que permite la carga de los productos de una lista cero, El Mismo recibe la información y sera procesada de manera asincrónica, es decir recibe la información y luego sera procesada.
La Lista cero es la lista base donde se encontraran todos los precios de los productos, la misma tiene la prioridad mas baja de las listas (El motor al consultar los precios evalúa las listas existentes de prioridad de mayor a menor).
La Lista cero será enviada desde un sistema externo a promo, el proceso crea y actualiza los precios enviados.
En la consola se agrego la pantalla de Monitoreo de Importaciones. en la sección de soporte, desde esta pantalla se podrá ver el resultado de la importación, ver la información enviada en la importación (menú contextual Contenido), el detalle de la importación mostrará el total de los registros los procesados correctamente y los que tuvieron errores, estos últimos en caso de existir se verán en la pantalla paginados o se podrá descargar los mismos en un archivo de texto. El monitor también permite el re proceso de la importaciones.
El Método es un POST a la siguiente dirección: <promo>/api/rest/priceList con el siguiente body:
{
"companyId": "napse",
"store": "napse",
"items": [
{
"sku": "0527-1537",
"salePrice": 69406.77,
"costPrice": 50942.13,
"saleCreditPrice": 119716.68,
"magnitudePrice": 829,
"measuredUnit": "cm3",
"supplierItem": "PR3",
"supplierFinancial": "PR2",
"supplierItemAmount": 52471,
"supplierFinancialAmount": 53604,
"saleWholesalePrice": 31858,
"saleWholesaleLimit": 6081,
"limit": 794,
"enabledDate": "2018-12-25T10:42:25Z"
"discountable":true,
"manualDiscount":false
},
{
"sku": "66897-001",
"salePrice": 39123.0,
"costPrice": 10452.59,
"saleCreditPrice": 42433.6,
"magnitudePrice": 371,
"measuredUnit": "kg",
"supplierItem": "PR2",
"supplierFinancial": "PR2",
"supplierItemAmount": 52551,
"supplierFinancialAmount": 21423,
"saleWholesalePrice": 78603,
"saleWholesaleLimit": 9691,
"limit": 2982,
"enabledDate": "2019-01-20T10:41:55Z"
}
]
}
La respuesta del mismo será en caso Ok (Http.status=200)
{
"status": "Informacion Recibida OK",
"description": "La lista de precios será procesada"
}
En caso de Error: (Http.status=400)
{
"status": "companyId is Required",
"description": "Debe enviar el campo companyId"
}
{
"status": "companyId is Invalid",
"description": "Debe enviar el campo companyId valido"
}
Nota: La compania enviada en el rest debe tener el modulo de precios habilitado para que el servicio se habilite
Propiedad | Tipo de dato | Descripción |
| companyId | Alfanumérico | Código de la compañía. Requerido |
| store | Alfanumérico | Código de la tienda de Promo. Requerido |
sku | Alfanumérico | Código del producto. Requerido |
salePrice | Numérico | Precio de venta. Requerido |
costPrice | Numérico | Opcional. Precio de costo |
saleCreditPrice | Numérico | Precio de crédito. Requerido |
magnitudePrice | Numérico | Opcional. Precio por magnitud (kilo, litro, bulto, etc.) |
| measuredUnit | Alfanumérico | Opcional. unidad de medida |
supplierItem | Alfanumérico | Opcional.Es el código del proveedor del ítem |
| supplierItemAmount | Numérico | Opcional. Es el monto que el proveedor reconoce (monto del recupero) |
| supplierFinancial | Alfanumérico | Opcional. Es el código del proveedor financiero del ítem |
| supplierFinancialAmount | Numérico | Opcional. Es el monto que el proveedor Financiero reconoce (monto del recupero) |
| saleWholesalePrice | Numérico | Opcional.Precio mayorista |
| saleWholesaleLimit | Numérico | Opcional. Cantidad a partir de la cual aplica el precio mayorista |
| limit | Numérico | Opcional.(límite de unidades que se podrán vender a ese precio) |
| enabledDate | Fecha | Fecha que indica a partir de cuando el precio es valido (FORMATO ISO 8601 (UTC)). Requerido |
discountable | Booleano | Opcional. determina si el ítem se le puede aplicar descuento.(de omitir dicho campo por default será true) |
manualDiscount | Booleano | Opcional. determina si el item se le puede aplicar descuento Manual .(de omitir dicho campo por default sera true) |
El proceso de importación de la lista cero, insertara/actualizara el producto en la lista cero de la tienda, en caso de tener el campo enable_date con una fecha futura, ese precio se habilitara en el momento que sea el enable_date.
El proceso de actualización de precios para una lista cero, lockea mientras se esta procesando la actualización, en caso inesperado error no contemplado y quede lockeado, hay un configuration data que determina el tiempo en minutos de espera de un lockeo de actualización que es el siguiente (luego de ese tiempo se podrá volver a correr el proceso para esa lista cero).
ConfigurationData.readAsInteger(companyId, "prices", "priceList.lockForUpate",15)
Servicio de Importación de Catálogos
PROMO expone este nuevo servicio para brindar una alternativa en la carga/recepción de catálogos que, hasta la presente versión, podía realizarse únicamente vía archivos. Para comprender esta sección se recomienda referirse al manejo de catálogos en el manual del usuario.
El esquema de autenticación es el mismo que en los demás servicios REST presentados aquí (ver mas arriba).
Una vez obtenido el token de acceso, el servicio puede ser invocado utilizando el método POST, desde la URL: <promo>/api/rest/catalogs
El formato general del request es:
{
"companyId": "myCompanyId",
"catalog":"CatalogId",
"params":[
"param1":"param1value",
"paramN":"paramNvalue"
],
"items": [
{.... primer item .......},
{.... otro item .......},
{.... otro item .......},
{.... otro item .......},
{.... otro item .......},
]
}
donde
| Campo | Descripción | Tipo de Dato |
|---|---|---|
companyId |
| alfanumérico. 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 parametros especificos, pero como valor genérico tenemos:
[...] "params": [ [...] Importante No aplica a tarjetas de fidelidad y asignación de convenios. Requerido |
| ítems | Registros a importar | Colección de objetos dependientes de cada catálogo. Requerido Atributos dinamicos. Para el catalogo de Clientes (catalogCustomer.catalog), podrá 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 de éstos elemento en la definición de condiciones de una promoción, cuando ésta funcionalidad se encuentre habilitada en consola. (Ver Manual de Usuario 7.0) Ejemplo de catalogCustomer 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 |
La respuesta será del tipo:
{
"status": "200",
"description": "CatalogCountry",
"detail": {
"result": "ok",
"detail": "Info adicional"
}
}
donde:
| Campo | Descripción | Tipo de Dato | Posibles valores |
|---|---|---|---|
status | codigo de Respuesta | alfanumérico | 200 (válido), 400 (errores de validación o de sintaxis json), 500 (error genérico) |
description | identificador del catálogo | alfanumérico | Cada uno de los nombre de los catálogos importables por mensaje rest, o bien cadena vacía si no es posible obtenerlos (por ej. ante un error de sintaxis json). |
| detail | Información adicional | Objeto | Clave result, con los resultados posibles, es decir, ok o error. Clave detail, con valor correspondiente al mensaje informativo de validación, error, o procesamiento válido. |
Consideraciones
- El número de registros por paquete (request) estará limitado a 1000 ítems para no afectar la performance y que las respuestas puedan ser procesadas.
- En caso de error se informaran los registros erróneos pero los que han resultado correctos serán incorporados. Los resultados podrán visualizarse en la consola en la pantalla de Monitor de Importación.
- En todos los casos se informara la cantidad total de líneas con error y las correctas. Los resultados podrán visualizarse en la consola en la pantalla de Monitor de Importación.
- El proceso utiliza semáforos para evitar la concurrencia de clientes que pretendan procesar en paralelo ya que implica posibilidad de errores en las validaciones.
Los catálogos a importar son:
Consola: Servicio REST de Eliminación de Datos del Cliente y sus datos de fidelidad
(Desde 7.0.18)
Este servicio rest permite eliminar al cliente y todos los datos de fidelidad relacionados con éste 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:
Servicio de Importación Masiva de Promociones vía REST
(Desde 7.0.2)
Este servicio permite realizar la importación de promociones en forma masiva a través de REST a la consola de PROMO.
El esquema de autenticación es el mismo que en los demás servicios REST presentados aquí (ver mas arriba).
Una vez obtenido el token de acceso, el servicio puede ser invocado utilizando el método POST:
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": "Entrega de un cupon para proxima compra",
"code": "P2002",
"sets": {
"set": [
{
"name": "5feaf1324b10b84760e83f37",
"type": "item",
"attribute": "level1",
"comparator": "Into",
"value": "maderas"
},
{
"name": "5feaf13a4b10b84760e83f3a",
"type": "payment",
"attribute": "type",
"comparator": "Into",
"value": "card"
}
]
},
"condition": {
"type": "composite",
"name": "And",
"condition": [
{
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "5feaf1324b10b84760e83f37"
}
},
{
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "5feaf13a4b10b84760e83f3a"
}
}
]
},
"benefits": {
"benefit": {
"instance": "CouponBenefit",
"parameter": [
{
"key": "displayMessage",
"value": "Entrega de un cupon para proxima compra"
},
{
"key": "printerMessage",
"value": "Entrega de un cupon para proxima compra"
},
{
"key": "TLOGMessage",
"value": "Entrega de un cupon para proxima compra"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "name",
"value": "5feaf1224b10b84760e83f34"
},
{
"key": "qty",
"value": "1"
},
{
"key": "couponid",
"value": "001"
},
{
"key": "infoPos",
"value": "0"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {
"name": "5feaf1324b10b84760e83f37"
}
}
}
}
},
{
"operation": "U",
"name": "Entrega de puntos llevando 2 furadeiras",
"code": "3003",
"sets": {
"set": {
"name": "5feaf18c4b10b84760e83f45",
"type": "item",
"attribute": "level3",
"comparator": "Into",
"value": "furadeiras"
}
},
"combo": {
"combo-component": {
"min": "2",
"max": "2",
"attribute": "qty",
"use-set": "5feaf18c4b10b84760e83f45"
}
},
"benefits": {
"benefit": {
"instance": "PercentLoyaltyBenefit",
"nro": "5feaf1cd4b10b84760e83f4a",
"parameter": [
{
"key": "displayMessage",
"value": "Entrega de puntos llevando 2 furadeiras"
},
{
"key": "printerMessage",
"value": "Entrega de puntos llevando 2 furadeiras"
},
{
"key": "TLOGMessage",
"value": "Entrega de puntos llevando 2 furadeiras"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "name",
"value": "5feaf1794b10b84760e83f40"
},
{
"key": "percent",
"value": "50"
},
{
"key": "type",
"value": "3003"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {
"name": "5feaf18c4b10b84760e83f45"
}
}
}
}
},
{
"operation": "R",
"code": "P2001",
},
{
"operation": "I",
"name": "Descuento Fijo $ 20 en Marca Adidas",
"code": "P1001",
"sets": {
"set": {
"name": "5feaf0c44b10b84760e83f2f",
"type": "item",
"attribute": "brand",
"comparator": "Into",
"value": "adidas"
}
},
"condition": {
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "5feaf0c44b10b84760e83f2f"
}
},
"benefits": {
"benefit": {
"instance": "FixedDiscount",
"nro": "5feaf0d04b10b84760e83f32",
"parameter": [
{
"key": "displayMessage",
"value": "Descuento Fijo $ 20 en Marca Adidas"
},
{
"key": "printerMessage",
"value": "Descuento Fijo $ 20 en Marca Adidas"
},
{
"key": "TLOGMessage",
"value": "Descuento Fijo $ 20 en Marca Adidas"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "name",
"value": "5feaf0bc4b10b84760e83f2c"
},
{
"key": "amount",
"value": "20"
},
{
"key": "unit",
"value": "qty"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {
"name": "5feaf0c44b10b84760e83f2f"
}
}
}
}
},
{
"operation": "I",
"name": "30% de descuento, llevando mas de 12 con prefijo 6447",
"code": "0002",
"sets": {
"set": {
"name": "5fe236da14b8fc698cfd63d7",
"type": "item",
"attribute": "level3",
"comparator": "Into",
"value": "6447"
}
},
"combo": {
"combo-component": {
"min": "12",
"max": "12",
"attribute": "qty",
"use-set": "5fe236da14b8fc698cfd63d7"
}
},
"benefits": {
"benefit": {
"instance": "PercentageDiscount",
"nro": "5fddeba114b8fc9724882991",
"parameter": [
{
"key": "displayMessage",
"value": "30% de descuento, llevando mas de 12 con prefijo 6447"
},
{
"key": "printerMessage",
"value": "30% de descuento, llevando mas de 12 con prefijo 6447"
},
{
"key": "TLOGMessage",
"value": "30% de descuento, llevando mas de 12 con prefijo 6447"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "name",
"value": "5fddeb8414b8fc972488298a"
},
{
"key": "percent",
"value": "30"
},
{
"key": "unit",
"value": "qty"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {
"name": "5fe236da14b8fc698cfd63d7"
}
}
}
}
}
]
}
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:
Requerido |
| conditions | Hace referencia a la combinación de conjuntos que forman parte de la condición para obtener el beneficio. Requerido 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. Requerido 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": "Informacion 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": "Informacion 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": "Informacion 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": { marcado en azul, tal como se muestra en el siguiente ejemplo:
Ejemplo:
{
"promotion": {
"nro": "62867033c9512b0184381178",
"name": "Promos con limites 1",
"code": "30",
"className": "com.synthesis.promo.engine.promotion.ModularPromotion",
"reportParticipants": "false",
"suggest": "not",
"sets": {
"set": {
"name": "62867340c9512b01843811b5",
"type": "item",
"attribute": "code",
"comparator": "Into",
"value": "111"
}
},
"condition": {
"type": "composite",
"name": "And",
"condition": [
{
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "62867340c9512b01843811b5"
}
},
{
"type": "basic",
"name": "Header",
"parameter": [
{
"key": "attribute",
"value": "store"
},
{
"key": "value",
"value": "napse,napse2"
}
]
}
]
},
"benefits": {
"benefit": {
"instance": "FixedDiscount",
"nro": "628670c9c9512b018438117f",
"parameter": [
{
"key": "displayMessage",
"value": "Promos con limites 1"
},
{
"key": "printerMessage",
"value": "Promos con limites 1"
},
{
"key": "TLOGMessage",
"value": "Promos con limites 1"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "hasLimit",
"value": "true"
},
{
"key": "name",
"value": "62867033c9512b0184381178"
},
{
"key": "amount",
"value": "300"
},
{
"key": "unit",
"value": "qty"
},
{
"key": "prorateBCP",
"value": "false"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {"name": "62867340c9512b01843811b5"}
}
}
}
}
}
5. Una vez copiado todo el contenido marcado en azul, se deberá actualizar el formato estándar de importación de promociones. Por ejemplo:
Deberá pegar el contenido copiado dentro después de “operation”: I, tal como se ve en la siguiente imagen.
Esto da el siguiente resultado con el formato de importación ya completo y listo para usar desde POSTMAN (el contenido pegado está marcado en azul):
Resultado del JSON de importación de promoción:
{
"companyId": "napse",
"promotions": [
{
"operation": "I",
"nro": "62867033c9512b0184381178",
"name": "Promos con limites 1",
"code": "30",
"className": "com.synthesis.promo.engine.promotion.ModularPromotion",
"reportParticipants": "false",
"suggest": "not",
"sets": {
"set": {
"name": "62867340c9512b01843811b5",
"type": "item",
"attribute": "code",
"comparator": "Into",
"value": "111"
}
},
"condition": {
"type": "composite",
"name": "And",
"condition": [
{
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "62867340c9512b01843811b5"
}
},
{
"type": "basic",
"name": "Header",
"parameter": [
{
"key": "attribute",
"value": "store"
},
{
"key": "value",
"value": "napse,napse2"
}
]
}
]
},
"benefits": {
"benefit": {
"instance": "FixedDiscount",
"nro": "628670c9c9512b018438117f",
"parameter": [
{
"key": "displayMessage",
"value": "Promos con limites 1"
},
{
"key": "printerMessage",
"value": "Promos con limites 1"
},
{
"key": "TLOGMessage",
"value": "Promos con limites 1"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "hasLimit",
"value": "true"
},
{
"key": "name",
"value": "62867033c9512b0184381178"
},
{
"key": "amount",
"value": "300"
},
{
"key": "unit",
"value": "qty"
},
{
"key": "prorateBCP",
"value": "false"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {"name": "62867340c9512b01843811b5"}
}
}
}
}
]
}
6. Importación del json desde POSTMAN:
Al importar una promoción, la misma se importará con el workflow general por default.
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.
Siguiendo el formato especificado anteriormente tendremos:
| Campo | Valor |
|---|---|
| companyId | El código de la compañia correspondiente. |
| catalog | "CatalogRedeemBenefit". No se debe modificar. |
params | Un listado vacío. No se debe modificar. |
| items | Un listado con cada item del catálogo de Canje de puntos. |
Dentro de items, el formato es:
| Campo | Valor |
|---|---|
store | Código de tienda. Requerido. Alfanumérico. Si se aplica a todas las tiendas, el código de la tienda debe ser "-". |
code | Código del producto. Requerido. Alfanumérico. |
points | Puntos requeridos. Numérico con decimales. |
discountValue | Valor descuento. Numérico con decimales. |
discountType | Tipo descuento. Acepta sólo los valores "perc" (porcentaje), "fix" (descuento fijo), o bien, "nprice" (nuevo precio) |
operation | La operación a realizar sobre el elemento. Ver tabla con valores posibles. |
Así tendremos que un ejemplo de request para insertar registros en este catálogo será:
{
"companyId": "napse",
"catalog": "CatalogRedeemBenefit",
"params": [],
"items": [
{
"store": "1",
"code": "10",
"points": "10.5",
"discountValue":"15" ,
"discountType": "perc",
"operation": "I"
},
{
"store": "1",
"code": "20",
"points": "20.5",
"discountValue":"20" ,
"discountType": "fix",
"operation": "I"
},
{
"store": "1",
"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 Tarjetas de Fidelidad
Esta operación es el equivalente a la función de asignación/actualización de tarjetas, mas la importación de clientes nuevos (Ver proceso actual de asignación de convenios). En este caso los campos serán:.
Asignación de una tarjeta a 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.......}
]
}
Los campos en negrita son obligatorios.
| Campo | Descripción |
|---|---|
| params | cardType: Tipo de tarjeta a importar que sera validado. contract: codigo de convenio al que pertenecen estas tarjetas/clientes. |
operation | I: Inserción / U: Actualización / R: Eliminación |
id |
|
customer |
|
amount |
|
name | Nombre del Cliente. Cadena libre. |
surname | Apellido. Cadena libre. |
gender | Género. (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin. |
birthDate | Fecha de nacimiento. Cadena en formato "yyyyMMdd". Más Información del formato |
idType | Tipo de identificacion (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin. |
identifier | Numero de Identificación del Cliente |
idDate | Fecha de Expiración de la identificación. Cadena en formato "yyyyMMdd". Más Información del formato |
nacionality | Nacionalidad. Cadena Libre. |
Direccion de correo electrónico. Cadena libre. | |
customerType | Tipo de Cliente (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin. |
address | Dirección. Cadena libre |
country | País. (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin. |
state | Estado/Provincia (ver valores por Catálogo). Depende de los valores cargados en el catálogo a tal fin. |
city | Ciudad (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin. |
postalCode | Codigo Postal |
phone | Telefono |
Asignación de ejemplo
Teniendo en cuenta que existe un convenio activo con código c1, y que hay una tarjeta existente, con código 1234000000000, y pertenece al tipo de tarjeta de código verano, se asigna a la tarjeta 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 a la tarjeta se especifica un operador + con el valor a sumar. Siguiendo el ejemplo anterior, donde la tarjeta 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 la tarjeta 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
(v 6.5) Sincrónico
Servicio Rest que opera de forma sincrónica para administrar clientes asociados a segmentos.
Una vez obtenido el token de acceso, el servicio puede ser invocado utilizando el método POST, desde la URL: <promo>/api/rest/segments