Manual de integración - Servicios
PROMO V7.0
Índice
Acerca del manual
Propósito y alcance
El presente manual tiene como finalidad la capacitación al usuario que desee integrar su aplicación de ventas con ellos servicios que expone Promo.
Se provee una descripción detallada de los mensajes que deben ser enviados al mismo y de cómo interpretar los mensajes de respuesta que dará ante un requerimiento.
Documentación de PROMO
PROMO provee la siguiente documentación:
- Manual de usuario:
Este documento tiene la finalidad de capacitar al usuario que desee utilizar la consola de Administración de Promociones de PROMO.
- Manual de instalación:
Este documento describe los procedimientos para instalar los componentes de Motor y Consola, la creación e inicialización de la Base de Datos y los requerimientos necesarios para el correcto funcionamiento de dichos componentes.
- Manual de integración - Motor:
Este documento describe detalladamente los mensajes que deben ser enviados al Motor de Promociones y la forma de interpretar los mensajes de respuesta que el mismo dará ante un requerimiento.
- Manual de integración - Servicios:
Este documento describe detalladamente los servicios que expone la consola de Promo y la forma de enviar y recibir información con ella.
Nota: Antes de continuar con la lectura del presente manual, se recomienda leer los capítulos 2 y 3 del Manual de usuario.
Herramientas utilizadas
En el desarrollo de este manual se utilizarán para los ejemplos basicamente tres herramientas que son de dominio público:
- CURL (https://curl.haxx.se/) "command line tool and library for transferring data with URLs": Es una herramienta por linea de comandos para enviar/recibir mensajes http.
- POSTMAN (https://www.postman.com) "The Collaboration Platform for API Development": Herramienta Grafica para la creación, envio y recepción de mensajes.
- SOAPUI (https://www.soapui.org/) "Accelerating API Quality Through Testing": Otra herramienta Gráfica para la definición, envio y recepción de mensajes.
Seguridad: Autenticación de Sistemas Externos con los Servicios
Antes de consumir un servicio provisto por Promo, deberá realizarse un Proceso de autenticación OAuth2. El mismo consiste en obtener un TOKEN que luego debe ser enviado en los subsiguientes mensajes.
Entonces como primer paso a comenzar la comunicación con los servicios de Promo, el sistema externo debe realizar el proceso descripto aquí.
Primero deberá de solicitarse el Tocken de acceso, que utilizando CURL el comando sería:
curl –v –X POST –u my-client: -d "grant_type=password" –d "username=sender" –d "password=mate" –d "scope=read" http://localhost:8080/promo/oauth/token
Donde "http://localhost:8080/promo/oauth/token" debe ser cambiado por la URL donde se encuentra la consola de Promo, de la misma forma que el usuario y password.
La respuesta ejemplo se puede ver en la siguiente ventana:
Una vez obtenido el token, se deberá enviar en las subsiguientes solicitudes. Por ejemplo realizamos un GET con la herramienta CURL:
curl -X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8" -H "Content-type: application/json" -H "Accept: application/json" "http://localhost:8080/promo/api/rest/customer?code=1"
De la misma forma, el mismo request pero realizado en POSTMAN, sería:
Consola: Servicios REST de Consulta
Aquí se presentan los servicios provistos para consulta de información contenida en PROMO.
Antes de consumir el servicio debe obtenerse el TOKEN de identificación como se explica en "Seguridad: Autenticación de Sistemas Externos con los Servicios"
Consulta de Datos de Clientes
PROMO expone un servicio que permite consultar tarjetas a la BBDD utilizando el ID de cliente. Junto con los campos del cliente, también se devuelve un listado de Tarjetas y Cupones, elementos de Fidelidad.
Si no tiene elementos de Fidelidad, se devolverán las Tarjetas o Cupones vacías
El código de la consulta debe ser exacto y solo se devolverá un resultado, si es que el cliente existe.
El formato en que se responde es en JSON.
Este método accesible desde api/rest/customer es el encargado de devolver en formato JSON el customer o cliente solicitado por medio de la acción GET.
Tiene tres parámetros de ingreso:
Nombre | Valor |
|---|---|
companyId | El código de la compañía. String. Requerido. |
code | El código del cliente. String. No requerido. |
identificationType | El código del tipo de identificación del cliente (por ej, "dni"). String. No requerido. |
identifier | El nro. de identificación de cliente (por ej. nro de dni). String. No requerido. |
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.
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
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=exito&code=85001"
Obteniéndose la siguiente respuesta:
Ejemplo {
"customerId": "85001",
"companyId": "exito",
"limitsDetail": [
{
"_id": "603a437c1082e83690817050",
"promotionId": "603a319c1082e83690816f95",
"benefitId": "603a31b81082e83690816f9c",
"promotionCode": "3",
"promotionName": "limite cliente",
"limitId": "603a31b61082e83690816f9b",
"scope": "CUSTOMER",
"period": "UNDEFINED",
"maxValue": 5.0,
"customerId": "85001",
"storeId": "-",
"numberDays": 0,
"nextReset": "2021-02-27T03:00:00+0000",
"lastReset": "2021-02-27T03:00:00+0000",
"companyId": "exito",
"limitTypeCode": "benefitApplicationCount",
"description": null,
"lastUpdate": "2021-02-27T13:05:00+0000",
"active": true,
"currentValue": 1.0
}
]
}
|
En caso de que el cliente no exista en la base la respuesta informara "El cliente especificado no existe".-
Servicio de Consulta de Cupón
PROMO expone un servicio que permite consultar cupones a la BBDD utilizando solo el número de cupón y como respuesta se obtienen los movimientos asociados a dicho cupón.
También se pueden realizar consultas sobre el historial de movimientos de cupones.
Los parámetros de entrada de la consulta son:
Propiedad | Tipo de dato | Descripción |
| companyId | Alfanumérico | Código de la compañía |
| barcode | Alfanumérico | Código de la tarjeta la cual se quiere consultar |
limit | Numérico | Cantidad de registros de movimientos a retornar (default: 5) con un máximo de 100.000 por consulta. |
dateFrom | Numérico | Fecha de Inicio en formato YYYYMMDD. Si no se especifica code. |
dateTo | Numérico | Fecha de Final en formato YYYYMMDD. Si no se especifica code. |
couponAction | Alfanumérico | Código de Operación que se quiere consultar. Si no se especifica code. Por defecto son todas las operaciones. Los valores disponibles son: CREATE, REDEEM, VOID |
| timeFrom | Numérico | (desde 7EP2) Hora de Inicio con formato HHmm |
| timeTo | Numérico | (desde 7EP2) Hora de Fin con formato HHmm |
Aclaración
Se pueden enviar el dateFrom y dateTo sin cargar los datos de timeFrom y timeTo, estos serán opcionales. Pero solo se utilizarán los parámetros timeFrom y timeTo si tiene cargados los parámetros de dateFrom y dateTo, caso contrario no serán utilizados.
EJEMPLO 1: se solicitan los datos del cupon 1020000000007
La misma pero utilizando CURL:
curl -X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8" -H "Content-type: application/json" -H "Accept: application/json" http://localhost:8080/promo/api/rest/coupon?barcode=1020000000007
Obteniéndose la siguiente respuesta:
Ejemplo {
"_id": "59a993d6caec3625e84476e1",
"barcode": "1020000000007",
"consumed": false,
"couponFormat": "PRE_PRINTED",
"couponStatus": "ACTIVE",
"couponType": "2",
"issuedDate": "2017-09-01T17:07:34Z",
"maxUsageTimes": 1,
"storeCode": "BC",
"terminalCode": "2",
"transactionId": "BC_201709011407171",
"usedTimes": 0,
"validFrom": "2017-09-01T17:07:34Z",
"validTo": "2117-08-08T17:07:34Z",
"version": 0,
*"couponHistory": \[*
{
"couponAction": "CREATE",
"date": "2017-09-01T17:07:34Z",
"storeCode": "BC"
}
]
}
|
En caso de que el cliente no exista en la base la respuesta se devolverá vacía.-
EJEMPLO 2: Se solicitan todos los cupones creados en el periodo 01/06/2020-01/07/2020, para la empresa napse con un limite de 100.000 registros.
(curl -X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8" -H "Content-type: application/json" -H "Accept: application/json"http://localhost:8080/promo/api/rest/coupon?dateFrom=20200601&dateTo=20200701&companyId=napse&limit=100000&couponAction=CREATE')
La respuesta será del tipo:
{
"couponHistory": [
{
"transactionId": "napse_1_10_20200608105150",
"date": "2020-06-05T18:11:00Z",
"coupon": "1010010106479",
"couponAction": "CREATE",
"storeCode": "1",
"terminalCode": "10"
},
{
"transactionId": "napse_1_10_20200608105150",
"date": "2020-06-05T18:11:00Z",
"coupon": "1010010102945",
"couponAction": "CREATE",
"storeCode": "1",
"terminalCode": "10"
},
{
"transactionId": "napse_1_10_20200608105150",
"date": "2020-06-05T18:11:00Z",
"coupon": "1010010109418",
"couponAction": "CREATE",
"storeCode": "1",
"terminalCode": "10"
},
{
"transactionId": "napse_1_10_20200608105250",
"date": "2020-06-05T18:21:30Z",
"coupon": "1010010102891",
"couponAction": "CREATE",
"storeCode": "1",
"terminalCode": "10"
}
]
}
Servicio de Consulta de Tarjetas
(Actualizado desde 6.5.2)
PROMO expone un servicio que permite consultar tarjetas a la BBDD utilizando solo su número de tarjeta y como respuesta se obtienen los datos de la tarjeta en cuestión y los movimientos asociados a dicha tarjeta. Los datos que se devuelven son: fecha, id de transacción, tipo de operación, monto, tienda.
Para consumir este servicio se debe realizar una solicitud del tipo GET con los parámetros correspondientes a la siguiente URL: http://servidor:puerto/promo/api/rest/card
Los parámetros de entrada de la consulta son:
Propiedad | Tipo de dato | Descripción |
| companyId | Alfanumérico | Código de la compañía |
| code | Alfanumérico | Código de la tarjeta la cual se quiere consultar |
limit | Numérico | Cantidad de registros de movimientos a retornar (default: 5) con un máximo de 100.000 por consulta. |
dateFrom | Numérico | Fecha de Inicio en formato YYYYMMDD |
dateTo | Numérico | Fecha de Final en formato YYYYMMDD |
| requestTypes | Booleano | (desde 7.EP2.1) Si se especifica el valor true se retornarán solamente los tipos de tarjetas definidos. *ver ejemplo mas abajo |
| cardAction | Alfanumérico | (desde 7.0.4) Código de Operación que se quiere consultar. Si no se especifica code. Por defecto son todas las operaciones. Los valores disponibles son: CHARGE, RECHARGE, AMOUNT_UPDATE, SALE, EXTENDED_POINTS |
| timeFrom | Numérico | (desde 7.0.4) Hora de Inicio en formato HHmm |
| timeTo | Numérico | (desde 7.0.4) Hora de final en formato HHmm |
Aclaración
Se pueden enviar el dateFrom y dateTo sin cargar los datos de timeFrom y timeTo, estos serán opcionales. Pero solo se utilizarán los parámetros timeFrom y timeTo si tiene cargados los parámetros de dateFrom y dateTo, caso contrario no serán utilizados.
Si se especifica una tarjeta, se retornarán los datos y movimientos asociados a dicha tarjeta, pudiéndose opcionalmente especificar un rango de fechas y un limite en la cantidad de movimientos.
Si no se especifica tarjeta, se debe especificar un rango de fechas y se retornaran todos los movimientos de las tarjetas en ese rango, incluyendo en ese caso el numero de tarjeta que se trata.
Para el caso de información de tarjetas, el Formato de la Respuesta será (JSON):
Propiedad | Tipo de dato | Descripción | ||||||
| _id* | Alfanumérico | Uso Interno | ||||||
| amount* | Numérico | Saldo Actual de la tarjeta. | ||||||
code* | Alfanumérico | Número de Tarjeta | ||||||
Created* | Alfanumérico | Fecha de Creacion en formato ISODATE | ||||||
| customerId | Alfanumérico | Id de cliente asocido a la tarjeta | ||||||
| activation | Numérico | Fecha de activacion | ||||||
isConsumed* | Booleano | Si ha sido consumida o no | ||||||
| status* | Alfanumérico | Estado actual de la tarjeta | ||||||
| storeCode* | Alfanumérico | Codigo de Tienda de generación (si aplica) | ||||||
| terminalCode* | Alfanumérico | Codigo de terminal de generación (si aplica) | ||||||
| transactionId* | Alfanumérico | Codigo de Transacción que la genero (si aplica) | ||||||
| lastPurchaseDate | Numérico | Fecha del ultimo movimiento | ||||||
| type* | Alfanumérico | Tipo de Tarjeta | ||||||
| typeName | Alfanumérico | Nombre del tipo de tarjeta | ||||||
| amountPrev | Numérico | monto previo | ||||||
| version* | Numérico | Uso Interno | ||||||
| cardHistory | Colección | Conjunto de registros que corresponden a cada movimiento de la tarjeta, con:
Conjunto de refistros que corresponden a la promocion que aplica al movimiento de tarjeta
|
- Estos datos son retornados solo si se consulta por un código de tarjeta determinado.
Para el caso de Tipos de tarjeta:
Propiedad | Tipo de dato | Descripción |
amountChargeLimit | Numérico | Limite de carga |
cardNumberLength | Numérico | Longitud del número de tarjeta |
cardTypePrefixRange | Array | definicion de rangos de prefijos para esa tarjeta. |
code | Alfanumérico | Codigo del tipo |
customerValidation | Alfanumérico | Si es Nominado, el tipo de validacion de customer (NO, API, FILE) |
description | Alfanumérico | Descripcion del tipo |
isActive | Booleano | True si se encuentra activo |
isCVVRequired | Booleano | True si requiere cvv |
isNominated | Booleano | True si es nominada |
isRechargeable | Booleano | True is es recargable |
name | Alfanumérico | Nombre del tipo |
EJEMPLO 1: se solicitan los datos de la tarjeta 1000000000001 para la compañia napse y con movimientos del 01/04/2020 al 31/04/2020 sin especificar limites con lo cual seran los 5 ultimos movimientos.
.
Via CURL
curl -X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8 -H "Content-type: application/json" -H "Accept: application/json" "http://localhost:8080/promo/api/rest/card?code=1000000000001&companyId=napse&dateFrom=20200401&dateTo=20200431"
El cual recibirá una respuesta del tipo:
{
"_id": "6054129516f79ab3103ad3ac",
"companyId": "exito",
"code": "s_verdes3095535912",
"status": "ENABLED",
"type": "s_verdes",
"amount": 20.0,
"customerId": "3095535912",
"created": "2021-03-19T02:55:17Z",
"activation": "2021-03-19T02:55:17Z",
"transactionId": "exito_1_1_20210319203011",
"storeCode": "1",
"terminalCode": "1",
"isConsumed": false,
"version": 2,
"lastPurchaseDate": "2021-03-19T02:56:30Z",
"typeName": "Stickers Verdes",
"cardHistory": [
{
"date": "2021-03-19T23:30:15Z",
"createdAt": "2021-03-19T02:56:30Z",
"card": "-",
"cardAction": "SALE",
"storeCode": "1",
"terminalCode": "1",
"appliedPromotionDetails": [
{
"promotionName": "otorga Stickers Verdes-54",
"promotionCode": "54",
"conditionDateRangeDescription": null
}
],
"customerCode": "-",
"amount": "20.0",
"amountPrev": "0.0",
"transactionId": "exito_1_1_20210319203015",
"reasonName": null
},
{
"date": "2021-03-19T02:55:17Z",
"createdAt": "2021-03-19T02:55:17Z",
"card": "-",
"cardAction": "ACTIVATION",
"storeCode": "1",
"terminalCode": "1",
"customerCode": "3095535912",
"amount": "0.0",
"amountPrev": "0",
"appliedPromotionDetails": null,
"transactionId": null,
"reasonName": null
}
],
"amountPrev": 0
}
EJEMPLO 2: se solicitan todos los movimientos del 29/04/2020 al 29/04/2020 con un maximo de 100.000 movimientos.
Via CURL:
curl -X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8 -H "Content-type: application/json" -H "Accept: application/json" "http://localhost:8080/promo/api/rest/card?companyId=napse&dateFrom=20200429&dateTo=20200429&limit=100000"
El cual recibirá una respuesta del tipo:
{
"cardHistory": [
{
"amount": "10.0",
"card": "1000000000000",
"cardAction": "AMOUNT_UPDATE",
"date": "2020-04-29T12:42:18Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "300.0",
"card": "1000000000000",
"cardAction": "CHARGE",
"date": "2020-04-29T12:02:06Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "0",
"card": "1000000000000",
"cardAction": "ACTIVATION",
"date": "2020-04-29T12:02:06Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "20.0",
"card": "1000000000001",
"cardAction": "AMOUNT_UPDATE",
"date": "2020-04-29T12:42:26Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "300.0",
"card": "1000000000001",
"cardAction": "CHARGE",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "0",
"card": "1000000000001",
"cardAction": "ACTIVATION",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "300.0",
"card": "1000000000002",
"cardAction": "CHARGE",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "0",
"card": "1000000000002",
"cardAction": "ACTIVATION",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "300.0",
"card": "1000000000003",
"cardAction": "CHARGE",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "0",
"card": "1000000000003",
"cardAction": "ACTIVATION",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "300.0",
"card": "1000000000004",
"cardAction": "CHARGE",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "0",
"card": "1000000000004",
"cardAction": "ACTIVATION",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "300.0",
"card": "1000000000005",
"cardAction": "CHARGE",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
},
{
"amount": "0",
"card": "1000000000005",
"cardAction": "ACTIVATION",
"date": "2020-04-29T12:41:07Z",
"storeCode": null,
"transactionId": null
}
]
}
Tipos de Tarjetas
Cuando se especifica el parámetro "isTypes" se retornarán solamente los tipos de tarjeta definidos.
EJEMPLO 3:
Via CURL
curl -X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8 -H "Content-type: application/json" -H "Accept: application/json" "http://localhost:8080/promo/api/rest/card?companyId=napse&isTypes=true"
El cual recibirá una respuesta del tipo:
{
"cardTypes": [
{
"amountChargeLimit": 0.0,
"cardNumberLength": 16,
"cardTypePrefixRange": [
{
"_id": "5f45547d830a697a4012df3c",
"creationAt": "2020-08-25T18:12:13Z",
"isSuggested": false,
"prefixEnd": 1000,
"prefixStart": 1
},
{
"_id": "5f45547d830a697a4012df3d",
"creationAt": "2020-08-25T18:12:13Z",
"isSuggested": false,
"prefixEnd": 2000,
"prefixStart": 1001
}
],
"code": "tc01",
"customerValidation": "NO",
"description": "TC01",
"isActive": true,
"isCVVRequired": false,
"isNominated": false,
"isRechargeable": true,
"name": "TC01"
},
{
"amountChargeLimit": 5000.0,
"cardNumberLength": 11,
"cardTypePrefixRange": [
{
"_id": "5f45575d830a697a4012df40",
"creationAt": "2020-08-25T18:24:29Z",
"isSuggested": false,
"prefixEnd": 3000,
"prefixStart": 3000
}
],
"code": "tc02",
"customerValidation": "FILE",
"description": "TC02",
"isActive": false,
"isCVVRequired": true,
"isNominated": true,
"isRechargeable": true,
"name": "TC02"
}
]
}
Servicio De Consulta de Mapas
PROMO expone un servicio que permite consultar mapas utilizando solo el número de mapa y como respuesta se obtiene el xml del mapa de la misma forma que se obtiene por la opcion de "descargar".
Como en el caso de los servicios REST previamente descriptos se necesita una authorizacion via OAuth2.
La siguiente figura muestra el contenido del request de ejemplo:
Donde:
Operation: valor getMaps para obtener el mapa solicitado.
companyId: identificacion o codigo de empresa la cual realiza el request.
mapNumber: Numero de mapa solicitado.
La respuesta es del tipo:
<?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>
<ack>0</ack>
<message>OK</message>
<maps>
<map version:="5">
<?xml version="1.0" encoding="iso-8859-1"?>
<promo-engine start-date="15/01/2019 00:00" end-date="22/01/2084 23:59" validity-after-void="365" map-version="5" suggest="conditional">
<parameter key="Logging" value="true" />
<parameter key="LogConfigurationFile" value="logrsca.xml" />
<parameter key="LogConfigurationCategory" value="com.synthesis.promo" />
<parameter key="Descriptors" value="descriptor.properties" />
<parameter key="DAOConfigurationFeatures" value="com.synthesis.promo.engine.dao.ConfigurationFeatures" />
<parameter key="EvaluationAlgorithmClass" value="com.synthesis.promo.engine.evaluation.InStepsAlgorithm" />
<promotions>
<promotion nro="5c3df6e0f7a021227ca8f7d4" name="Promociòn 10% de Descuento SKU 1" code="Promociòn 10% de Descuento SKU 1" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="true" suggest="not" descriptor="Promociòn 10% de Descuento SKU 1">
<sets>
<set name="5c3df6f6f7a021227ca8f7d8" type="item" attribute="code" comparator="Into" value="1" />
</sets>
<condition type="basic" name="Exists">
<parameter key="use-set" value="5c3df6f6f7a021227ca8f7d8" />
</condition>
<benefits>
<benefit instance="PercentageDiscount" nro="5c3df748f7a021227ca8f7dc">
<parameter key="displayMessage" value="Promociòn 10% de Descuento SKU 1" />
<parameter key="printerMessage" value="Promociòn 10% de Descuento SKU 1" />
<parameter key="TLOGMessage" value="Promociòn 10% de Descuento SKU 1" />
<parameter key="applicationMethod" value="lineByLine" />
<parameter key="prorationMethod" value="proportional" />
<parameter key="applicationPriceType" value="benefited-price" />
<parameter key="name" value="5c3df6e0f7a021227ca8f7d4" />
<parameter key="percent" value="10" />
<parameter key="unit" value="qty" />
<applied-elements>
<use-set name="5c3df6f6f7a021227ca8f7d8" />
</applied-elements>
</benefit>
</benefits>
</promotion>
<promotion nro="5c3dfcd5f7a021227ca8f807" name="Promocion 3x2 en SKU 2" code="Promocion 3x2 en SKU 2" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="true" suggest="always" descriptor="Con 3 items del SKU 2 obtendra Promocion 3x2 en SKU 2">
<sets>
<set name="5c3dfd00f7a021227ca8f80c" type="item" attribute="code" comparator="Into" value="2" />
</sets>
<combo>
<combo-component min="3" max="3" attribute="qty" use-set="5c3dfd00f7a021227ca8f80c" />
</combo>
<benefits>
<benefit instance="PercentageDiscount" nro="5c3dfd52f7a021227ca8f80e">
<parameter key="displayMessage" value="Promocion 3x1 en SKU 2" />
<parameter key="printerMessage" value="Promocion 3x1 en SKU 2" />
<parameter key="TLOGMessage" value="Promocion 3x1 en SKU 2" />
<parameter key="applicationMethod" value="resume" />
<parameter key="prorationMethod" value="proportional" />
<parameter key="applicationPriceType" value="benefited-price" />
<parameter key="name" value="5c3dfcd5f7a021227ca8f807" />
<parameter key="percent" value="100" />
<parameter key="unit" value="qty" />
<applied-elements>
<use-set name="5c3dfd00f7a021227ca8f80c" max="1.0" attribute="qty" />
</applied-elements>
</benefit>
</benefits>
</promotion>
<promotion nro="5c3dffd1f7a021227ca8f82e" name="Promocion Cupon de Regalo en SKU 3" code="Promocion Cupon de Regalo en SKU 3" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="true" suggest="not">
<sets>
<set name="5c3e0041f7a021227ca8f835" type="item" attribute="code" comparator="Into" value="3" />
</sets>
<condition type="basic" name="Exists">
<parameter key="use-set" value="5c3e0041f7a021227ca8f835" />
</condition>
<benefits>
<benefit instance="CouponBenefit" nro="5c3e0001f7a021227ca8f832">
<parameter key="displayMessage" value="Promocion Cupon de Regalo en SKU 3" />
<parameter key="printerMessage" value="Promocion Cupon de Regalo en SKU 3" />
<parameter key="TLOGMessage" value="Promocion Cupon de Regalo en SKU 3" />
<parameter key="applicationMethod" value="resume" />
<parameter key="prorationMethod" value="proportional" />
<parameter key="applicationPriceType" value="benefited-price" />
<parameter key="name" value="5c3dffd1f7a021227ca8f82e" />
<parameter key="qty" value="1" />
<parameter key="couponid" value="tc01" />
<applied-elements>
<use-set name="5c3e0041f7a021227ca8f835" max="1.0" attribute="qty" />
</applied-elements>
</benefit>
</benefits>
</promotion>
</promotions>
<evaluation-algorithm>
<step>
<function name="ALL">
<function name="SIMPLE">
<promotion-usage name="Promociòn 10% de Descuento SKU 1" />
</function>
<function name="SIMPLE">
<promotion-usage name="Promocion 3x2 en SKU 2" />
</function>
<function name="SIMPLE">
<promotion-usage name="Promocion Cupon de Regalo en SKU 3" />
</function>
</function>
</step>
</evaluation-algorithm>
</promo-engine>
</map>
</maps>
</promoCoreResponse>
Donde se observa:
ack: resultado del request, donde 0 es procesamiento correcto. (Ver codigos de respuesta ack mas arriba en este documento).
message: es el mensaje de error resultante.
maps: tag general que contiene los elementos map retornados en la respuesta. Cada elemento map, contiene todos los elementos y tags que contiene un mapa como cuando es descargado a archivo.
Servicio De Consulta de Promociones Distribuidas
PROMO expone un servicio que permite consultar promociones distribuidas utilizando un filtro por compañía (obligatorio) y parámetros de filtros opcionales (tienda/as, región/es, código/os) y como respuesta se obtiene un xml con las promociones obtenidas.
Como en el caso de los servicios REST previamente descriptos se necesita una autorización via OAuth2.
La siguiente figura muestra el contenido del request de ejemplo:
Donde:
Operation (obligatorio): valor getPromotions para obtener promociones.
companyId (obligatorio): identificación o código de empresa la cual realiza el request.
stores (opcional): Tiendas a la que pertenece la / las promociones.
regions (opcional): Zonass a la que pertenece la / las promociones.
promoCode (opcional): Código / os de promociones solicitadas
La respuesta es del tipo:
<?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>
<ack>0</ack>
<message value="" />
<promotions>
<promotion nro="5c6c61f053c6832cc00eec0f" name="2 plays 1 xbox gratis" code="Promo1" className="com.synthesis.promo.engine.promotion.ConditionXComboPromotion" reportParticipants="false" suggest="not">
<sets>
<set name="5c6c689153c6832cc00eec24" type="item" attribute="code" comparator="Into" value="111" />
<set name="5c6c625853c6832cc00eec13" type="item" attribute="code" comparator="Into" value="111" />
<set name="5c6c628d53c6832cc00eec15" type="item" attribute="code" comparator="Into" value="112" />
<set name="5c6c6aae53c6832cc00eec38" type="item" attribute="code" comparator="Into" value="112" />
</sets>
<condition type="basic" name="Exists">
<parameter key="use-set" value="5c6c689153c6832cc00eec24" />
</condition>
<combo>
<combo-component min="2" max="2" attribute="qty" use-set="5c6c625853c6832cc00eec13" />
<combo-component min="1" max="1" attribute="qty" use-set="5c6c628d53c6832cc00eec15" />
</combo>
<benefits>
<benefit instance="PercentageDiscount" nro="5c6c64fd53c6832cc00eec19">
<parameter key="displayMessage" value="2 plays 1 xbox gratis" />
<parameter key="printerMessage" value="2 plays 1 xbox gratis" />
<parameter key="TLOGMessage" value="2 plays 1 xbox gratis" />
<parameter key="applicationMethod" value="resume" />
<parameter key="prorationMethod" value="proportional" />
<parameter key="applicationPriceType" value="benefited-price" />
<parameter key="name" value="5c6c61f053c6832cc00eec0f" />
<parameter key="percent" value="100" />
<parameter key="unit" value="qty" />
<applied-elements>
<use-set name="5c6c6aae53c6832cc00eec38" />
</applied-elements>
</benefit>
</benefits>
</promotion>
<promotion nro="5c6c61f053c6832cc00eec0frest" name="2 plays 1 xbox gratisrest" code="Promo2" className="com.synthesis.promo.engine.promotion.ConditionXComboPromotion" reportParticipants="false" suggest="not">
<sets>
<set name="5c6c689153c6832cc00eec24" type="item" attribute="code" comparator="Into" value="111" />
<set name="5c6c625853c6832cc00eec13" type="item" attribute="code" comparator="Into" value="111" />
<set name="5c6c628d53c6832cc00eec15" type="item" attribute="code" comparator="Into" value="112" />
<set name="5c6c6aae53c6832cc00eec38" type="item" attribute="code" comparator="Into" value="112" />
</sets>
<condition type="basic" name="Exists">
<parameter key="use-set" value="5c6c689153c6832cc00eec24" />
</condition>
<combo>
<combo-component min="2" max="2" attribute="qty" use-set="5c6c625853c6832cc00eec13" />
<combo-component min="1" max="1" attribute="qty" use-set="5c6c628d53c6832cc00eec15" />
</combo>
<benefits>
<benefit instance="PercentageDiscount" nro="5c6c64fd53c6832cc00eec19">
<parameter key="displayMessage" value="2 plays 1 xbox gratis" />
<parameter key="printerMessage" value="2 plays 1 xbox gratis" />
<parameter key="TLOGMessage" value="2 plays 1 xbox gratis" />
<parameter key="applicationMethod" value="resume" />
<parameter key="prorationMethod" value="proportional" />
<parameter key="applicationPriceType" value="benefited-price" />
<parameter key="name" value="5c6c61f053c6832cc00eec0frest" />
<parameter key="percent" value="100" />
<parameter key="unit" value="qty" />
<applied-elements>
<use-set name="5c6c6aae53c6832cc00eec38" />
</applied-elements>
</benefit>
</benefits>
</promotion>
</promotions>
</promoCoreResponse>
Donde se observa:
ack: resultado del request, donde 0 es procesamiento correcto. (Ver códigos de respuesta ack mas arriba en este documento).
message: es el mensaje de error resultante.
promotions: tag general que contiene los elementos promotion retornados en la respuesta. Cada elemento promotion, contiene todos los elementos y tags que contiene una promoción.
Servicio De Consulta de Promoción
PROMO expone tres servicios que permiten consultar una promoción utilizando un filtro por compañía (obligatorio) y consultar mediante número de promoción o código de promoción o número de beneficio de promoción y como respuesta se obtiene un xml con la promoción obtenida.
Como en el caso de los servicios REST previamente descriptos se necesita una autorización via OAuth2.
Las siguientes figuras muestran los contenidos de los request mencionados
|
|
|
|---|
Donde:
Operation (obligatorio): valor getPromotionsByNro, getPromotionsByCode o getPromotionsByBenefitNro.
companyId (obligatorio): identificación o código de empresa la cual realiza el request.
nro (obligatorio): para una búsqueda mediante el número de promoción o para una búsqueda mediante el número de benefició de promoción.
promoCode (obligatorio): para una búsqueda mediante el código de promoción
La respuesta es del tipo:
<?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>
<ack>0</ack>
<message value="" />
<promotions>
<promotion nro="5c9cd81353c6832f848f8ffb1" name="promoParaCancelar1" code="Promo1" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not">
<sets>
<set name="5c9cd83053c6832f848f8ffe" type="item" attribute="code" comparator="Into" value="111" />
</sets>
<condition type="basic" name="Exists">
<parameter key="use-set" value="5c9cd83053c6832f848f8ffe" />
</condition>
<benefits>
<benefit instance="PercentageDiscount" nro="5c9cd86f53c6832f848f9001">
<parameter key="displayMessage" value="promoParaCancelar" />
<parameter key="printerMessage" value="promoParaCancelar" />
<parameter key="TLOGMessage" value="promoParaCancelar" />
<parameter key="applicationMethod" value="resume" />
<parameter key="prorationMethod" value="proportional" />
<parameter key="applicationPriceType" value="benefited-price" />
<parameter key="name" value="5c9cd81353c6832f848f8ffb1" />
<parameter key="percent" value="10" />
<parameter key="unit" value="qty" />
<applied-elements>
<use-set name="5c9cd83053c6832f848f8ffe" />
</applied-elements>
</benefit>
</benefits>
</promotion>
</promotions>
</promoCoreResponse>
Donde se observa:
ack: resultado del request, donde 0 es procesamiento correcto. (Ver códigos de respuesta ack más arriba en este documento).
message: es el mensaje de error resultante.
promotions: tag general que contiene los elementos promotion retornados en la respuesta. Cada elemento promotion, contiene todos los elementos y tags que contiene una promoción.
Servicio Próximo Número de tarjeta
PROMO expone un servicio que 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 Tocken (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>
Extensión en consulta de Tarjeta con el loyaltyValidation
Actualmente, desde el punto de venta puede enviarse una consulta de tarjeta utilizando el status LoyaltyValidation, en donde se informa el Id de tarjeta y el tipo, y la consola retorna todos los datos referentes a la tarjeta consultada.
En caso de enviar solo el Type de la tarjeta en una consulta de LoyaltyValidation, se devolverá el próximo número de tarjeta inactiva y sin cliente asociado disponible.
Por ejemplo, el último número de tarjeta activo para el tipo "aaa" es el 333000000000000007, al realizar la consulta solo con el tipo de tarjeta, Promo devolverá el id de tarjeta 333000000000000008 que corresponde al próximo número de tarjeta inactivo y sin cliente disponible.
<?xml version="1.0" encoding="UTF-8"?> <message companyId="C2" store="1" terminal="1" date-time="2018-07-18 10:16:00" init-tck="true" messageId="1" void-trx="false" response="true" status="loyaltyValidation" evaluate="true" tckpath="Y" suggest="true"> <loyaltycard-add seq="5" type="2" /> </message>
<?xml version="1.0" encoding="UTF-8"?><message ack="0" companyId="C2" engine="6.2.0" mapversion="0" messageId="1" store="1" terminal="1" transaction="C2_1_1_20180718135406"> <loyalty> <loyaltycards> <loyaltycard ack="0" id="2220000000000019" type="2"/> </loyaltycards> <coupons/> <errors/> <customers/> </loyalty> </message>
Servicio de Reporte de Promociones
(> v7.EP2.1)
PROMO expone un servicio que permite consultar la misma información que se obtiene del Reporte de Promociones por Consola (ver dicho reporte para información de filtros y datos).
http://localhost:8080/promo/api/rest/reports/transaction/promotion?companyId=napse&limit=50000&offset=0&dateFrom=20210512&dateTo=20210519
Los parámetros de entrada de la consulta son:
Propiedad | Tipo de dato | Descripción |
| companyId | Alfanumérico | Código de la compañía |
limit | Numérico | Cantidad de registros de movimientos a retornar con un máximo de 50.000 por consulta. Default: 25 |
| offset | Numérico | Registro desde el cual comenzar el conteo hasta "limit" registros. Default: 0 |
dateFrom | Numérico | Fecha de Inicio en formato YYYYMMDD. |
dateTo | Numérico | Fecha de Final en formato YYYYMMDD. |
transactionType | Alfanumérico | Opcionalmente se puede filtrar por tipo de Transacción: SALES o RETURN. Default: '' (Todas) |
| store | Alfanumérico | Código de Tienda por el cual se quiere filtrar. Default: '' (Todas) |
| pname | Alfanumérico | El nombre de la Promoción por el cual se desea filtrar. Default: '' (Todas) |
| pcode | Alfanumérico | El código de la Promoción por la cual se desea filtrar. Default: '' (Todas) |
Ejemplo de parámetros de entrada de la consulta en Postman:
La Respuesta será del tipo JSON con los siguientes parámetros:
Propiedad | Tipo de dato | Descripción |
| Records | Vector | Cada uno de los registros que componen el reporte |
Header | Vector | Encabezado con información adicional |
{
"records:": "[{\"transactionId\":\"napse_Tienda1_1_20210519110000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Descuento porcentaje\",\"itemCode\":\"456\",\"discountApply\":500.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"19/05/2021 11:00\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo limite1\",\"store\":\"Tienda1\",\"subTotal\":500.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210519100000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Descuento porcentaje\",\"itemCode\":\"456\",\"discountApply\":500.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"19/05/2021 10:00\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo limite1\",\"store\":\"Tienda1\",\"subTotal\":500.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210519091000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Descuento porcentaje\",\"itemCode\":\"456\",\"discountApply\":500.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"19/05/2021 09:10\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo limite1\",\"store\":\"Tienda1\",\"subTotal\":500.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210517091000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"555\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"17/05/2021 09:10\",\"transactionType\":\"Devolución\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo EMITE CUPON Impreso\",\"store\":\"Tienda1\",\"subTotal\":1000.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210517090000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"555\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"17/05/2021 09:00\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo EMITE CUPON Impreso\",\"store\":\"Tienda1\",\"subTotal\":1000.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210513100000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"555\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"13/05/2021 10:00\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo EMITE CUPON Impreso\",\"store\":\"Tienda1\",\"subTotal\":1000.0,\"conditionTimeRange\":\"Indefinida\"}]",
"header": {
"total": 6,
"offset": 0,
"limit": 50000
}
}
Cada elemento del Vector Records contendrá los siguientes parámetros correspondientes a cada una de las columnas del informe:
Propiedad | Tipo de dato | Descripción |
| transactionId | Alfanumérico | Código de la transacción |
offline | Booleano | Verdadero si la transacción fue realizada en modo offline |
| unitPrice | Numérico | Precio unitario del producto |
benefitClass | Alfanumérico | Clase de beneficio |
itemCode | Alfanumérico | Código de Producto |
discountApply | Numérico | Descuento Aplicado |
| deploymentChannels | Alfanumérico | Canal de Publicación |
| date | Alfanumérico | Fecha de la transacción |
| transactionType | Alfanumérico | Tipo de Transacción |
| campaign | Alfanumérico | Campaña |
| quantity | Numérico | Cantidad del Producto |
| promotionCode | Alfanumérico | Código de Promoción |
| promotionName | Alfanumérico | Nombre de la Promoción |
| store | Alfanumérico | Tienda |
| subTotal | Numérico | Subtotal de la transacción |
| conditionTimeRange | Alfanumérico | Condición de Fecha/hora si aplica. |
Cada elemento del Vector Header contendrá los siguientes parámetros Informativos:
Propiedad | Tipo de dato | Descripción |
| total | Numérico | Total de Registros disponibles |
offset | Numérico | offset solicitado actualmente |
| limit | Numérico | Limite solicitado actualmente |
Esta información sirve para mantener una paginación como sucede en pantalla pero a nivel servicio. Digamos:
Primer consulta: offset: 0, limit: 25 → retorna la primer página de 25 registros y me informa un total de 500.
Segunda consulta: offset: 25, limit 25 → retorna la segunda pagina, es decir registros 26 a 50.
En lo sucesivo se podrá ir pidiendo paginas hasta llegar a offset: 475, limit 25.
También se podría realizar un paginado de a 100 registros por consulta, etc. (limit: 100).
EJEMPLO 1:
Solicitamos un reporte de Promociones para la compañía myCompany, entre el 21/11/2020 y el 04/12/2020, limitado a 25 registros a partir del 500 (esto es el equivalente a la página 21 en pantalla), para el código de Promoción 10549
Obteniéndose la siguiente respuesta:
Ejemplo {
"records:": "[{\"transactionId\":\"xx_0621_002_20201202123540\",\"offline\":false,\"unitPrice\":10400.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"1580203\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"02/12/2020 04:35\",\"transactionType\":\"Venta\",\"campaign\":\"Mercadeo\",\"quantity\":1.0,\"promotionCode\":\"10549\",\"promotionName\":\"MY PROMO-10549\",\"store\":\"0621 - MY STORE \",\"subTotal\":10400.0,\"conditionTimeRange\":\"\r\nEntre las fechas con horario 26/11/2020 02:00-06/12/2020 01:59\r\n\"},{\"transactionId\":\"xx_0621_001_20201202112635\",\"offline\":false,\"unitPrice\":5600.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"720190\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"02/12/2020 03:26\",\"transactionType\":\"Venta\",\"campaign\":\"Mercadeo\",\"quantity\":1.0,\"promotionCode\":\"10549\",\"promotionName\":\"MY PROMOTION-10549\",\"store\":\"0621 - MY STORE\",\"subTotal\":5600.0,\"conditionTimeRange\":\"\r\nEntre las fechas con horario 26/11/2020 02:00-06/12/2020 01:59\r\n\"}]",
"header": {
"total": 504,
"offset": 500,
"limit": 25
}
}
|
.
Consola: Servicios REST de Carga de Datos
Aquí se presentan los servicios provistos para enviar o cargar información en PROMO.
Antes de consumir el servicio debe obtenerse el TOKEN de identificación como se explica en "Seguridad: Autenticación de Sistemas Externos con los Servicios"
Precios: Servicio de Carga De Lista Cero
Se creo un Servicio Rest que permite la carga de los productos de una lista cero, El Mismo recibe la información y sera procesada de manera asincrónica, es decir recibe la información y luego sera procesada.
La Lista cero es la lista base donde se encontraran todos los precios de los productos, la misma tiene la prioridad mas baja de las listas (El motor al consultar los precios evalúa las listas existentes de prioridad de mayor a menor).
La Lista cero será enviada desde un sistema externo a promo, el proceso crea y actualiza los precios enviados.
En la consola se agrego la pantalla de Monitoreo de Importaciones. en la sección de soporte, desde esta pantalla se podrá ver el resultado de la importación, ver la información enviada en la importación (menú contextual Contenido), el detalle de la importación mostrará el total de los registros los procesados correctamente y los que tuvieron errores, estos últimos en caso de existir se verán en la pantalla paginados o se podrá descargar los mismos en un archivo de texto. El monitor también permite el re proceso de la importaciones.
El Método es un POST a la siguiente dirección: <promo>/api/rest/priceList con el siguiente body:
{
"companyId": "napse",
"store": "napse",
"items": [
{
"sku": "0527-1537",
"salePrice": 69406.77,
"costPrice": 50942.13,
"saleCreditPrice": 119716.68,
"magnitudePrice": 829,
"measuredUnit": "cm3",
"supplierItem": "PR3",
"supplierFinancial": "PR2",
"supplierItemAmount": 52471,
"supplierFinancialAmount": 53604,
"saleWholesalePrice": 31858,
"saleWholesaleLimit": 6081,
"limit": 794,
"enabledDate": "2018-12-25T10:42:25Z"
"discountable":true,
"manualDiscount":false
},
{
"sku": "66897-001",
"salePrice": 39123.0,
"costPrice": 10452.59,
"saleCreditPrice": 42433.6,
"magnitudePrice": 371,
"measuredUnit": "kg",
"supplierItem": "PR2",
"supplierFinancial": "PR2",
"supplierItemAmount": 52551,
"supplierFinancialAmount": 21423,
"saleWholesalePrice": 78603,
"saleWholesaleLimit": 9691,
"limit": 2982,
"enabledDate": "2019-01-20T10:41:55Z"
}
]
}
La respuesta del mismo será en caso Ok (Http.status=200)
{
"status": "Informacion Recibida OK",
"description": "La lista de precios será procesada"
}
En caso de Error: (Http.status=400)
{
"status": "companyId is Required",
"description": "Debe enviar el campo companyId"
}
{
"status": "companyId is Invalid",
"description": "Debe enviar el campo companyId valido"
}
Nota: La compania enviada en el rest debe tener el modulo de precios habilitado para que el servicio se habilite
Propiedad | Tipo de dato | Descripción |
| companyId | Alfanumérico | Código de la compania |
| store | Alfanumérico | Código de la tienda de Promo |
sku | Alfanumérico | Código del producto |
salePrice | Numérico | Precio de venta |
costPrice | Numérico | Opcional. Precio de costo |
saleCreditPrice | Numérico | Precio de crédito |
magnitudePrice | Numérico | Opcional. Precio por magnitud (kilo, litro, bulto, etc) |
| measuredUnit | Alfanumérico | Opcional. unidad de medida |
supplierItem | Alfanumérico | Opcional.Es el código del proveedor del ítem |
| supplierItemAmount | Numérico | Opcional. Es el monto que el proveedor reconoce (monto del recupero) |
| supplierFinancial | Alfanumérico | Opcional. Es el código del proveedor financiero del ítem |
| supplierFinancialAmount | Numérico | Opcional. Es el monto que el proveedor Financiero reconoce (monto del recupero) |
| saleWholesalePrice | Numérico | Opcional.Precio mayorista |
| saleWholesaleLimit | Numérico | Opcional. Cantidad a partir de la cual aplica el precio mayorista |
| limit | Numérico | Opcional.(límite de unidades que se podrán vender a ese precio) |
| enabledDate | Fecha | Fecha que indica apartir de cuando el precio es valido (FORMATO ISO 8601 (UTC)) |
discountable | Booleano | Opcional. determina si el item se le puede aplicar descuento.(de omitir dicho campo por default sera true) |
manualDiscount | Booleano | Opcional. determina si el item se le puede aplicar descuento Manual .(de omitir dicho campo por default sera true) |
El proceso de importación de la lista cero, insertara/actualizara el producto en la lista cero de la tienda, en caso de tener el campo enable_date con una fecha futura,ese precio se habilitara en el momento que sea el enable_date.
El proceso de actualización de precios para una lista cero, lockea mientras se esta procesando la actualización, en caso inesperado error no contemplado y quede lockeado, hay un configuration data que determina el tiempo en minutos de espera de un lockeo de actualización que es el siguiente (luego de ese tiempo se podrá volver a correr el proceso para esa lista cero).
ConfigurationData.readAsInteger(companyId, "prices", "priceList.lockForUpate",15)
Servicio de Importación de Catálogos
PROMO expone este nuevo servicio para brindar una alternativa en la carga/recepción de catálogos que, hasta la presente versión, podía realizarse únicamente vía archivos. Para comprender esta sección se recomienda referirse al manejo de catálogos en el manual del usuario.
El esquema de autenticación es el mismo que en los demás servicios REST presentados aquí (ver mas arriba).
Una vez obtenido el token de acceso, el servicio puede ser invocado utilizando el método POST, desde la URL: <promo>/api/rest/catalogs
El formato general del request es:
{
"companyId": "myCompanyId",
"catalog":"CatalogId",
"params":[
"param1":"param1value",
"paramN":"paramNvalue"
],
"items": [
{.... primer item .......},
{.... otro item .......},
{.... otro item .......},
{.... otro item .......},
{.... otro item .......},
]
}
donde
| Campo | Descripción | Tipo de Dato |
|---|---|---|
companyId |
| alfanumérico |
catalog | identificador del catálogo | alfanumérico |
| params | Parametros que dependeran del catálogo | Listado de objetos de tipo clave, valor. Cada catalogo puede tener sus parametros especificos, pero como valor genérico tenemos:
[...] "params": [ [...] Importante No aplica a tarjetas de fidelidad y asignación de convenios. |
| items | Registros a importar | Colección de objetos dependientes de cada catálogo Atributos dinamicos. Para el Catalogo de Ítems (catalogItem) podrán incorporarse a la carga de los atributos dinámicos de los ítems que se estén dando de alta. Para ello deberá especificarse el nombre de los atributos dinámicos dados de alta por consola dentro del tag "items": [
{.... primer item .......}]Los Atributos dinámicos cargados vía Servicio serán tomados para la validación entre atributos del elemento Producto en la definición de condiciones de una promoción, cuando ésta funcionalidad se encuentre habilitada en consola. (Ver PROMO - Manual de Usuario Final - 7) Ejemplo de catalogItem con Atributos dinámicos. {
"companyId": "exito",
"catalog": "catalogItem",
"params": [],
"items": [{
"operation": "U",
"code": "111",
"name": "item A",
"unitprice": 5000,
"level1": "depart-1",
"level2": "family-1",
"level3": "category-1",
"level4": "subcategory-1",
"supplier": "tecno-1",
"brand": "Marca-1",
"detail": "detalle-1",
"sublinea":"sublinea1"
}]
}
|
Cada uno de los items dependerá del catalogo en su formato, pero existe un campo común a todos:
| Campo | Descripcion | Tipo de Dato |
|---|---|---|
operation | La operación a realizar sobre el elemento. Los valores posibles son:
| Alfanumérico |
La respuesta será del tipo:
{
"status": "200",
"description": "CatalogCountry",
"detail": {
"result": "ok",
"detail": "Info adicional"
}
}
donde:
| Campo | Descripción | Tipo de Dato | Posibles valores |
|---|---|---|---|
status | codigo de Respuesta | alfanumérico | 200 (válido), 400 (errores de validación o de sintaxis json), 500 (error genérico) |
description | identificador del catálogo | alfanumérico | Cada uno de los nombre de los catálogos importables por mensaje rest, o bien cadena vacía si no es posible obtenerlos (por ej. ante un error de sintaxis json). |
| detail | Información adicional | Objeto | Clave result, con los resultados posibles, es decir, ok o error. Clave detail, con valor correspondiente al mensaje informativo de validación, error, o procesamiento válido. |
Consideraciones
- El número de registros por paquete (request) estará limitado a 1000 items para no afectar la performance y que las respuestas puedan ser procesadas.
- En caso de error se informaran los registros erroneos pero los que han resultado correctos 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 lineas con error y las correctas. Los resultados podrán visualizarse en la consola en la pantalla de Monitor de Importación.
- El proceso utiliza semaforos para evitar la concurrencia de clientes que pretendan procesar en paralelo ya que implica posibilidad de errores en las validaciones.
OPERACIONES SOBRE CLIENTES
Un cliente está conformado por los siguientes datos. Datos como gender, identificationType, customerType, addressCountry, addressState, y addressCity, corresponden al código de cada uno de ellos y deberán importarse previamente antes de realizar cualquier operación sobre un cliente. En el caso particular de addressCountry, addressState, y addressCity, deberán importarse en ese orden debido a que se validará que una provincia/estado esté dentro de un país, y que una ciudad esté dentro de una provincia.
| Campo | Descripcion | Tipo de dato |
|---|---|---|
| code | Codigo | cadena libre |
| name | Nombre | cadena libre |
| lastName | Apellido | cadena libre |
| gender | Genero | Depende de los valores cargados en el catálogo a tal fin. |
| birthDate | Fecha de nacimiento | Formato: año-mes-día siendo el año de cuatro dígitos, y el mes y el día de dos dígitos |
| identificationType | Tipo de identificacion | Depende de los valores cargados en el catálogo a tal fin |
| identifier | El número de identificación del cliente | por ej. el número de documento de identidad |
| identificationExpiration | Fecha de Expiración de la identificación | Formato: año-mes-día siendo el año de cuatro dígitos, y el mes y el día de dos dígitos |
| nacionality | Nacionalidad | Cadena Libre. |
| Direccion de correo electrónico | Cadena libre. | |
| customerType | Tipo de Cliente | Depende de los valores cargados en el catálogo a tal fin |
| address | Dirección | Cadena libre |
| addressCountry | pais | Depende de los valores cargados en el catálogo a tal fin. |
| addressState | Estado/Provincia | Depende de los valores cargados en el catálogo a tal fin. |
| addressCity | Ciudad | Depende de los valores cargados en el catálogo a tal fin |
| addressPostalCode | Codigo Postal | Cadena libre |
| phone | Teléfono | Cadena libre. |
| isActive | Activo o No | Boolea |
Cuando desde la consola se indique que deben de Validar catálogos relacionados al catálogo de clientes, sera requerida la carga de los catalogos relacionados previo a la carga del catalogo de cliente.
Se importan entonces las entidades relacionadas previo a la importación de los clientes.
Catálogo IDTYPE. Este catálogo define los tipos de documento o identificacion válidos.
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogIdType",
"params": [],
"items": [
{
"code": "dni",
"description": "Documento de identidad",
"operation": "I"
},
{
"code": "le",
"description": "Libreta de enrolamiento",
"operation": "I"
}
]
}
Catálogo GENDER. Este catálogo define los tipos de género válidos.
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogGender",
"params": [],
"items": [
{
"code": "M",
"description": "Male",
"operation": "I"
},
{
"code": "F",
"description": "Female",
"operation": "I"
}
]
}
Catálogo CUSTOMERTYPE. Este catálogo define los tipos de clientes válidos
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogCustomerType",
"params": [],
"items": [
{
"code": "vip",
"description": "Cliente vip",
"operation": "I"
},
{
"code": "gold",
"description": "Cliente gold",
"operation": "I"
},
{
"code": "silver",
"description": "Cliente silver",
"operation": "I"
}
]
}
Catálogo COUNTRY. Este catálogo define los paises válidos.
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogCountry",
"params": [],
"items": [
{
"code": "ar",
"description": "Argentina",
"operation": "I"
},
{
"code": "it",
"description": "Italia",
"operation": "I"
},
{
"code": "es",
"description": "España",
"operation": "I"
}
]
}
Catálogo STATE. Este catálogo define las provincias válidas.
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogState",
"params": [],
"items": [
{
"code": "bsas",
"description": "Buenos Aires",
"country": "ar",
"operation": "I"
},
{
"code": "cor",
"description": "Córdoba",
"country": "ar",
"operation": "I"
}
]
}
Catálogo CITY. Este catálogo define las ciudades válidas
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogCity",
"params": [],
"items": [
{
"code": "tig",
"description": "Tigre",
"state": "bsas",
"operation": "I"
},
{
"code": "lm",
"description": "Los molinos",
"state": "cor",
"operation": "I"
},
{
"code": "sidr",
"description": "San isidro",
"state": "bsas",
"operation": "I"
}
]
}
Importación de nuevos clientes.
Una vez realizadas las importaciones anteriores, y considerando sus códigos, se pueden realizar altas, modificaciones, y eliminaciones de clientes.
Por ej. en este caso se dan de alta dos clientes:
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogCustomer",
"params": [],
"items": [
{
"code": "cod1",
"name": "Alberto",
"lastName": "Pérez",
"gender": "M",
"birthDate": "1950-01-01",
"identificationType": "le",
"identifier": "11112222",
"identificationExpiration": "2050-01-01",
"nacionality": "argentino",
"email": "[email protected]",
"customerType": "vip",
"address": "diagonal 12 2233",
"addressCountry": "ar",
"addressState": "bsas",
"addressCity": "tig",
"addressPostalCode": "2222",
"phone": "11111111",
"isActive": "true",
"operation": "I"
},
{
"code": "cod2",
"name": "Ángela",
"lastName": "Gonzales",
"gender": "F",
"birthDate": "1960-01-01",
"identificationType": "dni",
"identifier": "99998888",
"identificationExpiration": "2050-01-01",
"nacionality": "argentina",
"email": "[email protected]",
"customerType": "gold",
"address": "diagonal 50 2211",
"addressCountry": "ar",
"addressState": "cor",
"addressCity": "lm",
"addressPostalCode": "5050",
"phone": "55555555",
"isActive": "true",
"operation": "I"
}
]
}
Eliminación y actualización de clientes.
En el siguiente ejemplo, se elimina el primer cliente (campo operation en R) y se actualiza el segundo cliente (campo operation en U) cambiando el email y el teléfono
{
"companyId": "{{COMPANYID}}",
"catalog": "CatalogCustomer",
"params": [],
"items": [
{
"code": "cod1",
"name": "Alberto",
"lastName": "Pérez",
"gender": "M",
"birthDate": "1950-01-01",
"identificationType": "le",
"identifier": "11112222",
"identificationExpiration": "2050-01-01",
"nacionality": "argentino",
"email": "[email protected]",
"customerType": "vip",
"address": "diagonal 12 2233",
"addressCountry": "ar",
"addressState": "bsas",
"addressCity": "tig",
"addressPostalCode": "2222",
"phone": "11111111",
"isActive": "true",
"operation": "R"
},
{
"code": "cod2",
"name": "Ángela",
"lastName": "Gonzales",
"gender": "F",
"birthDate": "1960-01-01",
"identificationType": "dni",
"identifier": "99998888",
"identificationExpiration": "2050-01-01",
"nacionality": "argentina",
"email": "[email protected]",
"customerType": "gold",
"address": "diagonal 50 2211",
"addressCountry": "ar",
"addressState": "cor",
"addressCity": "lm",
"addressPostalCode": "5050",
"phone": "90909090",
"isActive": "true",
"operation": "U"
}
]
}
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.
Un ejemplo de creación, inactivación o actualización de un conjunto de promociones, es el siguiente:
{
"companyId": "napse",
"promotions": [
{
"operation": "I",
"name": "Entrega de un cupon para proxima compra",
"code": "P2002",
"sets": {
"set": [
{
"name": "5feaf1324b10b84760e83f37",
"type": "item",
"attribute": "level1",
"comparator": "Into",
"value": "maderas"
},
{
"name": "5feaf13a4b10b84760e83f3a",
"type": "payment",
"attribute": "type",
"comparator": "Into",
"value": "card"
}
]
},
"condition": {
"type": "composite",
"name": "And",
"condition": [
{
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "5feaf1324b10b84760e83f37"
}
},
{
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "5feaf13a4b10b84760e83f3a"
}
}
]
},
"benefits": {
"benefit": {
"instance": "CouponBenefit",
"parameter": [
{
"key": "displayMessage",
"value": "Entrega de un cupon para proxima compra"
},
{
"key": "printerMessage",
"value": "Entrega de un cupon para proxima compra"
},
{
"key": "TLOGMessage",
"value": "Entrega de un cupon para proxima compra"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "name",
"value": "5feaf1224b10b84760e83f34"
},
{
"key": "qty",
"value": "1"
},
{
"key": "couponid",
"value": "001"
},
{
"key": "infoPos",
"value": "0"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {
"name": "5feaf1324b10b84760e83f37"
}
}
}
}
},
{
"operation": "U",
"name": "Entrega de puntos llevando 2 furadeiras",
"code": "3003",
"sets": {
"set": {
"name": "5feaf18c4b10b84760e83f45",
"type": "item",
"attribute": "level3",
"comparator": "Into",
"value": "furadeiras"
}
},
"combo": {
"combo-component": {
"min": "2",
"max": "2",
"attribute": "qty",
"use-set": "5feaf18c4b10b84760e83f45"
}
},
"benefits": {
"benefit": {
"instance": "PercentLoyaltyBenefit",
"nro": "5feaf1cd4b10b84760e83f4a",
"parameter": [
{
"key": "displayMessage",
"value": "Entrega de puntos llevando 2 furadeiras"
},
{
"key": "printerMessage",
"value": "Entrega de puntos llevando 2 furadeiras"
},
{
"key": "TLOGMessage",
"value": "Entrega de puntos llevando 2 furadeiras"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "name",
"value": "5feaf1794b10b84760e83f40"
},
{
"key": "percent",
"value": "50"
},
{
"key": "type",
"value": "3003"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {
"name": "5feaf18c4b10b84760e83f45"
}
}
}
}
},
{
"operation": "R",
"code": "P2001",
},
{
"operation": "I",
"name": "Descuento Fijo $ 20 en Marca Adidas",
"code": "P1001",
"sets": {
"set": {
"name": "5feaf0c44b10b84760e83f2f",
"type": "item",
"attribute": "brand",
"comparator": "Into",
"value": "adidas"
}
},
"condition": {
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "5feaf0c44b10b84760e83f2f"
}
},
"benefits": {
"benefit": {
"instance": "FixedDiscount",
"nro": "5feaf0d04b10b84760e83f32",
"parameter": [
{
"key": "displayMessage",
"value": "Descuento Fijo $ 20 en Marca Adidas"
},
{
"key": "printerMessage",
"value": "Descuento Fijo $ 20 en Marca Adidas"
},
{
"key": "TLOGMessage",
"value": "Descuento Fijo $ 20 en Marca Adidas"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "name",
"value": "5feaf0bc4b10b84760e83f2c"
},
{
"key": "amount",
"value": "20"
},
{
"key": "unit",
"value": "qty"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {
"name": "5feaf0c44b10b84760e83f2f"
}
}
}
}
},
{
"operation": "I",
"name": "30% de descuento, llevando mas de 12 con prefijo 6447",
"code": "0002",
"sets": {
"set": {
"name": "5fe236da14b8fc698cfd63d7",
"type": "item",
"attribute": "level3",
"comparator": "Into",
"value": "6447"
}
},
"combo": {
"combo-component": {
"min": "12",
"max": "12",
"attribute": "qty",
"use-set": "5fe236da14b8fc698cfd63d7"
}
},
"benefits": {
"benefit": {
"instance": "PercentageDiscount",
"nro": "5fddeba114b8fc9724882991",
"parameter": [
{
"key": "displayMessage",
"value": "30% de descuento, llevando mas de 12 con prefijo 6447"
},
{
"key": "printerMessage",
"value": "30% de descuento, llevando mas de 12 con prefijo 6447"
},
{
"key": "TLOGMessage",
"value": "30% de descuento, llevando mas de 12 con prefijo 6447"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "name",
"value": "5fddeb8414b8fc972488298a"
},
{
"key": "percent",
"value": "30"
},
{
"key": "unit",
"value": "qty"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {
"name": "5fe236da14b8fc698cfd63d7"
}
}
}
}
}
]
}
PARÁMETROS DE ENTRADA
| Campo | Descripción |
|---|---|
| companyId | Código de la compañía |
promotions | Conjunto de promociones a actualizar, pueden ser nuevas, actualizaciones o promociones que deseamos inactivar. |
| operation | I: Insertar / U: Actualizar / R: Cancelación |
| name | Nombre de la promoción |
code | Código univoco de la promoción |
| sets | Hace referencia a los conjuntos que definirán la condición y el beneficio de la promoción, por ejemplo:
|
| conditions | Hace referencia a la combinación de conjuntos que forman parte de la condición para obtener el beneficio. Ejemplo: Conjunto 1 AND conjunto 2. Productos con Marca X y Familia Y Ejemplo 2: Conjunto 1 AND conjunto 3 Productos con marca X y Medio de pago VISA |
| benefits | Hace referencia a los beneficios que se otorgarán si se cumplen las condiciones Los beneficios posibles son: NewPrice : Nuevo precio |
RESPUESTA DEL SERVICIO
Si la solicitud ha sido exitosa, se podrá visualizar la siguiente respuesta:
Request exitoso
{
"status": "Información Recibida OK",
"description": "La importación de promociones será procesada"
}
En el caso de indicar un código de compañía que no existe, visualizará la siguiente respuesta:
Error con compañía indicada
{
"status": "companyId is Invalid",
"description": "Debe enviar el campo companyId válido"
}
Ejemplo 1: invocando el servicio de importación masiva de promociones via CURL:
Ejemplo
curl -X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8-H "Content-type: application/json" -H "Accept: application/json" "http://localhost:8080/promo/api/rest/promotion/import"
Se enviará el siguiente request:
{
"companyId": "napse",
"promotions": [
{
"code": "P002",
"sets": {
"set": [
{
"name": "5feaf1324b10b84760e83f37",
"type": "item",
"attribute": "level1",
"comparator": "Into",
"value": "maderas"
},
{
"name": "5feaf13a4b10b84760e83f3a",
"type": "payment",
"attribute": "type",
"comparator": "Into",
"value": "card"
}
]
},
"condition": {
"type": "composite",
"name": "And",
"condition": [
{
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "5feaf1324b10b84760e83f37"
}
},
{
"type": "basic",
"name": "Exists",
"parameter": {
"key": "use-set",
"value": "5feaf13a4b10b84760e83f3a"
}
}
]
},
"benefits": {
"benefit": {
"instance": "CouponBenefit",
"parameter": [
{
"key": "displayMessage",
"value": "Entrega de un cupon para proxima compra"
},
{
"key": "printerMessage",
"value": "Entrega de un cupon para proxima compra"
},
{
"key": "TLOGMessage",
"value": "Entrega de un cupon para proxima compra"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "name",
"value": "5feaf1224b10b84760e83f34"
},
{
"key": "qty",
"value": "1"
},
{
"key": "couponid",
"value": "001"
},
{
"key": "infoPos",
"value": "0"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {
"name": "5feaf1324b10b84760e83f37"
}
}
}
}
},
{
"operation": "u",
"name": "Entrega de puntos llevando 2 furadeiras",
"code": "P003",
"sets": {
"set": {
"name": "5feaf18c4b10b84760e83f45",
"type": "item",
"attribute": "level3",
"comparator": "Into",
"value": "furadeiras"
}
},
"combo": {
"combo-component": {
"min": "2",
"max": "2",
"attribute": "qty",
"use-set": "5feaf18c4b10b84760e83f45"
}
},
"benefits": {
"benefit": {
"instance": "PercentLoyaltyBenefit",
"nro": "5feaf1cd4b10b84760e83f4a",
"parameter": [
{
"key": "displayMessage",
"value": "Entrega de puntos llevando 2 furadeiras"
},
{
"key": "printerMessage",
"value": "Entrega de puntos llevando 2 furadeiras"
},
{
"key": "TLOGMessage",
"value": "Entrega de puntos llevando 2 furadeiras"
},
{
"key": "applicationMethod",
"value": "resume"
},
{
"key": "prorationMethod",
"value": "proportional"
},
{
"key": "applicationPriceType",
"value": "benefited-price"
},
{
"key": "name",
"value": "5feaf1794b10b84760e83f40"
},
{
"key": "percent",
"value": "50"
},
{
"key": "type",
"value": "3003"
},
{
"key": "recoveryValue",
"value": "0"
},
{
"key": "recoveryType",
"value": ""
}
],
"applied-elements": {
"use-set": {
"name": "5feaf18c4b10b84760e83f45"
}
}
}
}
}
]
}
El cual recibirá una respuesta del tipo:
{
"status": "Información Recibida OK",
"description": "La importación de promociones será procesada"
}
Servicio de CANJE DE PUNTOS POR CATALOGO
(Desde 6.5.2)
Como soporte al Nuevo beneficio de Canje de Puntos por Catalogo (ver mas arriba), se deben especificar la tabla de productos que poseen equivalente en puntos a través de un catalogo definido para tal uso.
Siguiendo el formato especificado anteriormente tendremos:
| Campo | Valor |
|---|---|
| companyId | El código de la compañia correspondiente. |
| catalog | "CatalogRedeemBenefit". No se debe modificar. |
params | Un listado vacío. No se debe modificar. |
| items | Un listado con cada item del catálogo de Canje de puntos. |
Dentro de items, el formato es:
| Campo | Valor |
|---|---|
store | Código de tienda. Requerido. Alfanumérico. Si se aplica a todas las tiendas, el código de la tienda debe ser "-". |
code | Código del producto. Requerido. Alfanumérico. |
points | Puntos requeridos. Numérico con decimales. |
discountValue | Valor descuento. Numérico con decimales. |
discountType | Tipo descuento. Acepta sólo los valores "perc" (porcentaje), "fix" (descuento fijo), o bien, "nprice" (nuevo precio) |
operation | La operación a realizar sobre el elemento. Ver tabla con valores posibles. |
Así tendremos que un ejemplo de request para insertar registros en este catálogo será:
{
"companyId": "napse",
"catalog": "CatalogRedeemBenefit",
"params": [],
"items": [
{
"store": "1",
"code": "10",
"points": "10.5",
"discountValue":"15" ,
"discountType": "perc",
"operation": "I"
},
{
"store": "1",
"code": "20",
"points": "20.5",
"discountValue":"20" ,
"discountType": "fix",
"operation": "I"
},
{
"store": "-",
"code": "30",
"points": "50",
"discountValue":"25" ,
"discountType": "nprice",
"operation": "I"
}
]
}
Servicio de Asignación de Tarjetas de Fidelidad
Esta operación es el equivalente a la función de asignacion/actualización de tarjetas, mas la importación de clientes nuevos (Ver proceso actual de asignación de convenios). En este caso los campos serán:.
ASIGNACIÓN A UNA TARJETA DE UN CLIENTE, UN CONVENIO, Y SU MONTO.
Esta operación realiza la asignación de tarjeta, cliente, convenio, y monto. Debe existir previamente la tarjeta (activa o inactiva), un convenio activo, y el cliente, en caso de no existir, se da de alta. En relación al monto, se puede asignar un valor, ingresando el valor del monto; sumar un valor al monto que la tarjeta tiene, especificando el operador +; y para el caso de restar saldo se debe especificar el operador - (ver más abajo el ejemplo del campo amount).
Un esquema de ejemplo es el siguiente:
{
"companyId": "napse",
"catalog": "CatalogCardAssign",
"params": [
{
"cardType": "tipo1"
},
{
"contract": "convenio1"
}
],
"items": [
{
"operation": "I",
"id": "1111000000030",
"customer": "codCliente1",
"amount": "90.37",
"name": "Juan",
"surname": "Perez",
"gender": "hom",
"birthDate": "19900506",
"idType": "dni",
"identifier": "33334444",
"idDate": "21001005",
"nacionality": "Argentina",
"email": "[email protected]",
"customerType": "gold",
"address": "Urquiza 20",
"country": "ar",
"state": "bsas",
"city": "tig",
"postalCode": "7669",
"phone": "2222-4444"
}
,{otro item.......}
,{otro item.......}
,{otro item.......}
,{otro item.......}
,{otro item.......}
,{otro item.......}
]
}
Los campos en negrita son obligatorios.
| Campo | Descripción |
|---|---|
| params | cardType: Tipo de 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"
}]
}
Transferencia de saldos.
Una transferencia de saldos puede ser total, cuando se transfiere todo el monto, o parcial, si sólo se realiza el intercambio de una parte del valor. En el caso de una transferencia total, hay que considerar que da de baja la primer tarjeta, de la cual se obtiene el monto.
Para poder realizar una transferencia de saldos, tanto la tarjeta de origen (la que da saldo) como la de destino (la que recibe saldo) deben ser del mismo tipo.
En la seq=1 enviada por el POS se informara la tarjeta origen, es decir, a quien se le descontaran los puntos, dinero, millas, etc.
En la seq=2 enviada por el POS se informara la tarjeta destino, es decir, la que recibirá los puntos, dinero, millas, etc.
(Ver también Manual de Usuario, "Conceptos de Tarjetas de Fidelidad" para más detalle sobe los distintos tipos de transferencia posible,)
Transferencia parcial
Teniendo ya una tarjeta de código 2345000000000 con monto de 100 y 2345000000001 con monto de 25, se le transfiere, a la segunda tarjeta, 50 de monto. El resultado es que la tarjeta 2345000000000 quedará con 50 de monto, y la segunda 2345000000001 con 75. El tipo de tarjeta, invierno, especifica que la transferencia es parcial.
Al operar con postman, como el mensaje correspondiente será en formato xml, la cabecera content type tendrá el valor application/xml en lugar de application/json.
Tener en cuenta que la url cambia para hacer esta operación, ya que se interactúa contra el motor. El valor que aparece a la derecha de evaluate, en la dirección, es autocompletado por postman. El cuerpo del mensaje (body) tendrá que estar vacío. Los mensajes se enviarán como un parámetro en la dirección. Este parámetro es request. Separar el valor con dos puntos. Presionar, para facilitar el ingreso de datos, en bulk edit (a la derecha de la solicitud) que luego cambia a key-value edit. El valor del parámetro request es el xml a enviar al motor, el cual no deberá tener ningún espacio entre etiquetas.
En la respuesta aparece como quedarían estas tarjetas de confirmarse la operación. Se confirma la operación con el mismo mensaje, pero con el atributo status en "commit" en lugar de "loyaltyTransfer" o "rollback" para cancelar.
Al confirmar la operación....
se verá en la consola reflejado el cambio.
