PROMO 7.8 - Manual de Integración - Servicios

Acerca del manual

Propósito y alcance

El presente manual tiene como finalidad la capacitación al usuario que desee integrar su aplicación de ventas con los servicios que expone Promo.
Se provee una descripción detallada de los mensajes que deben ser enviados al mismo y de cómo interpretar los mensajes de respuesta que dará ante un requerimiento.

Documentación de PROMO

PROMO provee la siguiente documentación:

Manual de usuario:

Este documento tiene la finalidad de capacitar al usuario que desee utilizar la consola de Administración de Promociones de PROMO.

Manual de instalación:

Este documento describe los procedimientos para instalar los componentes de Motor y Consola, la creación e inicialización de la Base de Datos y los requerimientos necesarios para el correcto funcionamiento de dichos componentes.

Manual de integración - Motor:

Este documento describe detalladamente los mensajes que deben ser enviados al Motor de Promociones y la forma de interpretar los mensajes de respuesta que el mismo dará ante un requerimiento.

Manual de integración - Servicios:

Este documento describe detalladamente los servicios que expone la consola de Promo y la forma de enviar y recibir información con ella.

Antes de continuar con la lectura del presente manual, se recomienda leer los capítulos 2 y 3 del Manual de usuario.

Herramientas utilizadas

En el desarrollo de este manual se utilizarán para los ejemplos básicamente tres herramientas que son de dominio público:

CURL: (https://curl.haxx.se/) "command line tool and library for transferring data with URLs": Es una herramienta por línea de comandos para enviar/recibir mensajes http.
POSTMAN: (https://www.postman.com) "The Collaboration Platform for API Development": Herramienta Grafica para la creación, envío y recepción de mensajes.
SOAPUI: (https://www.soapui.org/) "Accelerating API Quality Through Testing": Otra herramienta Gráfica para la definición, envío y recepción de mensajes.

Seguridad: Autenticación de Sistemas Externos con los Servicios

Antes de consumir un servicio provisto por Promo, deberá realizarse un Proceso de autenticación OAuth2. El mismo consiste en obtener un TOKEN que luego debe ser enviado en los subsiguientes mensajes.

Entonces como primer paso a comenzar la comunicación con los servicios de Promo, el sistema externo debe realizar el proceso descripto aquí.

Primero deberá de solicitarse el Token de acceso, que utilizando CURL el comando sería:

-- curl –v –X POST –u my-client: -d "grant_type=password" –d "username=sender" –d "password=mate" –d "scope=read" http://localhost:8080/promo/oauth/token

Donde "http://localhost:8080/promo" debe ser cambiado por la URL donde se encuentra la consola de Promo.

La respuesta ejemplo se puede ver en la siguiente ventana:

Napse > PROMO 7.8 - Manual de Integración - Servicios > worddav073c7c8c8a7060bf91ca4bd3d02f36ea.png

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

Napse > PROMO 7.8 - Manual de Integración - Servicios > image-2023-10-2_9-7-2.png

Napse > PROMO 7.8 - Manual de Integración - Servicios > image-2023-10-2_9-7-38.png

Napse > PROMO 7.8 - Manual de Integración - Servicios > image-2023-10-2_9-8-14.png

Napse > PROMO 7.8 - Manual de Integración - Servicios > image-2023-10-2_9-8-56.png

Luego presionar el botón "Get New Access Token"

Por último presionar el botón "Use Token"

Una vez obtenido el token, se puede enviar una solicitud, por ejemplo realizamos un GET:

Napse > PROMO 7.8 - Manual de Integración - Servicios > image-2023-10-2_9-11-23.png

Al presionar el botón "Send", se obtiene el siguiente resultado:

-- {
"_id": "64ac2a4ea62e431d30370c98",
"addressCountry": "arg",
"lastName": "Pérez",
"identifier": "28710944",
"code": "11",
"identificationExpiration": "2050-01-01T03:00:00Z",
"address": "diagonal 12 2233",
"gender": "m",
"autoCard": "cardType2",
"identificationType": "dni",
"addressState": "bsas",
"isActive": true,
"birthDate": "2012-04-23T03:00:00Z",
"addressPostalCode": "22223",
"customerType": "EMPLEADO",
"phone": "1111111123",
"nacionality": "arg",
"name": "RICARDO",
"email": "ricado33@gmail.com",
"addressCity": "tig",
"companyId": "2",
"creationDate": "2023-07-10T15:57:02Z",
"cards": [],
"coupons": []

}

Consola: Servicios REST de Consulta

Aquí se presentan los servicios provistos para consulta de información contenida en PROMO.

Antes de consumir el servicio debe obtenerse el TOKEN de identificación como se explica en "Seguridad: Autenticación de Sistemas Externos con los Servicios".

Se agregó la nueva variable rabbitMq.date.UTC para que todos los mensajes que se devuelven a alguna de las consultas via Rest disponible en Promo, se informen con el formato del locale configurado en el servidor, que por default es GMT.

Servicios afectados:

Clientes: http://[SERVER]:[PORT]/promo/api/rest/customer
Estado de Limites del cliente: http://[SERVER]:[PORT]/promo/api/rest/limit/limitStatus
Cupones: http://[SERVER]:[PORT]/promo/api/rest/coupon
Elementos de Fidelidad: http://[SERVER]:[PORT]/promo/api/rest/card
Mapas, promociones y promociones distribuidas: http://[SERVER]:[PORT]/promo/api/rest/promotions
Próximo numero de elemento de fidelidad: http://[SERVER]:[PORT]/promo/api/rest/nextCardNumber
Reporte de promociones: http://[SERVER]:[PORT]/promo/api/rest/reports/transaction/promotion

Tener en cuenta la configuración descripta en Información de Configuración

Servicio De Consulta de Datos de Clientes

PROMO expone un servicio que permite consultar elementos de fidelidad y transacciones (ventas y devoluciones) a la BBDD utilizando el ID de cliente.

Junto con los campos del cliente, también se devuelve un listado de Elementos de Fidelidad y Cupones, y sus últimas N transacciones.

Si no tiene elementos de Fidelidad, se devolverán los Elementos o Cupones vacíos; igualmente en el caso que no tengan transacciones, no traerá datos sobre las mismas.

El código de la consulta debe ser exacto y solo se devolverá un resultado, si es que el cliente existe.

El formato en que se responde es en JSON.

Este método accesible desde api/rest/customer es el encargado de devolver en formato JSON el customer o cliente solicitado por medio de la acción GET.

Tiene tres parámetros de ingreso:

Nombre	Valor
companyId	El código de la compañía. String. Requerido.
code	El código del cliente. String. No requerido.
identificationType	El código del tipo de identificación del cliente (por ej, "dni"). String. No requerido.
identifier	El nro. de identificación de cliente (por ej. nro de dni). String. No requerido.
lastSales	Con el valor configurado por el cliente, se habilita en la respuesta un listado con las últimas transacciones del cliente. No requerido
offset	Número entero. Indica desde qué posición comenzar a retornar clientes cuando no se consulta un cliente específico. Por defecto es `0`. Si se omite, comienza desde el primer cliente. No requerido.
max	Número entero. Define la cantidad máxima de clientes a retornar por consulta cuando no se consulta un cliente específico. El valor máximo permitido es `1000`. Si se omite, se toma por defecto `1000`. No requerido.

Para buscar el cliente se debe enviar, o bien el parámetro "code", o bien el par de parámetros identifier e identificationType.

En caso de no enviar ninguno, retorna [] con un mensaje de error en el log. Si envían code y el nuevo par de parámetros mencionados, buscará por code ya que tiene prioridad de búsqueda por el campo anterior en este caso particular.

El código debe ser exacto y solo se devolverá un resultado, si es que el cliente existe.

El campo “lastSales” es numérico, e indica la cantidad de transacciones que tiene un cliente. El usuario deberá ingresar la cantidad de transacciones que desea visualizar.

Si pasan x números se retornan esas x últimas transacciones. Si pasan 0, o no lo pasan (vacío), no se retorna esa info.

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 deberá enviar, por ej. http://URLPROMO:PUERTO/promo/api/rest/customer?code=0102909421&companyId=napse&lastSalesInfo=N

-- http://{server}:{port}/promo/api/rest/customer?code=12345&companyId={companyId}

Obteniéndose la siguiente respuesta:

-- {

"_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.-

El tag "Segments" mostrara la informacion de semgentos externos si estuviera el cliente asociado a tales segmentos.

Segmentos Internos en el Servicio de Consulta de Clientes

Se ha actualizado el Servicio de Consulta de Datos de Clientes para incluir la posibilidad de obtener los segmentos internos de un cliente cuando se consulta de forma puntual.

Se agregó el parámetro opcional includeSegments en el request del servicio.
Este parámetro solo se aplica cuando se consulta un cliente específico mediante su código.
Valores posibles de includeSegments:
- true: Si el cliente tiene segmentos internos, estos serán devueltos en la respuesta dentro del nuevo bloque "promoSegments".
- false: No se incluirán segmentos internos en la respuesta. (Valor por defecto).
La respuesta incluirá el listado de segmentos internos en el siguiente formato:

http://localhost:8081/promo/api/rest/customer?code=15248785&companyId=Napse&includeSegments=true

"promoSegments": [
    {
        "code": "c12A",
        "name": "segint12A"
    },
    {
        "code": "c13B",
        "name": "segint13B"
    }
]

Este campo solo refiere a los segmentos internos de Promo y no afecta la información de segmentos externos.

La respuesta por cada elemento incluido en el atributo lastSales , tiene la siguiente estructura (estos datos se sumaran, en caso de corresponder, a los datos que ya se informan de tarjetas y cupones asociados al cliente):

Atributo	Descripción
transactionId	Código de la transacción
transactionType	Tipo de la transacción
storeCode	Código de la tienda
terminalCode	Código de terminal
customerId	Código de cliente
customerType	El código del tipo de cliente
mapVersion	El nro. del mapa evaluado al realizar esta transacción
offline	Con valor true determina si fue originada offline, y false determina que fue originada online.
date	Fecha de la transacción. Formato equivalente al de la fecha de creación del cliente (campo creationDate). Por ej. 2021-06-24T20:34:39Z
transactionStatus	El estado en que se encuentra la transacción actualmente.
itemsTotalQuantity	Cantidad de unidades de productos vendidos al cliente. En el caso de venta por magnitud, al no enviar qty, suma un 1; por ej. vendiendo los siguientes ítems, daría como resultado "itemsTotalQuantity": 2.0 : <item-add code="1234" magnitude="1.5" seq="1" <otros atributos>/> <item-add code="2222" magnitude="5.5" seq="2" <otros atributos>/>
summaryValues	Representan el resumen de valores de la transacción. Objeto que contiene cuatro atributos. Detalle a continuación.
summaryValues.subtotal	Indica el subtotal de la transacción sin descuentos ni recargos
summaryValues.discount	Indica el monto de los descuentos aplicados en la transacción
summaryValues.surcharge	Indica el monto de los recargos aplicados en la transacción
summaryValues.total	Indica el total de la transacción con descuentos y recargos aplicados
payments	Representan los pagos presentados en la transacción. Es un listado de objetos que contienen tres atributos. Detalle a continuación.
payments.type	El tipo del medio de pago
payments.id	El id del medio de pago
payments.amount	El monto del pago realizado con ese medio.
loyaltyCards	Representan un detalle de los elementos de fidelidad presentadas en la transacción. Es un listado de objetos que contienen cinco atributos. Detalle a continuación.
loyaltyCards.id	El código de elemento del elemento de fidelidad
loyaltyCards.obtainedPoints	Puntos obtenidos durante la transacción
loyaltyCards.benefitedByPromotion	true en caso de haber obtenido puntos.
loyaltyCards.redeemedPoints	Puntos redimidos durante la transacción
loyaltyCards.redeemedByPromotion	true en caso de haberse redimido puntos.
coupons	Representan un detalle de la cantidad de cupones emitidos y consumidos en la transacción. Es un objeto que contiene dos atributos. Detalle a continuación.
coupons.obtained	Cantidad de cupones obtenidos.
coupons.redeemed	Cantidad de cupones redimidos.

-- {

"_id": "60824eeecff31c4138ebf73d",
"code": "0102909421",
"identifier": "0102909421",
"email": "-",
"name": "john promo",
"lastName": "-",
"identificationType": "c",
"customerType": "c",
"creationDate": "2021-04-23T04:37:02Z",
"isActive": true,
"companyId": "napse",
"cards": [],
"coupons": [],
"lastSales": [
{
"transactionId": "napse_1_1_20210624173439",
"transactionType": "SALE",
"storeCode": "1",
"terminalCode": "1",
"customerId": "0102909421",
"customerType": "c",
"mapVersion": 5,
"offline": false,
"date": "2021-06-24T20:34:39Z",
"transactionStatus": "COMMIT",
"itemsTotalQuantity": 33.0,
"summaryValues": {
"subtotal": 2217.0,
"discount": 353.0,
"surcharge": 0.0,
"total": 1864.0
},
"payments": [
{
"type": "1",
"id": "1",
"amount": 100.25
},
{
"type": "2",
"id": "2",
"amount": 200.5
}
],
"loyaltyCards": [
{
"id": "1111000000010",
"obtainedPoints": 100.0,
"benefitedByPromotion": true,
"redeemedPoints": 3.0,
"redeemedByPromotion": true
}
],
"coupons": {
"obtained": 10,
"redeemed": 2
}
}
]
}

Tener en cuenta que este servicio rest, en la sección lastSales, se alimenta de las colecciones transaction, transactionFlatten, y viewCustomer. Para que esté la info disponible es necesario que se hayan procesado los jobs: sts.console.job.LoyaltyJob (Finalización de transacciones) y sts.console.job.TransactionFlattenJob (Aplanado de Transacciones).

En caso de que el cliente no exista en la base la respuesta se devolverá vacía.

Servicio De 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:

-- {

"customerId": "85001",

"companyId": "napse",

"limitsDetail": [

{

"_id": "603a437c1082e83690817050",

"promotionId": "603a319c1082e83690816f95",

"benefitId": "603a31b81082e83690816f9c",

"promotionCode": "3",

"promotionName": "limite cliente",

"limitId": "603a31b61082e83690816f9b",

"scope": "CUSTOMER",

"period": "UNDEFINED",

"maxValue": 5.0,

"customerId": "85001",

"storeId": "-",

"numberDays": 0,

"nextReset": "2021-02-27T03:00:00+0000",

"lastReset": "2021-02-27T03:00:00+0000",

"companyId": "napse",

"limitTypeCode": "benefitApplicationCount",

"description": null,

"lastUpdate": "2021-02-27T13:05:00+0000",

"active": true,

"currentValue": 1.0

}

]

}

En caso de que el cliente no exista en la base la respuesta informara "El cliente especificado no existe".

Servicio De Consulta de Cupón

PROMO expone un servicio que permite consultar cupones a la BBDD utilizando solo el número de cupón y como respuesta se obtienen los movimientos asociados a dicho cupón.

También se pueden realizar consultas sobre el historial de movimientos de cupones.

Los parámetros de entrada de la consulta son:

Propiedad

Tipo de dato

Descripción

companyId Alfanumérico Código de la compañía. Requerido

barcode Alfanumérico Código del elemento de fidelidad la cual se quiere consultar. Opcional

limit

Numérico

Cantidad de registros de movimientos a retornar (default: 5) con un máximo de 100.000 por consulta. Opcional

dateFrom

Numérico

Fecha de Inicio en formato YYYYMMDD. Si no se especifica barcode. Opcional

dateTo

Numérico

Fecha de Final en formato YYYYMMDD. Si no se especifica barcode. Opcional

couponAction

Alfanumérico

Código de Operación que se quiere consultar. Si no se especifica barcode. Por defecto son todas las operaciones.

Los valores disponibles son: CREATE, REDEEM, VOID. Opcional

timeFrom Numérico Hora de Inicio con formato HHmm. Opcional

timeTo Numérico Hora de Fin con formato HHmm. Opcional

offset Numérico Permite navegar dentro del rango. Se usa en conjunto con el parámetro limit. Por ej: Se quiere navegar los primeros 10 registros, configurar offset=1 y limit=10. Se quiere ver los 10 siguientes, configurar offset=11 y limit 10. Cuando ya no hay más registros va a dar vacío. Opcional

isTypes

Booleano

Si se ingresa "true" se podrá consultar los tipos de cupones existentes. Si está en "false" devolverá los cupones (se trata de una consulta de cupones y no de tipos). Opcional

El atributo isTypes controla el tipo de resultado que se desea obtener en la consulta de cupones. Si isTypes se define como true, el servicio devolverá los tipos de cupones existentes.

En cambio, cuando isTypes se define como false, el servicio retornará los cupones correspondientes. En este caso, el uso de isTypes con valor false debe combinarse con otros atributos específicos para que la consulta devuelva resultados correctos y sin errores.

isTypes == false y barcode contiene un valor válido:

-- https://demo7.napse.global:8773/promo/api/rest/coupon?companyId=NapseDemo&isTypes=false&barcode=1120100246470

-- {
"_id": "66ea08a70cd5197356877248",
"companyId": "NapseDemo",
"transactionId": "NapseDemo_10_24_20240917175213",
"couponType": "10",
"issuedDate": "2024-09-17T22:54:31Z",
"customerId": "55458912",
"couponStatus": "ACTIVE",
"validFrom": "2024-09-17T00:00:00Z",
"validTo": "2124-08-24T00:00:00Z",
"usedTimes": 0,
"consumed": false,
"couponFormat": "ELECTRONIC",
"emitPromotion": "Promo otorga cupón electronico Boxito",
"storeCode": "10",
"terminalCode": "24",
"maxUsageTimes": 1,
"barcode": "1120100246470",
"amount": 0.0,
"generatedHTML": "<img alt=\"\" src=\"https://www.folletos.com/Boxito/mboxito.png\" style=\"height:100px; width:300px\">\r\n\r\nana gracias por tu última compra!\r\n\r\nTe queremos obsequiar este cupón del 20% de descuento en tu próxima.\r\n\r\n \r\n\r\n<img alt=\"\" src=\"https://img.offers-cdn.net/assets/uploads/flyers/1473532/zoomLarge/boxito-1-1.jpg\" style=\"height:300px; width:500px\">\r\n\r\n@barcode\r\n\r\nAplican Términos y Condiciones",
"couponHistory": [
{
"date": "2024-09-17T22:55:00Z",
"couponAction": "CREATE",
"storeCode": "10"
}
]
}

isTypes == false y las fechas dateFrom y dateTo están definidas correctamente (formato de 8 dígitos: YYYYMMDD):

-- https://demo7.napse.global:8773/promo/api/rest/coupon?companyId=NapseDemo&isTypes=false&dateFrom=20240701&dateTo=20241008

-- {

"couponHistory": [

{

"transactionId": "NapseDemo_10_14_20240813172439",

"date": "2024-08-13T20:27:30Z",

"coupon": "1010100147641",

"couponAction": "REDEEM",

"storeCode": "10",

"terminalCode": "14",

"customerCode": "24314537"

},

{

"transactionId": "NapseDemo_10_90_20240711150509",

"date": "2024-07-11T20:06:30Z",

"coupon": "1050100906473",

"couponAction": "CREATE",

"storeCode": "10",

"terminalCode": "90",

"customerCode": "30135949"

},

{

"transactionId": "NapseDemo_10_90_20240711162820",

"date": "2024-07-11T21:29:30Z",

"coupon": "1050100902949",

"couponAction": "CREATE",

"storeCode": "10",

"terminalCode": "90",

"customerCode": "30135949"

},

{

"transactionId": "NapseDemo_10_90_20240712121102",

"date": "2024-07-12T17:16:30Z",

"coupon": "1050100909412",

"couponAction": "CREATE",

"storeCode": "10",

"terminalCode": "90",

"customerCode": "30135949"

},

{

"transactionId": "NapseDemo_10_90_20240712124104",

"date": "2024-07-12T17:47:30Z",

"coupon": "1050100905889",

"couponAction": "CREATE",

"storeCode": "10",

"terminalCode": "90",

"customerCode": "30135949"

}

]

}

isTypes == false y couponType contiene un valor válido:

-- https://demo7.napse.global:8443/promo/api/rest/coupon?companyId=NapseDemo&isTypes=false&couponType=501

-- {
"coupons": [
{
"_id": "66e1e58d0cd5197356876683",
"companyId": "NapseDemo",
"transactionId": "NapseDemo_10_90_20240911134610",
"couponType": "501",
"issuedDate": "2024-09-11T18:46:37Z",
"customerId": "12345",
"couponStatus": "ACTIVE",
"validFrom": "2024-09-11T00:00:00Z",
"validTo": "2024-11-19T23:59:59Z",
"usedTimes": 0,
"consumed": false,
"couponFormat": "ELECTRONIC",
"emitPromotion": "66ac0d660cd519da360ea187",
"storeCode": "10",
"terminalCode": "90",
"maxUsageTimes": 1,
"barcode": "1080100901765",
"amount": 0.0,
"generatedHTML": "<img alt=\"\" src=\"https://www.sirena.do/assets/logo/logo.svg?v=20221013\" style=\"height:89px; width:300px\">\r\n\r\nDescuento del 10% de descuento sobes Doh Chow en tu proxima compra al presentar el cupón (minimo 3 piezas)\r\n\r\n<img alt=\"\" src=\"https://i5.walmartimages.com.mx/gr/images/product-images/img_large/00750107221026L.jpg?odnHeight=612&odnWidth=612&odnBg=FFFFFF\" style=\"height:250px; width:250px\">\r\n\r\nVigencia del 11/09/2024 al 19/11/2024\r\n\r\nTERMINOS Y CONDICIONES\r\n\r\nValido gasta agotar existecias. Aplica un cupon por cliente. Válido en las tiendas de CDMX\r\n\r\n@barcode\r\n\r\n \r\n\r\n \r\n\r\n \r\n\r\n \r\n\r\n \r\n\r\n \r\n\r\n \r\n\r\n \r\n\r\n "
},
{
"_id": "66e1e5650cd519735687667d",
"companyId": "NapseDemo",
"transactionId": "NapseDemo_10_90_20240911134526",
"couponType": "501",
"issuedDate": "2024-09-11T18:45:57Z",
"customerId": "12345",
"couponStatus": "CONSUMED",
"validFrom": "2024-09-11T00:00:00Z",
"validTo": "2024-11-19T23:59:59Z",
"usedTimes": 1,
"consumed": true,
"couponFormat": "ELECTRONIC",
"emitPromotion": "66ac0d660cd519da360ea187",
"storeCode": "10",
"terminalCode": "90",
"maxUsageTimes": 1,
"barcode": "1080100905299",
"amount": 0.0,
"generatedHTML": "<img alt=\"\" src=\"https://www.sirena.do/assets/logo/logo.svg?v=20221013\" style=\"height:89px; width:300px\">\r\n\r\nDescuento del 10% de descuento sobes Doh Chow en tu proxima compra al presentar el cupón (minimo 3 piezas)\r\n\r\n<img alt=\"\" src=\"https://i5.walmartimages.com.mx/gr/images/product-images/img_large/00750107221026L.jpg?odnHeight=612&odnWidth=612&odnBg=FFFFFF\" style=\"height:250px; width:250px\">\r\n\r\nVigencia del 11/09/2024 al 19/11/2024\r\n\r\nTERMINOS Y CONDICIONES\r\n\r\nValido gasta agotar existecias. Aplica un cupon por cliente. Válido en las tiendas de CDMX\r\n\r\n@barcode\r\n\r\n \r\n\r\n \r\n\r\n \r\n\r\n \r\n\r\n \r\n\r\n \r\n\r\n \r\n\r\n \r\n\r\n ",
"lastRedeemedDate": "2024-09-11T19:17:30Z"
},
{
"_id": "66e1e5b50cd5197356876689",
"companyId": "NapseDemo",
"transactionId": "NapseDemo_10_90_20240911134649",
"couponType": "501",
"issuedDate": "2024-09-11T18:47:17Z",
"customerId": "12345",
"couponStatus": "CONSUMED",
"validFrom": "2024-09-11T00:00:00Z",
"validTo": "2024-11-19T23:59:59Z",
"usedTimes": 1,
"consumed": true,
"couponFormat": "ELECTRONIC",
"emitPromotion": "66ac0d660cd519da360ea187",
"storeCode": "10",
"terminalCode": "90",
"maxUsageTimes": 1,
"barcode": "1080100908238",
"amount": 0.0,
"generatedHTML": "<img alt=\"\" src=\"https://www.sirena.do/assets/logo/logo.svg?v=20221013\" style=\"height:89px; width:300px\">\r\n\r\nDescuento del 10% de descuento sobes Doh Chow en tu proxima compra al presentar el cupón (minimo 3 piezas)\r\n\r\n<img alt=\"\" src=\"https://i5.walmartimages.com.mx/gr/images/product-images/img_large/00750107221026L.jpg?odnHeight=612&odnWidth=612&odnBg=FFFFFF\" style=\"height:250px; width:250px\">\r\n\r\nVigencia del 11/09/2024 al 19/11/2024\r\n\r\nTERMINOS Y CONDICIONES\r\n\r\nValido gasta agotar existecias. Aplica un cupon por cliente. Válido en las tiendas de CDMX\r\n\r\n@barcode\r\n\r\n \r\n\r\n \r\n\r\n \r\n\r\n \r\n\r\n \r\n\r\n \r\n\r\n \r\n\r\n \r\n\r\n ",
"lastRedeemedDate": "2024-09-11T18:49:30Z"
}
]
}

La correcta combinación de isTypes con estos atributos garantiza que el servicio devuelva los resultados deseados y evita errores en la consulta.

typeCode Alfanumérico Si se deja este campo vacío, traerá todos los tipos de cupones. Sino, se podrá consultar por un tipo de cupón específico. Para utilizar este campo, "isTypes" debe estar en "true". Opcional

typeActive Booleano Se podrá consultar por tipos de cupones Activos (true) o Inactivos (false) . Si se deja vacío (o no se envía) trae ambos. Opcional.

cuponType Alfanumérico Tipo de cupón. Opcional

Es obligatorio especificar al menos uno de los siguientes campos para completar la acción:

Código: debe ingresar un código válido.
Rango de fechas dateFrom - dateTo

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.

Modificación del Servicio de Consulta de Cupones:

En la versión 7.4 de Promo, se ha actualizado el servicio de consulta de cupones para ofrecer mayor flexibilidad en las consultas de tipos de cupones. Ahora es posible realizar las siguientes consultas:

Todos los tipos de cupones existentes.
Un tipo de cupón específico.
Tipos de cupones activos.
Tipos de cupones inactivos.
Tipos de cupones activos e inactivos.
Tipo de cupon especifico.

Para lograr estas consultas, se han incorporado tres nuevas propiedades:

isTypes (Booleano): Este parámetro indica si la consulta debe devolver tipos de cupones (true) o cupones propiamente dichos (false). Su uso es opcional.
typeCode (Alfanumérico): Este campo permite filtrar por un tipo de cupón específico. Si no se ingresa un valor, se devolverán todos los tipos de cupones. Este parámetro es opcional y requiere que isTypes esté en true.
typeActive (Booleano): Permite filtrar los cupones por su estado. Se puede consultar por cupones activos (true), inactivos (false), o ambos (si no se envía el parámetro). Este parámetro es opcional.
cuponType (Alfanumérico): Este parámetro permite consultar por un tipo de cupón específico. Si no se especifica el parámetro barcode, se devolverán todos los cupones que pertenezcan a ese tipo de cupón. Este parámetro es opcional.

Comportamiento adicional:

Si se filtra por fechas con los parámetros dateFrom (Desde) y dateTo (Hasta), y no se especifica un tipo de cupón en el campo typeCode, el servicio devolverá todos los tipos de cupones existentes (activos e inactivos) comprendidos en ese rango de fechas.
Al realizar una consulta con el parámetro cuponType, el resultado devolverá todos los cupones que tengan el tipo de cupón consultado, sin incluir el historial de cupones (couponHistory). Los demás campos de los cupones serán los mismos que el servicio devolvía antes de esta actualización.

La respuesta del servicio dependerá del tipo de cupón.

Como se ve en el siguiente ejemplo, si utiliza el tipo de cupón Pre Impreso, como el mismo no utiliza amount ese campo traerá null en lugar de 0.

Napse > PROMO 7.8 - Manual de Integración - Servicios > image-2024-12-30_15-6-7.png

-- {
    "_id": "673e3eafc6e56a4a987d1273",
    "barcode": "1110BCmp10000",
    "companyId": "napse",
    "consumed": false,
    "couponFormat": "PRE_PRINTED",
    "couponStatus": "DISABLED",
    "couponType": "tcpreimp1",
    "issuedDate": "2024-11-20T19:55:27Z",
    "maxUsageTimes": 1,
    "storeCode": "BC",
    "terminalCode": "tcpreimp1",
    "transactionId": "BC_202411201655174",
    "usedTimes": 0,
    "validFrom": "2024-11-20T03:00:00Z",
    "validTo": "2030-12-21T02:59:59Z",
    "version": 0,
    "amount": null,
    "customerId": null,
    "email": null,
    "emitPromotion": null,
    "generatedHTML": null,
    "lastRedeemedDate": null,
    "redeemPromotion": null,
    "couponHistory": [
        {
            "couponAction": "CREATE",
            "date": "2024-11-20T19:55:27Z",
            "storeCode": "BC"
        }
    ]

EJEMPLO 1: se solicitan los datos del cupón 1040BC005233

http://localhost:8073/promo/api/rest/coupon?companyId=2&barcode=1040BC005233

Napse > PROMO 7.8 - Manual de Integración - Servicios > image-2023-7-11_15-28-29.png

La misma pero utilizando CURL:

-- curl
-- X GET -H "Authorization: Bearer c4349afa-2c2e-46a8-b768-f89a4cb334bf'" 
-- H "Content-type: application/json" -H "Accept: application/json" http://localhost:8073/promo/api/rest/coupon?companyId=2&barcode=1040BC005233

Obteniéndose la siguiente respuesta:

-- {

    "_id": "6435a371a62e43505468c39d",

    "barcode": "1040BC005233",

    "companyId": "napse",

    "consumed": false,

    "couponFormat": "PRE_PRINTED",

    "couponStatus": "ACTIVE",

    "couponType": "5",

    "issuedDate": "2023-04-11T18:14:09Z",

    "maxUsageTimes": 1,

    "storeCode": "BC",

    "terminalCode": "5",

    "transactionId": "BC_202304111514814",

    "usedTimes": 0,

    "validFrom": "2023-04-11T03:00:00Z",

    "validTo": "2123-03-18T03:00:00Z",

    "version": 1,

    "amount": null,

    "customerId": null,

    "email": null,

    "emitPromotion": null,

    "generatedHTML": null,

    "lastRedeemedDate": null,

    "redeemPromotion": null,

    "couponHistory": [

        {

            "date": "2023-04-11T19:00:00Z",

            "couponAction": "ACTIVE",

            "storeCode": "BC"

        },

        {

            "couponAction": "CREATE",

            "date": "2023-04-11T18:14:09Z",

            "storeCode": "BC"

        }

    ]

}

EJEMPLO 2: Se solicitan todos los cupones creados en el periodo 01/03/2024-25/03/2024, para la empresa napse con un limite de 100.000 registros.

-- http://localhost:8073/promo/api/rest/coupon?companyId=napse&dateFrom=20240301&dateTo=20240325&limit=100000&couponAction=create

Napse > PROMO 7.8 - Manual de Integración - Servicios > image-2024-3-25_15-51-41.png

-- curl -X GET -H "Authorization: Bearer ea41e16c-6070-4a05-82c1-6d54ae70a225" -H "Content-type: application/json" -H "Accept: application/json"http://localhost:8073/promo/api/rest/coupon? dateFrom=20240301&dateTo=20240325&companyId=napse&limit=100000&couponAction=create

Obteniéndose la siguiente respuesta:

-- {
    "couponHistory": [
        {
            "transactionId": "napse_1_1_20240419173500",
            "date": "2024-03-19T20:29:30Z",
            "coupon": "1170010016472",
            "couponAction": "CREATE",
            "storeCode": "1",
            "terminalCode": "1",
            "customerCode": "-"
        },
        {
            "transactionId": "napse_1_1_20240419173500",
            "date": "2024-03-19T20:29:30Z",
            "coupon": "1190010016470",
            "couponAction": "CREATE",
            "storeCode": "1",
            "terminalCode": "1",
            "customerCode": "-"
        },
        {
            "transactionId": "napse_1_1_20240419173500",
            "date": "2024-03-19T20:29:30Z",
            "coupon": "1180010016471",
            "couponAction": "CREATE",
            "storeCode": "1",
            "terminalCode": "1",
            "customerCode": "-"
        }
    ]
}

EJEMPLO 3: Con la siguiente consulta se obtienen todos los movimientos de todos los cupones dentro del rango de fechas: desde 01 de enero de 2024, hasta el 19 de marzo de 2024, que ocurrieron en la compañía Napse.

-- http://localhost:8073/promo/api/rest/coupon?dateFrom=20240101&dateTo=20240319&companyId=napse

Napse > PROMO 7.8 - Manual de Integración - Servicios > image-2024-3-22_17-59-44.png

Obteniéndose la siguiente respuesta:

-- {
    "couponHistory": [
        {
            "transactionId": "-",
            "date": "2024-01-02T14:00:00Z",
            "coupon": "1030BCeso0000",
            "couponAction": "EXPIRATE",
            "storeCode": "BC",
            "terminalCode": "pre-impreso",
            "customerCode": "null"
        },
        {
            "transactionId": "-",
            "date": "2024-01-02T14:00:00Z",
            "coupon": "1030BCeso6472",
            "couponAction": "EXPIRATE",
            "storeCode": "BC",
            "terminalCode": "pre-impreso",
            "customerCode": "null"
        },
        {
            "transactionId": "-",
            "date": "2024-01-02T14:00:00Z",
            "coupon": "1030BCeso2948",
            "couponAction": "EXPIRATE",
            "storeCode": "BC",
            "terminalCode": "pre-impreso",
            "customerCode": "null"
        },
        {
            "transactionId": "-",
            "date": "2024-01-02T14:00:00Z",
            "coupon": "1030BCeso9411",
            "couponAction": "EXPIRATE",
            "storeCode": "BC",
            "terminalCode": "pre-impreso",
            "customerCode": "null"
        },
        {
            "transactionId": "-",
            "date": "2024-01-02T14:00:00Z",
            "coupon": "1030BCeso5888",
            "couponAction": "EXPIRATE",
            "storeCode": "BC",
            "terminalCode": "pre-impreso",
            "customerCode": "null"
        }
    ]
}

Servicio De Consulta de Estado de Cupón

PROMO expone un servicio que permite consultar el estado de cupones a la BBDD utilizando como parámetros el Id de cliente, Id de la compañía, el tipo de acción y el rango de fechas (Fecha_desde y Fecha_hasta) y como respuesta se obtienen los movimientos asociados a dicho cupón.

La Url para acceder al servicio es:

-- http://[server]:[port]/promo/api/rest/couponStatements

os 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

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_7-37-26.png

y como respuesta se obtienen los datos del cupón asociado al cliente y su estado.

Respuesta:

-- [
    {
        "transactionId": "napse_napse_1_20220830120000",
        "action": "Emisión",
        "terminal": "1",
        "couponType": "cimp",
        "customerId": "1",
        "amount": "-",
        "store": "napse",
        "datetime": "30/08/2022 11:08",
        "couponCode": "116pse0018828"
    },
    {
        "transactionId": "napse_napse_1_20220830120000",
        "action": "Emisión",
        "terminal": "1",
        "couponType": "cimp",
        "customerId": "1",
        "amount": "-",
        "store": "napse",
        "datetime": "30/08/2022 11:08",
        "couponCode": "116pse0015292"
    }
]

Servicio De Consulta de Elementos de Fidelidad

PROMO expone un servicio que permite consultar elementos de fidelidad a la BBDD utilizando solo su número de elemento y como respuesta se obtienen los datos del elemento en cuestión y los movimientos asociados a dicho elemento. Los datos que se devuelven son: fecha, id de transacción, tipo de operación, monto, tienda.

Para consumir este servicio se debe realizar una solicitud del tipo GET con los parámetros correspondientes a la siguiente URL:

-- http://servidor:puerto/promo/api/rest/card

Los parámetros de entrada de la consulta son:

Propiedad	Tipo de dato	Descripción
*companyId*	Alfanumérico	Código de la compañía. Requerido
*code*	Alfanumérico	Código del elemento que se quiere consultar. Requerido
*limit*	Numérico	Cantidad de registros de movimientos a retornar (default: 5) con un máximo de 100.000 por consulta. Opcional
*dateFrom*	Numérico	Fecha de Inicio en formato YYYYMMDD. Opcional
*dateTo*	Numérico	Fecha de Final en formato YYYYMMDD. Opcional
*requestTypes*	Booleano	(desde 7.EP2.1) Si se especifica el valor true se retornarán solamente los tipos de elementos definidos. *ver ejemplo mas abajo. Opcional
cardAction	Alfanumérico	Código de Operación que se quiere consultar. Si no se especifica code. Por defecto son todas las operaciones. Los valores disponibles son: CHARGE, RECHARGE, AMOUNT_UPDATE, SALE, EXTENDED_POINTS. Opcional
timeFrom	Numérico	Hora de Inicio en formato HHmm. Opcional
timeTo	Numérico	Hora de final en formato HHmm. Opcional
*offset*	Numérico	Permite navegar dentro del rango. Se usa en conjunto con el parámetro limit. Por ej: Se quiere navegar los primeros 10 registros, configurar offset=1 y limit=10. Se quiere ver los 10 siguientes, configurar offset=11 y limit 10. Cuando ya no hay más registros va a dar vacío. Opcional

Se pueden enviar el dateFrom y dateTo sin cargar los datos de timeFrom y timeTo, estos serán opcionales. Pero solo se utilizarán los parámetros timeFrom y timeTo si tiene cargados los parámetros de dateFrom y dateTo, caso contrario no serán utilizados.

Si se especifica un elemento, se retornarán los datos y movimientos asociados a dicha elemento, pudiéndose opcionalmente especificar un rango de fechas y un limite en la cantidad de movimientos.

Si no se especifica el elemento, se debe especificar un rango de fechas y se retornaran todos los movimientos de los elementos en ese rango, incluyendo en ese caso el numero del elemento que se trata.

Para el caso de información de elementos, el Formato de la Respuesta será (JSON):

Propiedad

Tipo de dato

Descripción

_id*

Alfanumérico

Uso Interno

amount*

Numérico

Saldo Actual del elemento.

code*

Alfanumérico

Número del Elemento

Created*

Alfanumérico

Fecha de Creación en formato ISODATE

customerId

Alfanumérico

Id de cliente asociado al elemento

activation

Numérico

Fecha de activación

isConsumed*

Booleano

Si ha sido consumida o no

status*

Alfanumérico

Estado actual del elemento

storeCode*

Alfanumérico

Código de Tienda de generación (si aplica)

terminalCode*

Alfanumérico

Código de terminal de generación (si aplica)

transactionId*

Alfanumérico

Código de Transacción que la genero (si aplica)

lastPurchaseDate

Numérico

Fecha del ultimo movimiento

type*

Alfanumérico

Tipo de Elemento

typeName

Alfanumérico

Nombre del tipo de elemento

amountPrev

Numérico

monto previo

version*

Numérico

Uso Interno

cardHistory

Colección

Conjunto de registros que corresponden a cada movimiento del elemento, con:

amount: monto del movimiento
card (Solo si no se consulto por una determinada): Numero del elemento
cardAction: Tipo de movimiento
date: fecha del movimiento (ISO DATE)
storeCode: código de elemento
transactionId: Código de transacción.
createdAt: fecha de creación
terminalCode: código de terminal
customerCode: código de cliente (para el caso de asignaciones)
amountPrev: Monto previo
reasonName: Razón del movimiento (Motivo del movimientos desde consola)

Conjunto de registros que corresponden a la promoción que aplica al movimiento del elemento

appliedPromotionDetails

promotionName	Nombre de la promoción
promotionCode	Código de la promoción
conditionDateRangeDescription	Condición de rango horario de la promoción

Estos datos son retornados solo si se consulta por un código de elemento determinado.

Para el caso de Tipos de elemento:

Propiedad	Tipo de dato	Descripción
amountChargeLimit	Numérico	Limite de carga
*cardNumberLength*	Numérico	Longitud del número del elemento
cardTypePrefixRange	Array	definición de rangos de prefijos para ese elemento.
code	Alfanumérico	Código del tipo
customerValidation	Alfanumérico	Si es Nominado, el tipo de validación de customer (NO, API, FILE)
description	Alfanumérico	Descripción del tipo
isActive	Booleano	True si se encuentra activo
isCVVRequired	Booleano	True si requiere cvv
isNominated	Booleano	True si es nominado
isRechargeable	Booleano	True is es recargable
name	Alfanumérico	Nombre del tipo

EJEMPLO 1: se solicitan los datos del elemento 1000000000001 para la compañía napse y con movimientos del 01/04/2020 al 31/04/2020 sin especificar limites con lo cual serán los 5 últimos movimientos.

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2020-5-1_21-45-16.png

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.

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2020-5-1_22-3-13.png

Via CURL:

-- curl
-- X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8
-- H "Content-type: application/json" -H "Accept: application/json" "http://localhost:8080/promo/api/rest/card?companyId=napse&dateFrom=20200429&dateTo=20200429&limit=100000"

El cual recibirá una respuesta del tipo:

 -- {
    "cardHistory": [
        {
            "amount": "10.0",
            "card": "1000000000000",
            "cardAction": "AMOUNT_UPDATE",
            "date": "2020-04-29T12:42:18Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "300.0",
            "card": "1000000000000",
            "cardAction": "CHARGE",
            "date": "2020-04-29T12:02:06Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "0",
            "card": "1000000000000",
            "cardAction": "ACTIVATION",
            "date": "2020-04-29T12:02:06Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "20.0",
            "card": "1000000000001",
            "cardAction": "AMOUNT_UPDATE",
            "date": "2020-04-29T12:42:26Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "300.0",
            "card": "1000000000001",
            "cardAction": "CHARGE",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "0",
            "card": "1000000000001",
            "cardAction": "ACTIVATION",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "300.0",
            "card": "1000000000002",
            "cardAction": "CHARGE",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "0",
            "card": "1000000000002",
            "cardAction": "ACTIVATION",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "300.0",
            "card": "1000000000003",
            "cardAction": "CHARGE",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "0",
            "card": "1000000000003",
            "cardAction": "ACTIVATION",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "300.0",
            "card": "1000000000004",
            "cardAction": "CHARGE",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "0",
            "card": "1000000000004",
            "cardAction": "ACTIVATION",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "300.0",
            "card": "1000000000005",
            "cardAction": "CHARGE",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        },
        {
            "amount": "0",
            "card": "1000000000005",
            "cardAction": "ACTIVATION",
            "date": "2020-04-29T12:41:07Z",
            "storeCode": null,
            "transactionId": null
        }
    ]
}

Tipos de Elementos

Cuando se especifica el parámetro "isTypes" se retornarán solamente los tipos de elemento definidos.

EJEMPLO 3: "isType=true"

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2020-10-5_12-32-47.png

Via CURL

-- curl
-- X GET -H "Authorization: Bearer 8c014b30-a674-456e-bc18-29a072a7a1f8
-- H "Content-type: application/json" -H "Accept: application/json" "http://localhost:8080/promo/api/rest/card?companyId=napse&isTypes=true"

El cual recibirá una respuesta del tipo:

-- {
    "cardTypes": [
        {
            "amountChargeLimit": 0.0,
            "cardNumberLength": 16,
            "cardTypePrefixRange": [
                {
                    "_id": "5f45547d830a697a4012df3c",
                    "creationAt": "2020-08-25T18:12:13Z",
                    "isSuggested": false,
                    "prefixEnd": 1000,
                    "prefixStart": 1
                },
                {
                    "_id": "5f45547d830a697a4012df3d",
                    "creationAt": "2020-08-25T18:12:13Z",
                    "isSuggested": false,
                    "prefixEnd": 2000,
                    "prefixStart": 1001
                }
            ],
            "code": "tc01",
            "customerValidation": "NO",
            "description": "TC01",
            "isActive": true,
            "isCVVRequired": false,
            "isNominated": false,
            "isRechargeable": true,
            "name": "TC01"
        },
        {
            "amountChargeLimit": 5000.0,
            "cardNumberLength": 11,
            "cardTypePrefixRange": [
                {
                    "_id": "5f45575d830a697a4012df40",
                    "creationAt": "2020-08-25T18:24:29Z",
                    "isSuggested": false,
                    "prefixEnd": 3000,
                    "prefixStart": 3000
                }
            ],
            "code": "tc02",
            "customerValidation": "FILE",
            "description": "TC02",
            "isActive": false,
            "isCVVRequired": true,
            "isNominated": true,
            "isRechargeable": true,
            "name": "TC02"
        }
    ]
}

Estado de puntos de Elementos de Fidelidad

PROMO expone un servicio que permite consultar el estado de los puntos de un elemento de fidelidad a la BBDD utilizando solo su número del elemento y como respuesta se obtienen los datos del estado de los puntos del elemento en cuestión y los movimientos asociados a dicha elemento.

Los datos que se devuelven son: número y tipo de elemento de fidelidad, Id de transacción, acción realizada, tienda, fecha de la transacción, cantidad de puntos involucrados en la acción y código del cliente.

Para consumir este servicio se debe realizar una solicitud del tipo GET con los parámetros correspondientes a la siguiente URL:

-- http://servidor:puerto/promo/api/rest/statementPoints

Los parámetros de entrada de la consulta son:

Propiedad	Tipo de Dato	Descripción
*companyId*	Alfanumérico	Código de la compañía. Requerido
*toDate*	Numérico	Fecha de Final en formato YYYYMMDD. Requerido
*fromDate*	Numérico	Fecha de Inicio en formato YYYYMMDD. Requerido
*customerCode*	Alfanumérico	Identificador único del cliente. Requerido
*isConsume*	Booleano	Si ha sido consumida o no. Requerido

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_8-2-14.png

Todos estos datos son requeridos; cuando falte alguno de ellos la aplicación enviará un mensaje como el ejemplo:

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_8-3-33.png

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_8-3-59.png

El rango de fechas no puede ser mayor a un mes:

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_8-6-6.png

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_8-6-28.png

El Formato de la Respuesta será (JSON):

Propiedad	Tipo de Dato	Descripción
cardNumber	Alfanumérico	Número del elemento de fidelidad asociado al cliente
cardTypeCode	Alfanumérico	identificador único de tipo de elemento de fidelidad
transactionId	Numérico	Número de transacción
action	Alfanumérico	Acción llevada a cabo (Otorga, Consumo)
storeCode	Alfanumérico	Identificador único de Tienda donde se llevó a cabo la transacción
date	Numérico	Fecha y hora de la transacción
amount	Numérico	Cant. de puntos participantes en la transacción
customerCode	Alfanumérico	Identificador único del cliente
terminalCode	Alfanumérico	Terminal donde se realizó la transacción

La respuesta al Ej 1 es:

-- [
    {
        "cardNumber": "6000011014",
        "cardTypeCode": "10",
        "transactionId": "napse_napse_1_20220831120500",
        "action": "Consumo",
        "storeCode": "napse",
        "date": "31/08/2022 12:05",
        "amount": 200.0,
        "customerCode": "1",
        "terminalCode": "1"
    }
]

Servicio De Consulta de Mapas

PROMO expone un servicio que permite consultar mapas utilizando solo el número de mapa y como respuesta se obtiene el xml del mapa de la misma forma que se obtiene por la opcion de "descargar".

Como en el caso de los servicios REST previamente descriptos se necesita una authorizacion vía OAuth2.

La siguiente figura muestra el contenido del request de ejemplo:

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2019-2-15_19-33-32.png

Donde:

operation: valor getMaps para obtener el mapa solicitado. Requerido
companyId: identificación o código de empresa la cual realiza el request. Requerido
mapNumber: Numero de mapa solicitado. Requerido.

La respuesta es del tipo:

-- <?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>   
    <ack>0</ack>
    <message>OK</message>
    <maps>
        <map version:="5">
            <?xml version="1.0" encoding="iso-8859-1"?>
            <promo-engine start-date="15/01/2019 00:00" end-date="22/01/2084 23:59" validity-after-void="365" map-version="5" suggest="conditional">
                <parameter key="Logging" value="true" />
                <parameter key="LogConfigurationFile" value="logrsca.xml" />
                <parameter key="LogConfigurationCategory" value="com.synthesis.promo" />
                <parameter key="Descriptors" value="descriptor.properties" />
                <parameter key="DAOConfigurationFeatures" value="com.synthesis.promo.engine.dao.ConfigurationFeatures" />
                <parameter key="EvaluationAlgorithmClass" value="com.synthesis.promo.engine.evaluation.InStepsAlgorithm" />
                <promotions>
                    <promotion nro="5c3df6e0f7a021227ca8f7d4" name="Promociòn 10% de Descuento SKU 1" code="Promociòn 10% de Descuento SKU 1" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="true" suggest="not" descriptor="Promociòn 10% de Descuento SKU 1">
                        <sets>
                            <set name="5c3df6f6f7a021227ca8f7d8" type="item" attribute="code" comparator="Into" value="1" />
                        </sets>
                        <condition type="basic" name="Exists">
                            <parameter key="use-set" value="5c3df6f6f7a021227ca8f7d8" />
                        </condition>
                        <benefits>
                            <benefit instance="PercentageDiscount" nro="5c3df748f7a021227ca8f7dc">
                                <parameter key="displayMessage" value="Promociòn 10% de Descuento SKU 1" />
                                <parameter key="printerMessage" value="Promociòn 10% de Descuento SKU 1" />
                                <parameter key="TLOGMessage" value="Promociòn 10% de Descuento SKU 1" />
                                <parameter key="applicationMethod" value="lineByLine" />
                                <parameter key="prorationMethod" value="proportional" />
                                <parameter key="applicationPriceType" value="benefited-price" />
                                <parameter key="name" value="5c3df6e0f7a021227ca8f7d4" />
                                <parameter key="percent" value="10" />
                                <parameter key="unit" value="qty" />
                                <applied-elements>
                                    <use-set name="5c3df6f6f7a021227ca8f7d8" />
                                </applied-elements>
                            </benefit>
                        </benefits>
                    </promotion>
                    <promotion nro="5c3dfcd5f7a021227ca8f807" name="Promocion 3x2 en SKU 2" code="Promocion 3x2 en SKU 2" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="true" suggest="always" descriptor="Con 3 items del SKU 2 obtendra Promocion 3x2 en SKU 2">
                        <sets>
                            <set name="5c3dfd00f7a021227ca8f80c" type="item" attribute="code" comparator="Into" value="2" />
                        </sets>
                        <combo>
                            <combo-component min="3" max="3" attribute="qty" use-set="5c3dfd00f7a021227ca8f80c" />
                        </combo>
                        <benefits>
                            <benefit instance="PercentageDiscount" nro="5c3dfd52f7a021227ca8f80e">
                                <parameter key="displayMessage" value="Promocion 3x1 en SKU 2" />
                                <parameter key="printerMessage" value="Promocion 3x1 en SKU 2" />
                                <parameter key="TLOGMessage" value="Promocion 3x1 en SKU 2" />
                                <parameter key="applicationMethod" value="resume" />
                                <parameter key="prorationMethod" value="proportional" />
                                <parameter key="applicationPriceType" value="benefited-price" />
                                <parameter key="name" value="5c3dfcd5f7a021227ca8f807" />
                                <parameter key="percent" value="100" />
                                <parameter key="unit" value="qty" />
                                <applied-elements>
                                    <use-set name="5c3dfd00f7a021227ca8f80c" max="1.0" attribute="qty" />
                                </applied-elements>
                            </benefit>
                        </benefits>
                    </promotion>
                    <promotion nro="5c3dffd1f7a021227ca8f82e" name="Promocion Cupon de Regalo en SKU 3" code="Promocion Cupon de Regalo en SKU 3" className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="true" suggest="not">
                        <sets>
                            <set name="5c3e0041f7a021227ca8f835" type="item" attribute="code" comparator="Into" value="3" />
                        </sets>
                        <condition type="basic" name="Exists">
                            <parameter key="use-set" value="5c3e0041f7a021227ca8f835" />
                        </condition>
                        <benefits>
                            <benefit instance="CouponBenefit" nro="5c3e0001f7a021227ca8f832">
                                <parameter key="displayMessage" value="Promocion Cupon de Regalo en SKU 3" />
                                <parameter key="printerMessage" value="Promocion Cupon de Regalo en SKU 3" />
                                <parameter key="TLOGMessage" value="Promocion Cupon de Regalo en SKU 3" />
                                <parameter key="applicationMethod" value="resume" />
                                <parameter key="prorationMethod" value="proportional" />
                                <parameter key="applicationPriceType" value="benefited-price" />
                                <parameter key="name" value="5c3dffd1f7a021227ca8f82e" />
                                <parameter key="qty" value="1" />
                                <parameter key="couponid" value="tc01" />
                                <applied-elements>
                                    <use-set name="5c3e0041f7a021227ca8f835" max="1.0" attribute="qty" />
                                </applied-elements>
                            </benefit>
                        </benefits>
                    </promotion>
                </promotions>
                <evaluation-algorithm>
                    <step>
                        <function name="ALL">
                            <function name="SIMPLE">
                                <promotion-usage name="Promociòn 10% de Descuento SKU 1" />
                            </function>
                            <function name="SIMPLE">
                                <promotion-usage name="Promocion 3x2 en SKU 2" />
                            </function>
                            <function name="SIMPLE">
                                <promotion-usage name="Promocion Cupon de Regalo en SKU 3" />
                            </function>
                        </function>
                    </step>
                </evaluation-algorithm>
            </promo-engine>
        </map>
    </maps>
</promoCoreResponse>

Donde se observa:

ack: resultado del request, donde 0 es procesamiento correcto. (Ver códigos de respuesta ack mas arriba en este documento).
message: es el mensaje de error resultante.
maps: tag general que contiene los elementos map retornados en la respuesta. Cada elemento map, contiene todos los elementos y tags que contiene un mapa como cuando es descargado a archivo.

Servicio De Consulta de Promociones Distribuidas

PROMO expone un servicio que permite consultar promociones distribuidas utilizando un filtro por compañía (obligatorio) y parámetros de filtros opcionales (tienda/as, región/es, código/os) y como respuesta se obtiene un xml con las promociones obtenidas.

Como en el caso de los servicios REST previamente descriptos se necesita una autorización vía OAuth2.

La siguiente figura muestra el contenido del GET del ejemplo:

-- http://[SERVER]:[PORT]/promo/api/rest/promotions

-- <promoCoreRequest>
<operation>getPromotions</operation>
<companyId>2</companyId>
<params>
     <promoCode>canje</promoCode>
     <store>3</store>
     <region>1</region>
</params>
</promoCoreRequest>

Donde:

Operation (obligatorio): valor getPromotions para obtener promociones.
companyId (obligatorio): identificación o código de empresa la cual realiza el request.
store (opcional): Tienda/s a la que pertenece la / las promociones.
region (opcional): Zona/s a la que pertenece la / las promociones.
promoCode (opcional): Código / os de promociones solicitadas

La respuesta es del tipo:

-- <?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>
	<ack>0</ack>
	<message value="" />
	<promotions>
		<promotion nro="64d140e6b29c1e1764334c1f" name="Promo Canje" code="canje"
			className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="true" suggest="not"
			promotionType="1" promotionSubType="1" promotionApplicationForm="1">
			<sets>
				<set name="64d140ecb29c1e1764334c23" type="item" />
			</sets>
			<condition type="basic" name="Exists">
				<parameter key="use-set" value="64d140ecb29c1e1764334c23" />
			</condition>
			<benefits>
				<benefit instance="RedeemPointsBenefit" nro="64d14116b29c1e1764334c26">
					<parameter key="displayMessage" value="Promo Canje" />
					<parameter key="printerMessage" value="Promo Canje" />
					<parameter key="TLOGMessage" value="Promo Canje" />
					<parameter key="applicationMethod" value="resume" />
					<parameter key="prorationMethod" value="proportional" />
					<parameter key="applicationPriceType" value="benefited-price" />
					<parameter key="name" value="64d140e6b29c1e1764334c1f" />
					<parameter key="type" value="5" />
					<parameter key="factor" value="1" />
					<parameter key="recoveryValue" value="0" />
					<parameter key="recoveryType" value="" />
					<parameter key="prorateBCP" value="false" />
					<applied-elements>
						<use-set name="64d140ecb29c1e1764334c23" />
					</applied-elements>
				</benefit>
			</benefits>
		</promotion>
	</promotions>
</promoCoreResponse>

Donde se observa:

ack: resultado del request, donde 0 es procesamiento correcto. (Ver códigos de respuesta ack mas arriba en este documento).
message: es el mensaje de error resultante.
promotions: tag general que contiene los elementos promotion retornados en la respuesta. Cada elemento promotion, contiene todos los elementos y tags que contiene una promoción.

Servicio De Consulta de Promociones Disponibles x MAPA

PROMO expone un servicio que permite consultar promociones disponibles utilizando un filtro por compañía y versión de mapa (obligatorios) y el código de Promoción como parámetro de filtro opcionales.

Para utilizar este servicio se debe realizar una solicitud del tipo GET con los parámetros correspondientes a la siguiente URL:

-- http://servidor:puerto/promo/api/rest/promotionAvailable

La siguiente figura muestra el contenido del request de ejemplo:

Napse > PROMO 7.8 - Manual de Integración - Servicios > image-2023-8-8_13-1-16.png

Los parámetros de entrada son:

Propiedad	Tipo de Dato	Descripción
mapVersion	Alfanumérico	Versión de Mapa que contiene la promoción. Requerido
companyId	Alfanumérico	Identificador único de la empresa. Requerido
promotionCode	Alfanumérico	código de la promoción que forma parte del mapa. No requerido

Los parámetros de salida son:

Propiedad	Tipo de Dato	Descripción
mapVersion	Alfanumérico	Versión del mapa requerido.
code	Alfanumérico	código de la promoción que está contenida en el mapa.
name	String	nombre de la promoción.
conditionSimple	String	condición simple de la promoción.
conditionCombo	String	condición combo de la promoción.
conditionDate	Alfanumérico	condición de fechas de la promoción.
benefitTypeDescription	String	Descripción del tipo de beneficio de la promoción.
benefitClassDescription	String	Descripción de la clase de beneficio de la promoción.
benefit	String	Descripción del beneficio de la promoción.
promotionType	String	Tipo al que pertenece la promoción.
promotionSubType	String	Subtipo al que pertenece la promoción.
promotionApplicationForm	String	Forma de aplicación de la promoción.

La respuesta es del tipo:

-- [
    {
        "mapVersion": "86",
        "code": null,
        "name": "Promo P1",
        "conditionSimple": "Productos con Aplica a TODOS",
        "conditionCombo": "",
        "conditionDate": "",
        "benefitTypeDescription": "<p>1.- Monetario</p><br/>",
        "benefitClassDescription": "<p>1.- Descuento porcentaje</p><br/>",
        "benefit": "<p>1.- Productos con Aplica a TODOS. El siguiente porcentaje (%) 100. Por cada unidad de Cantidad. Prorratear entre Participantes No. Valor de Recupero 0. Tipo de Recupero -. Balance -</p> ",
        "promotionType": "1",
        "promotionSubType": "1",
        "promotionApplicationForm": "1"
    }
]

Servicio De Consulta de Promociones Disponibles x COMPAÑÍA

PROMO expone un servicio que permite consultar todas las promociones disponibles que se ven en la pantalla "Gestión de promociones" para una compañía especifica (código de compañía obligatorio). Opcionalmente es posible filtrar por rango de fechas "Desde" y "Hasta", y/o por "Tienda" y/o por "Campaña".

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/promotions/allAvailable

Consideraciones para el servicio:

Filtros opcionales:

Se puede consultar por rango de fechas (dateFrom y dateTo), tienda (store) o campaña (campaign). Todos estos filtros son opcionales, lo que significa que la consulta puede realizarse con o sin ellos.
Aunque los campos dateFrom y dateTo son opcionales, es necesario que se envíen ambos juntos para que el servicio consulte correctamente dentro de un rango de fechas.
Si no se especifica un filtro de tienda, se devolverán todas las promociones independientemente de si tienen una condición por tienda.
Si el nombre de la campaña contiene espacios, estos deben codificarse con "+" o "%20".

Rango de fechas:

Si no se establece una condición de fechas en la promoción, esta se considerará válida y se incluirá en los resultados.
Si una promoción tiene una condición por fecha, los rangos deben coincidir al menos en parte con los filtros especificados para que se incluya en los resultados.
Las promociones con otras variantes como la periodicidad (por ejemplo, todos los lunes) también se considerarán válidas si coinciden con el rango de fechas.

Condiciones de tienda:

Si la promoción tiene una condición específica por tienda y el filtro store incluye esa tienda, se devolverá esa promoción.
Además, si se filtra por tienda, se incluirán todas las promociones que no tengan una condición específica de tienda.

La siguiente figura muestra el contenido del request de ejemplo:

Napse > PROMO 7.8 - Manual de Integración - Servicios > image-2024-10-6_9-52-22.png

Los parámetros de entrada son:

Propiedad	Tipo de Dato	Descripción
companyId	Alfanumérico	Identificador único de la empresa. Requerido
*dateFrom*	Numérico	Fecha de Inicio en formato YYYYMMDD. Opcional
*dateTo*	Numérico	Fecha de Final en formato YYYYMMDD. Opcional
*store*	Alfanumérico	Código de Tienda (storeCode). Default: Todas. Opcional
*campaign*	Alfanumérico	Nombre de la Campaña. Opcional
*offset*	Numérico	Registro desde el cual comenzar el conteo hasta “max” registros. Default: 0. Opcional
*max*	Numérico	Máximo de registros a retornar con un máximo de 100 por consulta. Opcional

Jerarquía de productos:

Las promociones relacionadas con productos deben respetar la jerarquía de departamentos, familias, categorías y subcategorías.
Cada nivel de la jerarquía tiene un campo específico en el JSON de respuesta:
- Departamento → conditionDepartment
- Familia → conditionFamily
- Categoría → conditionCategory
- Subcategoría → conditionSubCategory
Estas condiciones deben reflejar lo que el usuario ingresó en los campos correspondientes durante la configuración de la promoción.

Limitaciones por tienda:

Si se especifica una tienda que no existe o que no está incluida en ninguna promoción, el servicio devolverá solo aquellas promociones que no tienen ninguna condición por tienda.

Los parámetros de salida son:

Propiedad	Tipo de Dato	Descripción
promotions	Array	Lista de promociones
conditionCategoryComparator	String	Comparador para la categoría
conditionZoneComparator	String	Comparador para la zona
conditionFormat	Array	Lista de formatos
conditionSubCategoryComparator	String	Comparador para subcategoría
endDate	String	Fecha de finalización de la promoción
conditionBarcodeComparator	String	Comparador para código de barras
conditionDepartment	Array	Lista de departamentos
conditionSupplierComparator	String	Comparador para proveedor
conditionCouponComparator	String	Comparador para cupón
newPrice	Number	Nuevo precio de la promoción
conditionBarcode	Array	Lista de códigos de barras
frequency	Array	Frecuencia de la promoción
discountPercentage	Number	Porcentaje de descuento
createdAt	String	Fecha de creación
conditionSku	Array	Lista de códigos SKU
conditionBrandComparator	String	Comparador para la marca
conditionSkuComparator	String	Comparador para SKU
conditionFamilyComparator	String	Comparador para familia
benefitsMaxApplicationValue	Number	Valor máximo de aplicación de beneficios
conditionSupplier	Array	Lista de proveedores
conditionSubCategory	Array	Lista de subcategorías
updatedBy	String	Usuario que actualizó
stores	Array	Lista de tiendas
active	Boolean	Indica si está activa
nro	String	Número mero de promoción
conditionDepartmentComparator	String	Comparador para departamento
applicationBenefit	Array	Lista de beneficios aplicados
conditionBrand	Array	Lista de marcas
conditionCoupon	Array	Lista de cupones
benefitClassField	Object	Clase de beneficios
createdBy	String	Usuario que créa
conditionFamily	Array	Lista de familias
conditionZone	Array	Lista de zonas
lastUpdate	String	Ãšltima actualización
name	String	Nombre de la promoción
conditionCategory	Array	Lista de categoría
comboComponentsMax	Number	MÃ¡ximo de componentes en el combo
campaign	Object	Detalles de la campañía
startDate	String	Fecha de inicio
conditionFormatComparator	String	Comparador para formato

Formato de la respuesta:

La respuesta incluirá solo promociones activas, excluyendo aquellas que estén incompletas o canceladas.
El JSON de respuesta seguirá el mismo formato que el servicio RabbitMQ utilizado en la integración de promociones.

Campos clave:

discountPercentage: Si la clase del beneficio de la promoción es de tipo "Descuento Porcentaje", este campo mostrará el valor correspondiente. De lo contrario, devolverá 0.
comboComponentsMax: Representa la cantidad de ítems necesaria para cumplir con la condición de la promoción. Para promociones simples, será 1, mientras que para promociones compuestas se extrae el valor de combo.components(max).
benefitsMaxApplicationValue: Indica la cantidad afectada por el beneficio de la promoción.

La respuesta es del tipo:

-- {
    "promotions": [
        {
            "conditionCategoryComparator": "",
            "conditionZoneComparator": "",
            "conditionFormat": [],
            "conditionSubCategoryComparator": "",
            "endDate": "",
            "conditionBarcodeComparator": "",
            "conditionDepartment": [],
            "conditionSupplierComparator": "",
            "conditionCouponComparator": "",
            "newPrice": 0,
            "conditionBarcode": [],
            "frequency": [],
            "discountPercentage": 5,
            "createdAt": "2024-10-06T12:01:40Z",
            "conditionSku": [
                "1111"
            ],
            "conditionBrandComparator": "",
            "conditionSkuComparator": "Into",
            "conditionFamilyComparator": "",
            "benefitsMaxApplicationValue": 1,
            "conditionSupplier": [],
            "conditionSubCategory": [],
            "updatedBy": "admin",
            "stores": [],
            "active": true,
            "nro": "67027c240cd5198d64f220d6",
            "conditionDepartmentComparator": "",
            "applicationBenefit": [
                "1111"
            ],
            "conditionBrand": [],
            "conditionCoupon": [],
            "benefitClassField": {},
            "createdBy": "admin",
            "conditionFamily": [],
            "conditionZone": [],
            "lastUpdate": "2024-10-06T12:02:30Z",
            "name": "testSrvSku",
            "conditionCategory": [],
            "comboComponentsMax": 1,
            "campaign": {
                "companyId": "prueba",
                "endDate": "2023-09-29T11:55:44Z",
                "name": "BLACK FRIDAY",
                "description": "BLACK FRIDAY",
                "_id": "64ef2e400cd519a52643b68e",
                "isActive": true,
                "startDate": "2023-08-30T11:55:44Z"
            },
            "startDate": "",
            "conditionFormatComparator": ""
        }
    ]
}

Servicio De Consulta de Promociones Disponibles x SKU

PROMO expone un servicio que permite consultar todas las promociones que se ven en la pantalla "Gestión de promociones" filtrando por un SKU específico pudiendo filtrar en caso de ser necesario por rango de fechas "Desde" y "Hasta", y/o por "Tienda" y/o por "Campaña".

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/promotions/allBySku

Consideraciones para el servicio

Filtrado por SKU: El servicio permite obtener todas las promociones relacionadas con un SKU específico. Es obligatorio enviar el campo SKU para realizar la consulta.

Filtros opcionales: Se pueden incluir los siguientes filtros adicionales para refinar la búsqueda:

dateFrom: Fecha de inicio en formato YYYYMMDD. Es opcional.
dateTo: Fecha de fin en formato YYYYMMDD. Es opcional.
store: Código de la tienda. Si no se especifica, devolverá todas las promociones aplicables a todas las tiendas.
campaign: Nombre de la campaña de la promoción. También es opcional.

Rango de fechas:

Si se proporcionan las fechas dateFrom y dateTo, solo se devolverán las promociones que caigan dentro de ese rango.
Si la promoción no tiene una condición por fecha, igual será válida dentro del rango indicado.
Aunque los campos dateFrom y dateTo son opcionales, es necesario que se envíen ambos juntos para que el servicio consulte correctamente dentro de un rango de fechas.
Si la promoción tiene una periodicidad (como semanal o mensual), se considerará como válida si cae en alguno de los días dentro del rango.

La siguiente figura muestra el contenido del request de ejemplo:

Napse > PROMO 7.8 - Manual de Integración - Servicios > image-2024-10-7_8-42-21.png

Las propiedades de entrada son:

Propiedad	Tipo de dato	Descripción
*companyId*	Alfanumérico	Código de la compañía. Requerido
*dateFrom*	Numérico	Fecha de Inicio en formato YYYYMMDD. Opcional
*dateTo*	Numérico	Fecha de Final en formato YYYYMMDD. Opcional
*sku*	Alfanumérico	Código del producto. Requerido
*store*	Alfanumérico	Código de Tienda (storeCode). Default: Todas. Opcional
*campaign*	Alfanumérico	Nombre de la Campaña. Opcional

Jerarquía de productos:

El sistema respeta una jerarquía de categorías en productos:

Departamento (nivel 1)
Familia (nivel 2)
Categoría (nivel 3)
Subcategoría (nivel 4) Al filtrar por estas jerarquías, se mostrarán las promociones correspondientes a la condición aplicada.

Consulta por tienda:

Si una promoción tiene una condición específica de tienda y se envía el filtro de esa tienda, se devolverá la promoción, junto con las promociones que no tengan una condición de tienda.
Si se filtra por una tienda que no esté en ninguna promoción, se devolverán solo las promociones sin condición de tienda.

Promociones válidas: El servicio solo devolverá promociones activas, excluyendo las promociones incompletas o canceladas.

Operadores soportados:

Solo se considera el operador "IGUAL" para las condiciones de filtrado en los productos. Otros operadores como "DISTINTO", "MAYOR" o "MENOR" no se toman en cuenta.
Las listas vacías se devuelven como [], nunca se devolverá un valor -1.

Formato de fechas: Las fechas devueltas por el servicio estarán en formato ISO DATE, como por ejemplo: 2024-03-31T20:20:47Z.

Los parámetros de salida son:

Propiedad	Tipo de Dato	Descripción
promotions	Array	Lista de promociones
endDate	String	Fecha de finalización
suggestMessage	String	Mensaje sugerido
promotionStatus	Object	Estado de la promoción
frequency	Array	Frecuencia
alwaysValid	Boolean	Siempre válida
createdAt	String	Fecha de creación
id	String	Identificador
benefitsMaxApplicationValue	Number	Valor máximo de aplicación
deploymentChannels	Array	Canales de despliegue
isEditedPromotion	Boolean	Promoción editada
updatedBy	String	Actualizado por
workflow	Object	Información del workflow
active	Boolean	Indica si está activa
combo	Null	Combinación
reportParticipants	Boolean	Participantes del reporte
isWorkflowApproved	Boolean	Aprobado por workflow
conditionBrand	Array	Condiciones por marca
promotionApplicationForm	Object	Formulario de aplicación
companyId	String	Identificador de la compañía
condition	Object	Condiciones de la promoción
conditionCoupon	Array	Condiciones por cupón
conditionFamily	Array	Condiciones por familia
lastUpdate	String	Última actualización
name	String	Nombre de la promoción
conditionCategory	Array	Condiciones por categoría
campaign	Object	Información de la campañía
comboComponentsMax	Number	Máximo de componentes del combo
pictureToolTip	Null	Tooltip de la imagen
startDate	String	Fecha de inicio
benefits	Array	Lista de beneficios
code	Null	Código de la promoción
isWorkflowRejected	Boolean	Rechazado por workflow
description	Null	Descripción
conditionDepartment	Array	Condiciones por departamento
baseTemplate	Null	Plantilla base
discountPercentage	Number	Porcentaje de descuento
suggestType	Null	Tipo sugerido
conditionSku	Array	Condiciones por SKU
conditionTimeRange	Null	Rango de tiempo
skuEvaluationCode	String	Código de evaluación del SKU
cancelReason	Array	Motivo de cancelación
conditionSupplier	Array	Condiciones por proveedor
picturePath	Object	Ruta de la imagen
conditionSubCategory	Array	Condiciones por subcategoría
promotionType	Boolean	Tipo de promoción
stores	Boolean	Lista de tiendas
suggest	Null	Sugerido
evaluateConditionInCombo	String	Evaluar condición en combo
statusDescription	Array	Descripción del estado
createdBy	Object	Creado por
hdrFlds	Null	Campos del encabezado
promotionSubType	Null	Subtipo de la promoción

La respuesta es del tipo:

-- {
    "promotions": [
        {
            "endDate": "",
            "suggestMessage": "Redime Loyalty",
            "promotionStatus": {
                "name": "DEPLOYEDEDITABLE"
            },
            "frequency": [],
            "alwaysValid": true,
            "createdAt": "2023-09-07T19:42:39Z",
            "id": "64fa27af2590dc0b9c78ab27",
            "benefitsMaxApplicationValue": 1,
            "deploymentChannels": [
                {
                    "companyId": "fidelidad",
                    "code": "pos",
                    "social": false,
                    "name": "Punto de venta",
                    "id": "64f7b2ca2590dc0b9c789cc4"
                }
            ],
            "isEditedPromotion": false,
            "updatedBy": "",
            "workflow": {
                "workflowSteps": [
                    {
                        "isFinalStep": true,
                        "workflow": {},
                        "secRole": {
                            "authority": "ROLE_ADMIN",
                            "description": "Administrador",
                            "weight": 1,
                            "id": 1,
                            "homePage": {
                                "code": "indexPromotion",
                                "actionHomeAccess": "index",
                                "name": "Lista de promociones",
                                "id": 1,
                                "controllerHomeAccess": "Promotion"
                            },
                            "enabled": true
                        },
                        "name": "Captura",
                        "id": "64f7b2ca2590dc0b9c789cbd",
                        "isInitialStep": true,
                        "order": 1
                    }
                ],
                "companyId": "fidelidad",
                "name": "Workflow general",
                "appliesTo": [
                    {
                        "name": "PROMOTION_WORKFLOW"
                    },
                    {
                        "name": "PRICELIST_WORKFLOW"
                    },
                    {
                        "name": "PROMOTION_CONDITION_BASE_WORKFLOW"
                    }
                ],
                "description": "Pasos necesarios para poder aprobar una promoción",
                "id": "64f7b2ca2590dc0b9c789cbc",
                "workflowHistories": []
            },
            "active": true,
            "combo": null,
            "reportParticipants": false,
            "isWorkflowApproved": true,
            "conditionBrand": [],
            "promotionApplicationForm": {
                "createdAt": "2023-09-05T22:59:25Z",
                "companyId": "fidelidad",
                "isDefault": true,
                "code": "1",
                "name": "Genérico",
                "description": "Genérico",
                "id": "64f7b2cd2590dc0b9c789ce6",
                "isActive": true
            },
            "companyId": "fidelidad",
            "condition": {
                "children": [
                    {
                        "children": [],
                        "elementSet": {
                            "children": [],
                            "simple": true,
                            "id": "64fa2a2e2590dc0b9c78ab54",
                            "setType": {
                                "applyForCombo": true,
                                "code": "item",
                                "name": "Productos",
                                "id": "641c9b982590dc0ae0d9466e",
                                "isActive": true
                            },
                            "setTypeAttribute": {
                                "isRequired": false,
                                "code": "all",
                                "disabledByDefault": false,
                                "chainValidationChildFields": [],
                                "applyForEquivalenceAttribute": true,
                                "applyForInequivalenceAttribute": true,
                                "setType": {
                                    "applyForCombo": true,
                                    "code": "item",
                                    "name": "Productos",
                                    "id": "641c9b982590dc0ae0d9466e",
                                    "isActive": true
                                },
                                "type": "All",
                                "chainValidation": false,
                                "isPromoDefaultAttribute": true,
                                "name": "Aplica a TODOS",
                                "entityCatalog": null,
                                "id": "641c9b982590dc0ae0d9467a",
                                "measurable": false
                            },
                            "value": "all",
                            "operator": {
                                "name": "SIMPLE"
                            },
                            "setTypeAttributeComparator": null
                        },
                        "simple": true,
                        "id": "64fa2a2e2590dc0b9c78ab55",
                        "conditionComparator": {
                            "code": "Exists",
                            "name": "SIN AGRUPACION",
                            "id": "641c9b982590dc0ae0d94664"
                        },
                        "operator": {
                            "name": "SIMPLE"
                        }
                    },
                    {
                        "children": [],
                        "elementSet": {
                            "children": [],
                            "simple": true,
                            "id": "64fa2a3d2590dc0b9c78ab57",
                            "setType": {
                                "applyForCombo": true,
                                "code": "loyaltycard",
                                "name": "Elementos de fidelidad",
                                "id": "6421d63a2590dc0ae0d94947",
                                "isActive": true
                            },
                            "setTypeAttribute": {
                                "isRequired": false,
                                "code": "type",
                                "disabledByDefault": false,
                                "chainValidationChildFields": [],
                                "applyForEquivalenceAttribute": true,
                                "applyForInequivalenceAttribute": true,
                                "setType": {
                                    "applyForCombo": true,
                                    "code": "loyaltycard",
                                    "name": "Elementos de fidelidad",
                                    "id": "6421d63a2590dc0ae0d94947",
                                    "isActive": true
                                },
                                "type": "autocomplete",
                                "chainValidation": false,
                                "isPromoDefaultAttribute": true,
                                "name": "Tipo",
                                "entityCatalog": "CardType",
                                "id": "6421d63a2590dc0ae0d94949",
                                "measurable": false
                            },
                            "value": "5566",
                            "operator": {
                                "name": "SIMPLE"
                            },
                            "setTypeAttributeComparator": {
                                "code": "Into",
                                "name": "IGUAL",
                                "id": "641c9b982590dc0ae0d9466a"
                            }
                        },
                        "simple": true,
                        "id": "64fa2a3d2590dc0b9c78ab58",
                        "conditionComparator": {
                            "code": "Exists",
                            "name": "SIN AGRUPACION",
                            "id": "641c9b982590dc0ae0d94664"
                        },
                        "operator": {
                            "name": "SIMPLE"
                        }
                    }
                ],
                "simple": false,
                "id": "64fa2a3d2590dc0b9c78ab59",
                "operator": {
                    "name": "AND"
                }
            },
            "conditionCoupon": [],
            "conditionFamily": [],
            "lastUpdate": "2024-08-05T12:26:00Z",
            "name": "Redime Loyalty",
            "conditionCategory": [],
            "campaign": {
                "companyId": "fidelidad",
                "promotions": null,
                "endDate": "2023-10-05T22:59:22Z",
                "name": "BLACK FRIDAY",
                "description": "BLACK FRIDAY",
                "id": "64f7b2ca2590dc0b9c789cc3",
                "isActive": true,
                "deploymentChannels": [],
                "startDate": "2023-09-05T22:59:22Z"
            },
            "comboComponentsMax": 1,
            "pictureToolTip": null,
            "startDate": "",
            "benefits": [
                {
                    "replicateConditionSet": true,
                    "benefitType": {
                        "code": "monetary",
                        "name": "Monetario",
                        "id": "641c9b9a2590dc0ae0d946f8"
                    },
                    "staggeredUnit": "qty",
                    "financialProvider": null,
                    "additionalProvider1": null,
                    "additionalProvider2": null,
                    "displayMessage": "Redime Loyalty",
                    "tlogMessage": "Redime Loyalty",
                    "staggeredSteps": [],
                    "minApplicationValue": null,
                    "elementSet": {
                        "children": [],
                        "simple": true,
                        "id": "64fa2a2e2590dc0b9c78ab54",
                        "setType": {
                            "applyForCombo": true,
                            "code": "item",
                            "name": "Productos",
                            "id": "641c9b982590dc0ae0d9466e",
                            "isActive": true
                        },
                        "setTypeAttribute": {
                            "isRequired": false,
                            "code": "all",
                            "disabledByDefault": false,
                            "chainValidationChildFields": [],
                            "applyForEquivalenceAttribute": true,
                            "applyForInequivalenceAttribute": true,
                            "setType": {
                                "applyForCombo": true,
                                "code": "item",
                                "name": "Productos",
                                "id": "641c9b982590dc0ae0d9466e",
                                "isActive": true
                            },
                            "type": "All",
                            "chainValidation": false,
                            "isPromoDefaultAttribute": true,
                            "name": "Aplica a TODOS",
                            "entityCatalog": null,
                            "id": "641c9b982590dc0ae0d9467a",
                            "measurable": false
                        },
                        "value": "all",
                        "operator": {
                            "name": "SIMPLE"
                        },
                        "setTypeAttributeComparator": null
                    },
                    "id": "64fa284a2590dc0b9c78ab32",
                    "benefitDivisionMethod": {
                        "code": "proportional",
                        "name": "Proporcional",
                        "id": "641c9b9a2590dc0ae0d94709"
                    },
                    "limits": [],
                    "creditProvider": null,
                    "numericId": 140,
                    "benefitApplicationMethod": {
                        "code": "resume",
                        "name": "Resumen",
                        "id": "641c9b9b2590dc0ae0d94744"
                    },
                    "benefitClass": {
                        "benefitRedeemWithOptions": [],
                        "benefitClassFields": [
                            {
                                "isRequired": true,
                                "code": "type",
                                "name": "Tipo de Elemento de Fidelidad",
                                "description": "tipo de elemento de fidelidad",
                                "entityCatalog": "cardType",
                                "id": "641c9b9a2590dc0ae0d946d9",
                                "isCheckable": null,
                                "type": "autocomplete"
                            },
                            {
                                "isRequired": true,
                                "code": "factor",
                                "name": "Factor $1 = x Puntos",
                                "description": "Factor de conversion",
                                "entityCatalog": null,
                                "id": "641c9b9a2590dc0ae0d946da",
                                "isCheckable": null,
                                "type": "Double"
                            },
                            {
                                "isRequired": false,
                                "code": "recoveryValue",
                                "name": "Valor de Recupero",
                                "description": "Valor del Recupero",
                                "entityCatalog": null,
                                "id": "641c9b9a2590dc0ae0d946eb",
                                "isCheckable": null,
                                "type": "Double"
                            },
                            {
                                "isRequired": false,
                                "code": "recoveryType",
                                "name": "Tipo de Recupero",
                                "description": "Tipo de Recupero",
                                "entityCatalog": null,
                                "id": "641c9b9a2590dc0ae0d946ea",
                                "isCheckable": null,
                                "type": "List"
                            },
                            {
                                "isRequired": false,
                                "code": "prorateBCP",
                                "name": "Prorratear entre Participantes",
                                "description": "Prorratear entre participantes de la condicion",
                                "entityCatalog": null,
                                "id": "641c9b9a2590dc0ae0d946ed",
                                "isCheckable": null,
                                "type": "Boolean"
                            },
                            {
                                "isRequired": false,
                                "code": "balance",
                                "name": "Balance",
                                "description": "Balance",
                                "entityCatalog": "catalogBalance",
                                "id": "641c9b9a2590dc0ae0d946f4",
                                "isCheckable": null,
                                "type": "autocomplete"
                            }
                        ],
                        "code": "RedeemPointsBenefit",
                        "disabledByDefault": false,
                        "benefitClassLimitType": [],
                        "benefitType": {
                            "code": "monetary",
                            "name": "Monetario",
                            "id": "641c9b9a2590dc0ae0d946f8"
                        },
                        "name": "Canje de Puntos",
                        "id": "641c9b9f2590dc0ae0d947f1",
                        "isCheckable": false
                    },
                    "elementSetOrderCriteria": null,
                    "benefitDivisionPrice": {
                        "code": "benefited-price",
                        "name": "Precio beneficiado",
                        "id": "641c9b9a2590dc0ae0d9470d"
                    },
                    "benefitSetType": null,
                    "elementSetTypeAttribute": null,
                    "parameters": [
                        {
                            "benefitClassField": {
                                "isRequired": true,
                                "code": "type",
                                "name": "Tipo",
                                "description": "tipo de elemento de fidelidad",
                                "entityCatalog": "cardType",
                                "id": "641c9b9a2590dc0ae0d946d9",
                                "isCheckable": null,
                                "type": "autocomplete"
                            },
                            "benefitClassFieldOption": null,
                            "value": "5566"
                        },
                        {
                            "benefitClassField": {
                                "isRequired": true,
                                "code": "factor",
                                "name": "Tipo",
                                "description": "Factor de conversion",
                                "entityCatalog": null,
                                "id": "641c9b9a2590dc0ae0d946da",
                                "isCheckable": null,
                                "type": "Double"
                            },
                            "benefitClassFieldOption": null,
                            "value": "1"
                        },
                        {
                            "benefitClassField": {
                                "isRequired": false,
                                "code": "recoveryValue",
                                "name": "Valor del Recupero",
                                "description": "Valor del Recupero",
                                "entityCatalog": null,
                                "id": "641c9b9a2590dc0ae0d946eb",
                                "isCheckable": null,
                                "type": "Double"
                            },
                            "benefitClassFieldOption": null,
                            "value": "0"
                        },
                        {
                            "benefitClassField": {
                                "isRequired": false,
                                "code": "recoveryType",
                                "name": "Tipo de Recupero",
                                "description": "Tipo de Recupero",
                                "entityCatalog": null,
                                "id": "641c9b9a2590dc0ae0d946ea",
                                "isCheckable": null,
                                "type": "List"
                            },
                            "benefitClassFieldOption": null,
                            "value": null
                        },
                        {
                            "benefitClassField": {
                                "isRequired": false,
                                "code": "prorateBCP",
                                "name": "Prorratear entre participantes",
                                "description": "Prorratear entre participantes de la condicion",
                                "entityCatalog": null,
                                "id": "641c9b9a2590dc0ae0d946ed",
                                "isCheckable": null,
                                "type": "Boolean"
                            },
                            "benefitClassFieldOption": null,
                            "value": "false"
                        },
                        {
                            "benefitClassField": {
                                "isRequired": false,
                                "code": "balance",
                                "name": "Balance",
                                "description": "Balance",
                                "entityCatalog": "catalogBalance",
                                "id": "641c9b9a2590dc0ae0d946f4",
                                "isCheckable": null,
                                "type": "autocomplete"
                            },
                            "benefitClassFieldOption": null,
                            "value": ""
                        }
                    ],
                    "account": null,
                    "maxApplicationValue": null,
                    "printerMessage": "Redime Loyalty"
                }
            ],
            "code": null,
            "isWorkflowRejected": false,
            "description": null,
            "conditionDepartment": [],
            "baseTemplate": null,
            "discountPercentage": 0,
            "suggestType": null,
            "conditionSku": [],
            "conditionTimeRange": null,
            "skuEvaluationCode": "(   item )",
            "cancelReason": null,
            "conditionSupplier": [],
            "picturePath": null,
            "conditionSubCategory": [],
            "promotionType": {
                "createdAt": "2023-09-05T22:59:25Z",
                "companyId": "fidelidad",
                "isDefault": true,
                "code": "1",
                "name": "Genérico",
                "description": "Genérico",
                "id": "64f7b2cd2590dc0b9c789ce4",
                "isActive": true,
                "isUsed": true
            },
            "stores": [],
            "suggest": true,
            "evaluateConditionInCombo": false,
            "statusDescription": null,
            "createdBy": "fidelidad",
            "hdrFlds": [],
            "promotionSubType": {
                "createdAt": "2023-09-05T22:59:25Z",
                "companyId": "fidelidad",
                "isDefault": true,
                "code": "1",
                "name": "Genérico",
                "description": "Genérico",
                "id": "64f7b2cd2590dc0b9c789ce5",
                "isActive": true
            }
        }
    ]
}

Servicio De Consulta de Promoción

PROMO expone cuatro servicios que permiten consultar una promoción utilizando un filtro por compañía (obligatorio) y consultar mediante número de promoción o código de promoción o número de beneficio de promoción o nombre de promoción y como respuesta se obtiene un xml con la promoción obtenida.

Como en el caso de los servicios REST previamente descriptos se necesita una autorización via OAuth2.

Se puede acceder al servicio desde:

-- http://[Server]:[Port]/promo/api/rest/promotions

Obtener promociones por Nro.

Request:

-- <promoCoreRequest>
<operation>getPromotionsByNro</operation>
<companyId>2</companyId>
<nro>64d140e6b29c1e1764334c1f</nro>
</promoCoreRequest>

Response:

-- <?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>
	<ack>0</ack>
	<message value="" />
	<promotions>
		<promotion nro="64d140e6b29c1e1764334c1f" name="Promo Canje" code="canje"
			className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not"
			promotionType="1" promotionSubType="1" promotionApplicationForm="1">
			<sets>
				<set name="64d140ecb29c1e1764334c23" type="item" />
			</sets>
			<condition type="basic" name="Exists">
				<parameter key="use-set" value="64d140ecb29c1e1764334c23" />
			</condition>
			<benefits>
				<benefit instance="RedeemPointsBenefit" nro="64d14116b29c1e1764334c26">
					<parameter key="displayMessage" value="Promo Canje" />
					<parameter key="printerMessage" value="Promo Canje" />
					<parameter key="TLOGMessage" value="Promo Canje" />
					<parameter key="applicationMethod" value="resume" />
					<parameter key="prorationMethod" value="proportional" />
					<parameter key="applicationPriceType" value="benefited-price" />
					<parameter key="name" value="64d140e6b29c1e1764334c1f" />
					<parameter key="type" value="5" />
					<parameter key="factor" value="1" />
					<parameter key="recoveryValue" value="0" />
					<parameter key="recoveryType" value="" />
					<parameter key="prorateBCP" value="false" />
					<applied-elements>
						<use-set name="64d140ecb29c1e1764334c23" />
					</applied-elements>
				</benefit>
			</benefits>
		</promotion>
	</promotions>
</promoCoreResponse>

Obtener promociones por Codigo

Request:

-- <promoCoreRequest>
<operation>getPromotionsByCode</operation>
<companyId>2</companyId>
<promoCode>redes</promoCode>
</promoCoreRequest>

Response:

-- <?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>
	<ack>0</ack>
	<message value="" />
	<promotions>
		<promotion nro="64d0fb1db29c1e1764334bc6" name="Promo Redes" code="redes"
			className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not"
			promotionType="1" promotionSubType="1" promotionApplicationForm="1">
			<sets />
			<benefits />
		</promotion>
	</promotions>
</promoCoreResponse>

Obtener promocion por Nro. de Beneficio

Request:

-- <promoCoreRequest>
<operation>getPromotionsByBenefitNro</operation>
<companyId>2</companyId>
<nro>6489c122a62e4343b821cc9d</nro>
</promoCoreRequest>

Response

-- <?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>
	<ack>0</ack>
	<message value="" />
	<promotions>
		<promotion nro="64cbfc85a62e430ec443b4d5" name="Promo Limites Clientes Cant. de aplicaciones" code=""
			className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not"
			promotionType="1" promotionSubType="1" promotionApplicationForm="1">
			<sets>
				<set name="64cbfc85a62e430ec443b4d2" type="item" />
			</sets>
			<condition type="basic" name="Exists">
				<parameter key="use-set" value="64cbfc85a62e430ec443b4d2" />
			</condition>
			<benefits>
				<benefit instance="PercentageDiscount" nro="64cbfc85a62e430ec443b4d4">
					<parameter key="displayMessage" value="Promo Limites Clientes Cant. de aplicaciones" />
					<parameter key="printerMessage" value="Promo Limites Clientes Cant. de aplicaciones" />
					<parameter key="TLOGMessage" value="Promo Limites Clientes Cant. de aplicaciones" />
					<parameter key="applicationMethod" value="resume" />
					<parameter key="prorationMethod" value="proportional" />
					<parameter key="applicationPriceType" value="benefited-price" />
					<parameter key="name" value="64cbfc85a62e430ec443b4d5" />
					<parameter key="percent" value="50" />
					<parameter key="unit" value="qty" />
					<parameter key="prorateBCP" value="false" />
					<parameter key="recoveryValue" value="0" />
					<parameter key="recoveryType" value="" />
					<applied-elements>
						<use-set name="64cbfc85a62e430ec443b4d2" />
					</applied-elements>
				</benefit>
			</benefits>
		</promotion>
	</promotions>
</promoCoreResponse>

Obtener promociones por Nombre

Request:

-- <promoCoreRequest>
<operation>getPromotionsByName</operation>
<companyId>2</companyId>
<promoName>Promo Limite Clientes Cant. de Dinero</promoName>
</promoCoreRequest>

Response

-- ?xml version="1.0" encoding="iso-8859-1"?>
<promoCoreResponse>
	<ack>0</ack>
	<message value="" />
	<promotions>
		<promotion nro="64cbfc85a62e430ec443b4d1" name="Promo Limite Clientes Cant. de Dinero" code=""
			className="com.synthesis.promo.engine.promotion.ModularPromotion" reportParticipants="false" suggest="not"
			promotionType="1" promotionSubType="1" promotionApplicationForm="1">
			<sets>
				<set name="64cbfc85a62e430ec443b4ce" type="item" />
			</sets>
			<condition type="basic" name="Exists">
				<parameter key="use-set" value="64cbfc85a62e430ec443b4ce" />
			</condition>
			<benefits>
				<benefit instance="PercentageDiscount" nro="64cbfc85a62e430ec443b4d0">
					<parameter key="displayMessage" value="Promo Limite Clientes" />
					<parameter key="printerMessage" value="Promo Limite Clientes" />
					<parameter key="TLOGMessage" value="Promo Limite Clientes" />
					<parameter key="applicationMethod" value="resume" />
					<parameter key="prorationMethod" value="proportional" />
					<parameter key="applicationPriceType" value="benefited-price" />
					<parameter key="hasLimit" value="true" />
					<parameter key="name" value="64cbfc85a62e430ec443b4d1" />
					<parameter key="percent" value="50" />
					<parameter key="unit" value="qty" />
					<parameter key="prorateBCP" value="false" />
					<parameter key="recoveryValue" value="0" />
					<parameter key="recoveryType" value="" />
					<applied-elements>
						<use-set name="64cbfc85a62e430ec443b4ce" />
					</applied-elements>
				</benefit>
			</benefits>
		</promotion>
	</promotions>
</promoCoreResponse>

Donde:

Operation (obligatorio): valor getPromotionsByNro, getPromotionsByCode, getPromotionsByBenefitNro o getPromotionsByName.
companyId (obligatorio): identificación o código de empresa la cual realiza el request.
nro (obligatorio): para una búsqueda mediante el número de promoción o para una búsqueda mediante el número de benefició de promoción.
promoCode (obligatorio): para una búsqueda mediante el código de promoción-
promoName(obligatorio): para una búsqueda mediante el nombre de la promoción.

Donde se observa:

ack: resultado del request, donde 0 es procesamiento correcto. (Ver códigos de respuesta ack más arriba en este documento).
message: es el mensaje de error resultante.
promotions: tag general que contiene los elementos promotion retornados en la respuesta. Cada elemento promotion, contiene todos los elementos y tags que contiene una promoción.

Si el código de la promoción no es único, en la respuesta se detallará el listado de todas las promociones que tengan ese código.

Caso contrario la respuesta mostrará la información de la promoción que corresponde a ese código.

Servicio Próximo Número de elemento de fidelidad

PROMO expone un servicio que permite consultar, para un determinado tipo de elemento cual es el próximo número de elemento disponible inactivo y sin cliente asociado. Por medio de este servicio de consulta, el POS podrá conocer el número del "siguiente elemento inactivo y sin cliente asociado" para ser asignada a un cliente desde línea de cajas. Promo devolverá el número de elemento y el POS lo asociará al cliente y le reenviará (LoyaltyAssign) el número y tipo de elemento, más los datos del cliente para que se active y asigne el elemento.

Cuando no se disponga de mas elementoss inactivos y sin cliente asociado en la base de datos para el tipo de elemento consultado, se devolverá el mensaje de error indicando que no se cuenta con mas elementos disponibles para ser asociadas.

Considerar que el tipo de nominación que utilizará es "Asociación por canal de Ventas" y los elementos deberán darse de alta vía archivo.

En el archivo de alta masiva solo se informará el nro. de elemento y el Tipo.

Al darse de alta los elementos, estas quedarán en estado INACTIVO.

La activación del elemento y asignación de cliente se debe realizar por medio del "Canal de Ventas".

Para ello, una vez dadas de alta los elementos de forma masiva, desde el POS, cuando se desee dar de alta un cliente y asignarle una cuenta "prepaga" (Monedero), se enviará el mensaje de consulta de próximo Elemento (NextCardNumber). Promo informará a este mensaje el número del próximo elemento inactivo y sin cliente asignado, disponible.

Luego el POS, enviará un mensaje de asociación (LoyaltyAssign) del cliente al elemento, quedando este último activo y con el cliente informado asociado al elemento.

Servicio REST

Para los ejemplos se realizaron las consultas de elementos utilizando la herramienta "PostMan" de Chrome. Deberá obtenerse un nuevo Token, y luego podrá realizarse la consulta de próximo número de elemento

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.

-- 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)
<servername>	nombre o ip donde este alojado Promo
<port>	puerto http donde este corriendo Promo.

-- 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.

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2019-6-19_12-24-56.png

Mensaje de consulta

El cuerpo del mensaje deberá ser un xml. A continuación se detallarán las posibles peticiones y sus respuestas involucradas.

Request:

-- <promoCoreRequest>
    <operation>NextCardNumber</operation>
    <params>
        <type="555">
    </params> 
</promoCoreRequest>

Response OK

-- <promoCoreResponse>
      <ack>0</ack>
      <message>Id:"555000002200002"</message>
</promoCoreResponse>

Response No OK

-- <promoCoreResponse>
      <ack>9503</ack>
      <message>No se encontró el Tipo de tarjeta loyalty</message>
</promoCoreResponse>

Servicio De Reporte de Promociones

A partir de la version v7.EP2.1 promo disponibiliza el servicio de Repote de Promociones.

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:

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2021-5-19_15-33-34.png

La Respuesta será del tipo JSON con los siguientes parámetros:

Propiedad	Tipo de dato	Descripción
*Records*	Vector	Cada uno de los registros que componen el reporte
*Header*	Vector	Encabezado con información adicional

-- {
    "records:": "[{\"transactionId\":\"napse_Tienda1_1_20210519110000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Descuento porcentaje\",\"itemCode\":\"456\",\"discountApply\":500.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"19/05/2021 11:00\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo limite1\",\"store\":\"Tienda1\",\"subTotal\":500.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210519100000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Descuento porcentaje\",\"itemCode\":\"456\",\"discountApply\":500.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"19/05/2021 10:00\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo limite1\",\"store\":\"Tienda1\",\"subTotal\":500.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210519091000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Descuento porcentaje\",\"itemCode\":\"456\",\"discountApply\":500.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"19/05/2021 09:10\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo limite1\",\"store\":\"Tienda1\",\"subTotal\":500.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210517091000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"555\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"17/05/2021 09:10\",\"transactionType\":\"Devolución\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo EMITE CUPON Impreso\",\"store\":\"Tienda1\",\"subTotal\":1000.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210517090000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"555\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"17/05/2021 09:00\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo EMITE CUPON Impreso\",\"store\":\"Tienda1\",\"subTotal\":1000.0,\"conditionTimeRange\":\"Indefinida\"},{\"transactionId\":\"napse_Tienda1_1_20210513100000\",\"offline\":false,\"unitPrice\":1000.0,\"benefitClass\":\"Cupón\",\"itemCode\":\"555\",\"discountApply\":0.0,\"deploymentChannels\":\"Punto de venta\",\"date\":\"13/05/2021 10:00\",\"transactionType\":\"Venta\",\"campaign\":\"BLACK FRIDAY\",\"quantity\":1.0,\"promotionCode\":null,\"promotionName\":\"Promo EMITE CUPON Impreso\",\"store\":\"Tienda1\",\"subTotal\":1000.0,\"conditionTimeRange\":\"Indefinida\"}]",
    "header": {
        "total": 6,
        "offset": 0,
        "limit": 50000
    }
}

Cada elemento del Vector Récords contendrá los siguientes parámetros correspondientes a cada una de las columnas del informe:

Propiedad	Tipo de dato	Descripción
transactionId	Alfanumérico	Código de la transacción
offline	Booleano	Verdadero si la transacción fue realizada en modo offline
unitPrice	Numérico	Precio unitario del producto
benefitClass	Alfanumérico	Clase de beneficio
itemCode	Alfanumérico	Código de Producto
discountApply	Numérico	Descuento Aplicado
deploymentChannels	Alfanumérico	Canal de Publicación
date	Alfanumérico	Fecha de la transacción
transactionType	Alfanumérico	Tipo de Transacción
campaign	Alfanumérico	Campaña
quantity	Numérico	Cantidad del Producto
promotionCode	Alfanumérico	Código de Promoción
promotionName	Alfanumérico	Nombre de la Promoción
store	Alfanumérico	Tienda
subTotal	Numérico	Subtotal de la transacción
conditionTimeRange	Alfanumérico	Condición de Fecha/hora si aplica.

Cada elemento del Vector Header contendrá los siguientes parámetros Informativos:

Propiedad	Tipo de dato	Descripción
total	Numérico	Total de Registros disponibles
offset	Numérico	offset solicitado actualmente
limit	Numérico	Limite solicitado actualmente

Esta información sirve para mantener una paginación como sucede en pantalla pero a nivel servicio.

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

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2020-12-4_16-13-28.png

Obteniéndose la siguiente respuesta:

-- {
    "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
    }
}

Servicio Transaccional de Límite vía REST

PROMO expone un servicio que permite devolver la información referente al transaccional de limites para una determinada compañía.

Para ello deberá enviarse un GET a la siguiente URL.

--  http://[SERVER]:[PORT]/promo/api/rest/limit/statements

Tiene tres parámetros de ingreso:

Nombre	Valor
*companyId*	El código de la compañía. String. Requerido.
*mapVersion*	n° de mapa. Requerido
*promoCode*	Código de la promoción. String. Requerido

Deberá validarse que el mapa consultado se encuentre activo en alguno de los motores conectados a la consola.

Ejemplo

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_12-6-37.png

Se obtendría un resultado como el siguiente:

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2022-11-9_12-6-34.png

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2022-11-9_12-7-44.png

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2022-11-9_12-8-19.png

Se espera obtener como respuesta un Json que informe los movimientos de limites que hayan tenido las promociones con limites definidas en el mapa consultado.

Los datos a informar deberán ser:

Nombre	Valor
*PromotionName*	Nombre de la promoción que interviene en la transacción.
*PromotionCode*	Código de la promoción que interviene en la transacción.
*benefitType*	Tipo de Beneficio que otorga la promoción.
*benefitClass*	Clase de beneficio que otorga la transacción.
*limitScope*	Tipo de Límite que tiene el beneficio de la promoción
*limitType*	Indica el criterio por el cual se aplicará el límite.
*store*	Id de la tienda sobre las que se distribuyó el mapa donde se encuentra la promoción
*customer*	id de cliente que llevó a cabo la transacción.
*limitOriginalValue*	Valor original del límite
*limitCurrentValue*	Valor actual del límite
*storeCode*	código de la tienda donde se llevó a cabo la transacción
*date*	día en que se llevó a cabo la transacción
*transaction*	id de la transacción que aplicó esa promoción con límite
*operation*	Tipo de operación
*store*	Id de la tienda donde se llevó a cabo la transacción
*terminal*	Terminal donde se llevó a cabo la transacción.
*customer*	Id del cliente que llevó a cabo la transacción
*initialValue*	valor inicial de la transacción
*transactionValue*	valor del limite aplicado en la transacción
*finalValue*	valor final del limite aplicado en la transacción.

Ejemplo: consulta con companyId y mapVersion:

-- [
    {
        "promotionName": "PromoLimite",
        "promotionCode": null,
        "benefitType": "Monetario",
        "benefitClass": "Descuento porcentaje",
        "limitScope": "General",
        "limitType": "Cantidad de productos beneficiados",
        "store": "",
        "customer": "",
        "limitOriginalValue": "3.00",
        "limitCurrentValue": "1.00",
        "storeCode": "-",
        "detail": [
            {
                "date": "09/11/2022 10:37",
                "transaction": "napse_napse_1_20221109120000",
                "operation": "Venta",
                "store": "napse",
                "terminal": "1",
                "customer": "",
                "initialValue": "0.00",
                "transactionValue": "1.00",
                "finalValue": "1.00"
            }
        ]
    }

]

Ejemplo: companyId inexistente

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_12-7-22.png

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_12-7-43.png

Ejemplo: companyId invalido

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_12-7-22.png

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_12-7-43.png

Ejemplo: Sin conpanyId:

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_12-9-11.png

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_12-9-35.png

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_12-11-0.png

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_12-11-25.png

Ejemplo: mapa invadido:

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_12-8-24.png

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_12-8-42.png

Consola: Servicios REST de Carga de Datos

Aquí se presentan los servicios provistos para enviar o cargar información en PROMO.

Antes de consumir el servicio debe obtenerse el TOKEN de identificación como se explica en "Seguridad: Autenticación de Sistemas Externos con los Servicios"

Servicio De Importación de Catálogos

PROMO expone este 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

código de Empresa

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. Requerido

Cada catalogo puede tener sus parámetros específicos, pero como valor genérico tenemos:

"deleteAllCollectionFirst" : "true" Indica que antes de realizar la importación de este conjunto de registros se realice el borrado de todos los registros existentes.

Disponible desde: desde 6.5.5 y 7.TRK

Ejemplo:

-- [...]

-- "params": [
{ "deleteAllCollectionFirst": "true" }
],

-- [...]

Cuando se importa un nuevo catálogo, el usuario que realizó la modificación es informado en el log de la consola:

Napse > PROMO 7.8 - Manual de Integración - Servicios > image-2023-12-22_15-33-56.png

No aplica a elementos de fidelidad y asignación de convenios.

items

Registros a importar

Colección de objetos dependientes de cada catálogo. Requerido

Para el Catalogo de Clientes (catalogCustomer.catalog) podrán incorporarse a la carga de los atributos dinámicos de los ítems que se estén dando de alta. Para ello deberá especificarse el nombre de los atributos dinámicos dados de alta por consola dentro del tag

-- "items": [
-- {.... primer item .......}]

Los Atributos dinámicos cargados vía Servicio serán tomados para la validación entre atributos del elemento Producto en la definición de condiciones de una promoción, cuando ésta funcionalidad se encuentre habilitada en consola. (Ver PROMO - Manual de Usuario Final)

-- {
    "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.

Cada uno de los ítems dependerá del catalogo en su formato, pero existe un campo común a todos:

La operación a realizar sobre el elemento. Los valores posibles son:

I: Insertar
U: Actualizar
R: Eliminar
IU: Insertar/Actualizar: Si el registro no existe será insertado (I), si existe será actualizado (U). (Disponible desde 6.5.5 y 7.TRK)

No aplica a elementos de fidelidad y asignación de convenios.

Alfanumérico. Requerido

La respuesta será del tipo:

-- {
    "status": "200",
    "description": "CatalogCountry",
    "detail": {
        "result": "ok",
        "detail": "Info adicional"
    }
}

Donde:

Campo

Descripción

Tipo de Dato

Posibles valores

status

código de Respuesta

alfanumérico

200 (válido), 400 (errores de validación o de sintaxis json), 500 (error genérico)

description

identificador del catálogo

alfanumérico

Cada uno de los nombre de los catálogos importables por mensaje rest, o bien cadena vacía si no es posible obtenerlos (por ej. ante un error de sintaxis json).

detail

Información adicional

Objeto

Clave result, con los resultados posibles, es decir, ok o error.

Clave detail, con valor correspondiente al mensaje informativo de validación, error, o procesamiento válido.

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:

Para la importación de campos adicionales de la cabecera por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
   "companyId":"napse",
   "catalog":"catalogAdditionalField05", 
   "params": [],
    "items": [
        {
            "code": "100",
            "name": "dato a",
            "operation": "I"

        },
        {
            "code": "101",
            "name": "dato b",
            "operation": "I"

        },
        {
            "code": "102",
            "name": "dato c",
            "operation": "I"

        }
          ]


}

-- {
    "status": "200",
    "description": "catalogAdditionalField05",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de elementos de fidelidad por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
    "companyId": "napse",
    "catalog": "Card",
    "params": [],
    "items": [
        {
            "code": "4567000000000",
            "type": "tipo1",
            "validFrom": "",
            "validTo": "",
            "cvv": "123",
            "customerId": "1122",
            "amount": 50,
            "status": "ENABLED",
            "operation": "I"
        },
        {
            "code": "3456000000001",
            "type": "tipo2",
            "validFrom": "",
            "validTo": "",
            "cvv": "234",
            "customerId": "2233",
            "amount": 45.5,
            "status": "DISABLED",
            "operation": "U"
        },
        {
            "code": "3456000000002",
            "type": "tipo2",
            "validFrom": "",
            "validTo": "",
            "cvv": "345",
            "customerId": "2233",
            "amount": 35.5,
            "status": "ENABLED",
            "operation": "R"
        }
    ]
}

En la sección "ítems" deberán indicarse la colección de objetos dependientes de cada catálogo, en este caso, el de elementos, "Card"

Campo

Valor

code

El código del elemento.

type

El código del tipo de elemento.

validFrom

Fecha de inicio de vigencia (considerar los tipos de vigencia existentes en el tipo de elemento relacionado). Formato año-mes-día, 4 dígitos, 2 dígitos, 2 dígitos; por ej. "2020-05-14"

validTo

Fecha de fin de vigencia (considerar los tipos de vigencia existentes en el tipo de elemento relacionado). Formato año-mes-día, 4 dígitos, 2 dígitos, 2 dígitos; por ej. "2020-05-14"

cvv

Número cvv.

customerId

El código de cliente al cual pertenece el elemento (considerar el campo nominado del tipo de elemento). Alfanumérico.

amount

El monto del elemento (considerar el tipo de precarga del tipo del elemento). Numérico con decimales.

Este valor sólo se debe agregar si el tipo de elemento de fidelidad al que pertenece el elemento es precargado por archivo/servicio

status

El estado del elemento. Los valores posibles para el status son: ENABLED (elemento activo), DISABLED (elemento inactivo), CANCELED (elemento cancelado).

operation

La operación a realizar sobre el elemento. Los valores posibles son: I: Inserción / U: Actualización / R: Eliminación

Para la importación de Marcas por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
   "companyId":"napse",
   "catalog":"catalogBrand", 
   "params": [],
    "items": [
        {
            "code": "1",
            "name": "Nintendo",
            "operation": "I"

        },
        {
            "code": "2",
            "name": "Electronic Arts",
            "operation": "I"

        },
        {
            "code": "3",
            "name": "Activision Inc.",
            "operation": "I"

        }
          ]


}

-- {
   "companyId":"napse",
   "catalog":"catalogBrand", 
   "params": [],
    "items": [
        {
            "code": "1",
            "name": "Nintendo",
            "operation": "I"

        },
        {
            "code": "2",
            "name": "Electronic Arts",
            "operation": "I"

        },
        {
            "code": "3",
            "name": "Activision Inc.",
            "operation": "I"

        }
          ]


}

-- {
    "status": "200",
    "description": "catalogBrand",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Canales por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
   "companyId":"napse",
   "catalog":"catalogChannel", 
   "params": [],
    "items": [
        {
            "code": "1",
            "name": "Channel1",
            "operation": "I"

        },
        {
            "code": "2",
            "name": "Channel2",
            "operation": "I"

        },
        {
            "code": "3",
            "name": "Channel3",
            "operation": "I"

        }
          ]


}

-- {
    "status": "200",
    "description": "catalogChannel",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la carga de los catálogos de País, Provincia y Ciudad, deberá respetarse un orden en la carga de estos tres catálogos ya que hay una dependencia entre ellos.

Primero deberá procesarse el catálogo de país (catalogCountry.catalog), después provincia/estado (catalogState.catalog), y al final ciudad (catalogCity.catalog).

Para la importación de País por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
    "companyId": "napse",
    "catalog": "CatalogCountry",
    "params": [],
    "items": [
        {
            "code": "ar",
            "description": "Argentina",
            "operation": "I"
        },
        {
            "code": "it",
            "description": "Italia",
            "operation": "I"
        },
        {
            "code": "es",
            "description": "España",
            "operation": "I"
        }
    ]
}

-- {
    "status": "200",
    "description": "CatalogCountry",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Provincias por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
    "companyId": "napse",
    "catalog": "CatalogState",
    "params": [],
    "items": [
        {
            "code": "bsas",
            "description": "Buenos Aires",
            "country": "ar",
            "operation": "I"
        },
        {
            "code": "cor",
            "description": "Córdoba",
            "country": "ar",
            "operation": "I"
        }
    ]
}

-- {
    "status": "200",
    "description": "CatalogState",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Ciudades por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
    "companyId": "napse",
    "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"
        }
    ]
}

-- {
    "status": "200",
    "description": "CatalogCity",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Campaña Crediticia por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
    "companyId": "napse",
    "catalog": "catalogCreditCampaignCode",
    "params": [],
    "items": [
        {
            "code": "1",
            "description": "BalckFriday",
            "operation": "I"
        },
        {
            "code": "2",
            "description": "Campaña crediticia 1",
            "operation": "I"
        },
        {
            "code": "3",
            "description": "Campaña crediticia 2",
            "operation": "I"
        }
    ]
}

-- {
    "status": "200",
    "description": "catalogCreditCampaignCode",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Moneda por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
    "companyId": "napse",
    "catalog": "catalogCurrencyCode",
    "params": [],
    "items": [
        {
            "code": "1",
            "description": "Peso Argentino",
            "operation": "I"
        },
        {
            "code": "2",
            "description": "Dólar",
            "operation": "I"
        },
        {
            "code": "3",
            "description": "Euro",
            "operation": "I"
        }
    ]
}

-- {
    "status": "200",
    "description": "catalogCurrencyCode",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Un cliente está conformado por los siguientes datos.

(Datos como gender, identificationType, customerType, addressCountry, addressState, y addressCity, corresponden al código de cada uno de ellos y deberán importarse previamente antes de realizar cualquier operación sobre un cliente. En el caso particular de addressCountry, addressState, y addressCity, deberán importarse en ese orden debido a que se validará que una provincia/estado esté dentro de un país, y que una ciudad esté dentro de una provincia.).

A partir de la versión 7.3.0 se agregaron tres atributos al elemento Cliente:

Cumpleaños
Años
Datos Incompletos

Campo	Tipo de dato	Observaciones
*code*	string	Corresponde al código que se le asignara al cliente en Promo. (requerido)
*name*	string	Nombre de cliente. (requerido)
*lastName*	string	Apellido del cliente. (requerido)
*gender*	string	Genero del cliente (en caso de "Validar catálogos relacionados al catálogo de clientes" este en "true", el dato definido en este campo deberá coincidir con alguno de los códigos de género "catalogGender" previamente cargados.) Opcional
*birthDate*	string	Fecha de nacimiento del cliente. Formato: año-mes-día siendo el año de cuatro dígitos, y el mes y el día de dos dígitos
*identificationType*	string	Tipo de identificación del cliente. (en caso de "Validar catálogos relacionados al catálogo de clientes" este en "true", el dato definido en este campo deberá coincidir con alguno de los códigos de tipo de identificación "catalogIdType" previamente cargados.). Opcional
*identifier*	string	Numero de identificación del cliente. (requerido)
*identificationExpiration*	string	Fecha de expiración de la identificación del cliente. Opcional
*nacionality*	string	Nacionalidad del cliente. Opcional
*email*	string	e-Mail del cliente. Opcional
*customerType*	string	Tipo de cliente (requerido) / / (en caso de "Validar catálogos relacionados al catálogo de clientes" este en "true", el dato definido en este campo deberá coincidir con alguno de los códigos de tipo cliente "catalogIdType" previamente cargados.). Opcional
*address*	string	Dirección del cliente. Opcional
*addressCountry*	string	País del cliente. (en caso de "Validar catálogos relacionados al catálogo de clientes" este en "true", el dato definido en este campo deberá coincidir con alguno de los códigos de Pais "catalogCoutry" previamente cargados.). Opcional
*addressState*	string	Provincia de residencia del cliente. (en caso de "Validar catálogos relacionados al catálogo de clientes" este en "true", el dato definido en este campo deberá coincidir con alguno de los códigos de Provincia "catalogState" previamente cargados.). Opcional
*addressCity*	string	Ciudad de residencia del cliente. (en caso de "Validar catálogos relacionados al catálogo de clientes" este en "true", el dato definido en este campo deberá coincidir con alguno de los códigos de Ciudad "catalogCity" previamente cargados.). Opcional
*addressPostalCode*	string	Código Postal. Opcional
*phone*	string	Teléfono. Opcional
*isActive*	booleano	Indicara si al momento del alta el cliente estará Activo o Inactivo. Deberá definirse como true o false. Opcional
*segments*	string	Segmento/s asociado al cliente. Opcional
*birthday*	booleano	Indicará si al momento del alta del cliente es su cumpleaños. Deberá definirse como true o false. Opcional
*Age*	integer	Indicará la edad del cliente. Acepta valores nulos o cero. Opcional
*incompleteData*	booleano	Indicará si el cliente tiene datos incompletos. Deberá definirse como true o false. Opcional

-- {"companyId":"napse",
"catalog":"CatalogCustomer",
"params":[],
"items":[{
    "operation":"I",
    "name":"Manuel Jose",
    "lastName":"Mendoza",
    "code":"95540610",
    "identifier":"95540610",
    "addressCountry":"arg",
    "identificationExpiration":"2050-01-01",
    "address":"diagonal 12 2233",
    "gender":"h",
    "identificationType":"le",
    "addressState":"bsas",
    "isActive":"true",
    "birthDate":"2001-01-01",
    "segments":"SEG1,SEG2",
    "addressPostalCode":"",
    "customerType":"STANDARD",
    "phone":"",
    "nacionality":"argentino",
    "email":"",
    "addressCity":"tig",
    "birthday":true,
    "age": 36,
    "incompleteData":false
}
]
}

Si los atributos del elemento cliente: cumpleaños y datos incompletos tienen valor null; se importarán como false.

Cuando desde la consola se indique que deben de Validar catálogos relacionados al catálogo de clientes, será requerida la carga de los catálogos relacionados previo a la carga del catalogo de cliente.

Se importan entonces las entidades relacionadas previo a la importación de los clientes.

Catálogo IDTYPE. Este catálogo define los tipos de documento o identificación válidos.

-- {
    "companyId": "napse",
    "catalog": "CatalogIdType",
    "params": [],
    "items": [
        {
            "code": "dni",
            "description": "Documento de identidad",
            "operation": "I"
        },
        {
            "code": "le",
            "description": "Libreta de enrolamiento",
            "operation": "I"
        }
    ]
}

Catálogo GENDER. Este catálogo define los tipos de género válidos.

-- {
    "companyId": "napse",
    "catalog": "CatalogGender",
    "params": [],
    "items": [
        {
            "code": "M",
            "description": "Male",
            "operation": "I"
        },
        {
            "code": "F",
            "description": "Female",
            "operation": "I"
        }
    ]
}

Catálogo CUSTOMERTYPE. Este catálogo define los tipos de clientes válidos

-- {
    "companyId": "{{COMPANYID}}",
    "catalog": "CatalogCustomerType",
    "params": [],
    "items": [
        {
            "code": "vip",
            "description": "Cliente vip",
            "operation": "I"
        },
        {
            "code": "gold",
            "description": "Cliente gold",
            "operation": "I"
        },
        {
            "code": "silver",
            "description": "Cliente silver",
            "operation": "I"
        }
    ]
}

Importación de nuevos clientes.

Una vez realizadas las importaciones anteriores, y considerando sus códigos, se pueden realizar altas, modificaciones, y eliminaciones de clientes.

Ejemplo: Se dan de alta dos clientes:

-- {
    "companyId": "{{COMPANYID}}",
    "catalog": "CatalogCustomer",
    "params": [],
    "items": [
        {
            "code": "cod1",
            "name": "Alberto",
            "lastName": "Pérez",
            "gender": "M",
            "birthDate": "1950-01-01",
            "identificationType": "le",
            "identifier": "11112222",
            "identificationExpiration": "2050-01-01",
            "nacionality": "argentino",
            "email": "[email protected]",
            "customerType": "vip",
            "address": "diagonal 12 2233",
            "addressCountry": "ar",
            "addressState": "bsas",
            "addressCity": "tig",
            "addressPostalCode": "2222",
            "phone": "11111111",
            "isActive": "true",
            "birthday":false,
            "age": 73,
            "incompleteData":false,
            "operation": "I"
        },
        {
            "code": "cod2",
            "name": "Ángela",
            "lastName": "Gonzales",
            "gender": "F",
            "birthDate": "1960-01-01",
            "identificationType": "dni",
            "identifier": "99998888",
            "identificationExpiration": "2050-01-01",
            "nacionality": "argentina",
            "email": "[email protected]",
            "customerType": "gold",
            "address": "diagonal 50 2211",
            "addressCountry": "ar",
            "addressState": "cor",
            "addressCity": "lm",
            "addressPostalCode": "5050",
            "phone": "55555555",
            "isActive": "true",
            "birthday":false,
            "age": 63,
            "incompleteData":"",
            "operation": "I"
        }
    ]
}

Cuando se agrega un atributo de elemento a un cliente; éste se debe agregar en el Json al importar el catálogo de cliente.

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2022-12-30_16-22-49.png

-- {
    "companyId": "2",
    "catalog": "catalogCustomer",
    "params": [],
    "items": [{
        "operation": "I",
                "code":"8",
                "name":"John",
                "lastName":"Promo",
                "gender":"h",
                "birthDate":"03-05-1959",
                "identificationType":"dni",
                "identifier":"4688779900",
                "identificationExpiration":"31-12-2030",
                "nacionality":"Arg",
                "email":"[email protected]",
                "customerType":"EMPLEADO",
                "address":"Av.Livertad 123",
                "addressCountry":"arg",
                "addressState":"bsas",
                "addressCity":"tig",
                "addressPostalCode":"9999",
                "phone":"457896203",
                "isActive":"true",
                "segments":"4650",
                "birthday":false,
                "age": 64,
                "incompleteData":"",                 
                "condiva":"Responsable Inscripto"
    }]
}

Eliminación y actualización de clientes.

En el siguiente ejemplo, se elimina el primer cliente (campo operation en R) y se actualiza el segundo cliente (campo operation en U) cambiando el email y el teléfono.

-- {
    "companyId": "{{COMPANYID}}",
    "catalog": "CatalogCustomer",
    "params": [],
    "items": [
        {
            "code": "cod1",
            "name": "Alberto",
            "lastName": "Pérez",
            "gender": "M",
            "birthDate": "1950-01-01",
            "identificationType": "le",
            "identifier": "11112222",
            "identificationExpiration": "2050-01-01",
            "nacionality": "argentino",
            "email": "[email protected]",
            "customerType": "vip",
            "address": "diagonal 12 2233",
            "addressCountry": "ar",
            "addressState": "bsas",
            "addressCity": "tig",
            "addressPostalCode": "2222",
            "phone": "11111111",
            "isActive": "true",
            "birthday":"",
            "age": 73,
            "incompleteData":"",             
            "operation": "R"
        },
        {
            "code": "cod2",
            "name": "Ángela",
            "lastName": "Gonzales",
            "gender": "F",
            "birthDate": "1960-01-01",
            "identificationType": "dni",
            "identifier": "99998888",
            "identificationExpiration": "2050-01-01",
            "nacionality": "argentina",
            "email": "[email protected]",
            "customerType": "gold",
            "address": "diagonal 50 2211",
            "addressCountry": "ar",
            "addressState": "cor",
            "addressCity": "lm",
            "addressPostalCode": "5050",
            "phone": "90909090",
            "isActive": "true",
            "birthday":"",
            "age":"",
            "incompleteData":"",             
            "operation": "U"
        }
    ]
}

Para la importación de Departamentos por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
   "companyId":"napse",
   "catalog":"catalogDepartment", 
   "params": [],
    "items": [
        {
            "code": "Elec",
            "name": "Electronics",
            "operation": "I"

        },
        {
            "code": "Pack",
            "name": "Pack",
            "operation": "I"

        },
        {
            "code": "Alma",
            "name": "Almacén",
            "operation": "I"

        }
          ]


}

-- {
    "status": "200",
    "description": "catalogDepartment",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Catálogo de Evento por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
   "companyId":"napse",
   "catalog":"catalogEventTransaction", 
   "params": [],
    "items": [
        {
            "code": "50",
            "name": "Evento 1",
            "operation": "I"

        },
        {
            "code": "51",
            "name": "Evento 2",
            "operation": "I"

        },
        {
            "code": "52",
            "name": "Evento 3",
            "operation": "I"

        }
          ]


}

-- {
    "status": "200",
    "description": "catalogEventTransaction",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Tipos de Transacción por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
   "companyId":"napse",
   "catalog":"catalogEventTransactionType", 
   "params": [],
    "items": [
        {
            "code": "BIG",
            "name": "BIG TICKET",
            "operation": "I"

        },
        {
            "code": "VEM",
            "name": "VENTA EMPLEADO",
            "operation": "I"

        },
        {
            "code": "REG",
            "name": "MESA DE REGALOS",
            "operation": "I"

        }
          ]


}

-- {
    "status": "200",
    "description": "catalogEventTransactionType",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Familia por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
   "companyId":"napse",
   "catalog":"catalogFamily", 
   "params": [],
    "items": [
        {
            "code": "Prin",
            "name": "Printers",
            "operation": "I"

        },
        {
            "code": "Lapt",
            "name": "Laptops",
            "operation": "I"

        },
        {
            "code": "DVDP",
            "name": "DVD Players",
            "operation": "I"

        }
          ]


}

-- {
    "status": "200",
    "description": "catalogFamily",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Categoría por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
   "companyId":"napse",
   "catalog":"catalogCategory", 
   "params": [],
    "items": [
        {
            "code": "PS3G",
            "name": "PS3 Videogames",
            "familyCode": "VGCo",
            "operation": "I"

        },
        {
            "code": "AlmaCar",
            "name": "Caramelos",
            "familyCode": "AlmaDu",
            "operation": "I"

        },
        {
            "codeType": "AlmaCon",
            "name": "Confites",
            "familyCode": "AlmaDu",
            "operation": "I"

        }
          ]


}

-- {
    "status": "200",
    "description": "catalogCategory",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Subcategoría por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
   "companyId":"napse",
   "catalog":"catalogSubCategory", 
   "params": [],
    "items": [
        {
            "code": "AlmaDes",
            "name": "Descafeinado",
            "categoryCode": "AlmaCaf",
            "operation": "I"

        },
        {
            "code": "AlmaIns",
            "name": "Instantaneo",
            "categoryCode": "AlmaCaf",
            "operation": "I"

        },
        {
            "code": "AlmaCap",
            "name": "En cápsulas",
            "categoryCode": "AlmaCaf",
            "operation": "I"

        }
          ]


}

-- {
    "status": "200",
    "description": "catalogSubCategory",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Formato por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
   "companyId":"napse",
   "catalog":"catalogFormat", 
   "params": [],
    "items": [
        {
            "code": "111",
            "name": "Formato A",
            "operation": "I"

        },
        {
            "code": "112",
            "name": "Formato B",
            "operation": "I"

        },
        {
            "code": "113",
            "name": "Formato C",
            "operation": "I"

        }
          ]


}

-- {
    "status": "200",
    "description": "catalogFormat",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Ítem por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
   "companyId":"napse",
   "catalog":"catalogItem", 
   "params": [],
    "items": [
        {
            "code": "111",
            "name": "PlayStation 4",
            "unitprice": 1000,
            "level1": "Gen",
            "level2": "Cat11",
            "level3": "SubCat11",
            "level4": "1",
            "supplier": "1",
            "brand": "Consola Sony Play Station 4 Ps4 1206 500 Gb",
            "detail": "Modelo: Playstation 4 1206&nbsp",
            "detail2": "Incluye cable de alimentaci&oacute",
            "operation": "I"

        },
        {
            "code": "112",
            "name": "XBOX One",
            "unitprice": "9900",
            "level1": "Gen",
            "level2": "Cat11,
            "level3": "SubCat12",
            "level4": "1",
            "supplier": "1",
            "brand": "Xbox One X 1tb, 4k", 
            "detail": "XBOX One X cuenta con reproductor 4K HDR, y te permite grabar y transmitir tus partidas en 4K 60 FPS a través de Mixer",
            "detail2": "Disfruta de tus películas favoritas gracias al reproductor Blu-ray 4K Ultra HD o disfruta de apps como NetFlix.",
            "operation": "I"

        },
        {
            "code": "113",
            "name": "Nintendo Switch",
            "unitprice": "13300",
            "level1": "Gen",
            "level2": "Cat11",
            "level3": "SubCat13",
            "level4": "1",
            "supplier": "1",
            "brand": "Consola Nintendo Switch 32gb Neon",      
            "detail": "La consola Nintendo Switch está diseñada para acompañarte dondequiera que vayas, transformándose de consola para el hogar a consola portátil en un instante.",
            "detail2": "Memoria Interna 32GB de memoria NAND",
            "operation": "I"

        }
          ]


}

-- {
    "status": "200",
    "description": "catalogItem",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Stock por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
   "companyId":"napse",
   "catalog":"catalogItemStock", 
   "params": [],
    "items": [
        {
            "store": "Tienda1",
            "code": "111",
            "stock": "500.00",
            "operation": "I"

        },
        {
            "store": "Tienda1",
            "code": "112",
            "stock": "700.00",
            "operation": "I"

        },
        {
           "store": "Tienda1",
           "code": "113",
            "stock": "100.00",
            "operation": "I"

        }
          ]


}

-- {
    "status": "200",
    "description": "catalogItemStock",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Bancos por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
   "companyId":"napse",
   "catalog":"catalogPaymentBank", 
   "params": [],
    "items": [
        {
            "code": "BAN",
            "name": "BANAMEX",
            "operation": "I"

        },
        {
            "code": "SAN",
            "name": "SANTANDER",
            "operation": "I"

        },
        {
            "code": "BCO",
            "name": "BANCOMER",
            "operation": "I"

        }
          ]


}

-- {
    "status": "200",
    "description": "catalogPaymentBank",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Tipos de Pago por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
   "companyId":"napse",
   "catalog":"CatalogPaymentCode", 
   "params": [],
    "items": [
        {
            "codeType": "11",
            "name": "Mercado Pago",
            "code": "MP",
            "operation": "I"

        },
        {
            "codeType": "12",
            "name": "AMERICAN EXPRESS",
            "code": "AMEX",
            "operation": "I"

        },
        {
            "codeType": "13",
            "name": "BANAMEX",
            "code": "BANAMEX",
            "operation": "I"

        }
          ]


}

-- {
    "status": "200",
    "description": "CatalogPaymentCode",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Prefijo por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
    "companyId": "napse",
    "catalog": "catalogPaymentPrefix",
    "params": [],
    "items": [
        {
            "code": "10",
            "name": "Pref A",
            "operation": "I"
        },
        {             
            "code": "11",
            "name": "Pref B",
            "operation": "I"         
        },
        {            
            "code": "12",
            "name": "Pref C",
            "operation": "I"         }
    ]
}

-- {
    "status": "200",
    "description": "catalogPaymentPrefix",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Tipo de Pago por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
    "companyId": "napse",
    "catalog": "catalogPaymentType",
    "params": [],
    "items": [
        {
            "code": "EVO",
            "name": "EFECTIVO",
            "operation": "I"
        },
        {             
            "code": "TAR",
            "name": "TARJETA DE CREDITO",
            "operation": "I"         
        },
        {            
            "code": "CHE",
            "name": "CHEQUE",
            "operation": "I"         }
    ]
}

-- {
    "status": "200",
    "description": "catalogPaymentType",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Bolsillo por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
    "companyId": "napse",
    "catalog": "catalogPocket",
    "params": [],
    "items": [
        {
            "code": "1",
            "name": "bolsilloa",
            "operation": "I"
        },
        {             
            "code": "2",
            "name": "bolsillob",
            "operation": "I"         
        },
        {            
            "code": "3",
            "name": "bolsillo3",
            "operation": "I"         }
    ]
}

-- {
    "status": "200",
    "description": "catalogPocket",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Perfil del Cliente por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
    "companyId": "napse",
    "catalog": "catalogProfileCode",
    "params": [],
    "items": [
        {
            "code": "1",
            "name": "Perfil 1",
            "operation": "I"
        },
        {             
            "code": "2",
            "name": "Perfil 2",
            "operation": "I"         
        },
        {            
            "code": "3",
            "name": "Perfil 3",
            "operation": "I"         
        }
    ]
}

-- {
    "status": "200",
    "description": "catalogProfileCode",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Cadena por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
    "companyId": "napse",
    "catalog": "catalogStoreChain",
    "params": [],
    "items": [
        {
            "code": "10",
            "name": "Cadena 1",
            "operation": "I"
        },
        {             
            "code": "12",
            "name": "Cadena 2",
            "operation": "I"         
        },
        {            
            "code": "13",
            "name": "Cadena 3",
            "operation": "I"         
        }
    ]
}

-- {
    "status": "200",
    "description": "catalogStoreChain",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Proveedor por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
    "companyId": "napse",
    "catalog": "catalogSupplier",
    "params": [],
    "items": [
        {
            "code": "PR1",
            "name": "SONY",
            "operation": "I"
        },
        {             
            "code": "PR2",
            "name": "APPLE",
            "operation": "I"         
        },
        {            
            "code": "PR3",
            "name": "LACTEOS PREMIUM",
            "operation": "I"         
        }
    ]
}

-- {
    "status": "200",
    "description": "catalogSupplier",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Zona por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
    "companyId": "napse",
    "catalog": "catalogZone",
    "params": [],
    "items": [
        {
            "code": "10",
            "name": "Zona 1",
            "operation": "I"
        },
        {             
            "code": "11",
            "name": "Zona 2",
            "operation": "I"         
        },
        {            
            "code": "12",
            "name": "Zona 3",
            "operation": "I"         
        }
    ]
}

-- {
    "status": "200",
    "description": "catalogZone",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Sub Zona por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
    "companyId": "napse",
    "catalog": "catalogSubZone",
    "params": [],
    "items": [
        {
            "code": "10",
            "name": "Sub Zona 1",
            "operation": "I"
        },
        {             
            "code": "11",
            "name": "Sub Zona 2",
            "operation": "I"         
        },
        {            
            "code": "12",
            "name": "Sub Zona 3",
            "operation": "I"         
        }
    ]
}

-- {
    "status": "200",
    "description": "catalogSubZone",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Canje de Puntos por Catálogos por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
    "companyId": "napse",
    "catalog": "catalogRedeemBenefit",
    "params": [],
    "items": [
        {
            "store": "b320"
            "code": "1000",
            "points": "100",
            "discountValue": "10"
            "discountType": "perc"
            "operation": "I"
        },
        {            
            "store": "b320"
            "code": "2000",
            "points": "60",
            "discountValue": "27"
            "discountType": "fix"
            "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."
    }
}

Para la importación de Código de Producto por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
    "companyId": "napse",
    "catalog": "CatalogProductCode",
    "params": [],
    "items": [
        {
            "code": "1",
            "name": "Lapicera",
            "operation": "I"
        },
        {             
            "code": "2",
            "name": "Lápiz",
            "operation": "I"         
        },
        {            
            "code": "3",
            "name": "Goma",
            "operation": "I"         
        }
    ]
}

-- {
    "status": "200",
    "description": "CatalogProductCode",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Código de Barras de Producto por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
    "companyId": "napse",
    "catalog": "CatalogProductBarcode",
    "params": [],
    "items": [
        {
            "code": "1000177",
            "name": "Yerba",
            "operation": "I"
        },
        {             
            "code": "1000178",
            "name": "Azúcar",
            "operation": "I"         
        },
        {            
            "code": "1000179",
            "name": "Café",
            "operation": "I"         
        }
    ]
}

-- {
    "status": "200",
    "description": "CatalogProductBarcode",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Para la importación de Balance por medio del servicio REST, deberá considerarse el siguiente formato general:

-- {
    "companyId": "napse",
    "catalog": "CatalogBalance",
    "params": [],
    "items": [
        {
            "code": "1",
            "descripcion": "Balance 1",
            "operation": "I"
        }
       
    ]
}

-- {
    "status": "200",
    "description": "CatalogBalance",
    "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 Borrado de atributos en catálogos en PROMO

La aplicación permite borrar de ciertos catálogos, algunos atributos con solo enviar el id de dicho atributo que se le envíe en el post, utilizando el servicio Rest.

No es necesario enviar el id y la descripción. Con enviar sólo el código se puede realizar el borrado.

Los catálogos que cumplen con este criterio son:

Catálogos dinámicos

"CatalogAdditionalField00"
"CatalogAdditionalField01"
"CatalogAdditionalField02"
"CatalogAdditionalField03"
"CatalogAdditionalField04"
"CatalogAdditionalField05"
"CatalogAdditionalField06"
"CatalogAdditionalField07"
"CatalogAdditionalField08"
"CatalogAdditionalField09"
"CatalogAdditionalField10"
"CatalogAdditionalField11"
"CatalogAdditionalField12"
"CatalogAdditionalField13"
"CatalogAdditionalField14"
"CatalogAdditionalField15"
"CatalogAdditionalField16"
"CatalogAdditionalField17"
"CatalogAdditionalField18"
"CatalogAdditionalField19"
"CatalogBrand"
"CatalogChannel"
"CatalogCreditCampaignCode"
"CatalogCurrencyCode"
"CatalogCustomerType"
"CatalogDepartment"
"CatalogEventTransaction"
"CatalogEventTransactionType"
"CatalogFamily"
"CatalogFormat"
"CatalogPaymentBank"
"CatalogPaymentCode"
"CatalogPaymentPrefix"
"CatalogItem"
"CatalogSubCategory"
"CatalogPaymentType"
"CatalogPocket"
"CatalogProductBarcode"
"CatalogProductCode"
"CatalogCustomer"
"CatalogProfileCode"
"CatalogStoreChain"
"CatalogSubZone"
"CatalogSupplier"
"CatalogZone"
"CatalogGender"
"CatalogIdType"
"CatalogContractPriceList"
"CatalogCountry"
"CatalogCategory"

De los anteriores, estos catálogos no admiten repetición de registros:

"CatalogGender"
"CatalogIdType"
"CatalogContractPriceList"
"CatalogCountry"
"CatalogCustomerType"
"CatalogItem"
"CatalogCustomer"

Y estos catálogos no son código-nombre pero igualmente cumplirán con el requerimiento porque su clave primaria incluye sólamente companyId y code

"CatalogItem"
"CatalogCustomer"
"CatalogSubCategory"
"CatalogCategory"

Estos catálogos no fueron afectados:

"Card"
"CatalogCity"
"CatalogState"
"CatalogInfoFinancial"
"CatalogItemStock" (si bien tiene clave primaria companyId-code, no tiene un campo name)
"CatalogExtendWarranty" (idem anterior)
"CatalogRedeemBenefit"

Se pueden presentar los siguientes casos:

La Url es:

-- http://{{SERVER}}:{{PORT}}/promo/api/rest/catalogs --

Casos de Uso:

Se envía sólo el código del producto:

-- {
    "companyId" = "napse",
    "catalog" = "CatalogChannel",
    "params":[],
    "items": [
        {
            "code"= "1",
            "operacion" = "D"

        }

    ]
    

}

Se envía sólo el código y nombre del producto:

-- {
    "companyId" = "napse",
    "catalog" = "CatalogChannel",
    "params":[],
    "items": [
        {
            "code"= "1",
            "name"= "CATALOGCHANNEL2",
            "operacion" = "D"

        }

    ]
    

}

Servicio De Eliminación de Datos del Cliente y sus datos de fidelidad

Este servicio rest permite eliminar al cliente y todos los datos de fidelidad relacionados con este si se desea.

Campo	Valor
companyId	Id de la compañía (requerido)
params	para dejarlo extensible, es una lista vacía
code	Código del cliente (requerido)
operation	D: es borrado parcial asignará rayita ( - ) en los datos del cliente (excepto el código, que se seguirá mostrando) o R: borrado total incluye fidelidad y borra también el código del cliente. Requerido

Datos para el request

Método

Url base

DELETE

-- http://URLPROMO:PUERTO/promo/api/rest/customer/delete

Por ej. http://promo.com:8080/promo/api/rest/customer/delete

Servicio rest para eliminar total o parcialmente al cliente y si se desea sus datos de fidelidad:

 -- {
    "companyId": "<companyId>",
    "params": [],
    "items": [
                {
            "code": "<codigoCliente1>",
            "operation": "D"
        }
    ]
}

Se puede enviar varios clientes por vez.

-- {
    "status": "200",
    "description": "Cliente (s) Eliminado (s)",
	"detail": [
                {
            "result": "ok",
            "detail": "Cliente (s) Eliminado (s)"
        }
    ]
}

Ejemplo:

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2021-10-19_12-4-33.png

Ejemplo:

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2022-7-19_11-57-53.png

Se observará que en la consola se ha eliminado el primer registro que encontró con los datos solicitados:

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2022-7-19_11-58-40.png

Servicio De Importación Masiva de Promociones vía REST

Este servicio permite realizar la importación de promociones en forma masiva a través de REST a la consola de PROMO.

El esquema de autenticación es el mismo que en los demás servicios REST presentados aquí (ver mas arriba).

Una vez obtenido el token de acceso, el servicio puede ser invocado utilizando el método POST, desde la URL:<promo>/api/rest/import

Datos para el request:

Método

Url base

POST

-- http://URLPROMO:PUERTO/promo/api/rest/promotion/import

Por ej. – http://promo.com:8080/promo/api/rest/promotion/import

Es importante que al momento de importar, se definan plantillas específicas, esto facilitará mucho la tarea del armado del servicio.

Ejemplo: si vamos a importar descuentos por porcentaje, lo mas importante es definir la plantilla en JSON.

El armado de la plantilla es un proceso que debe realizar una persona con conocimiento de la plataforma.

Las promociones deben estar en estado Completa para poder importarlas a través de este servicio. Promo limita a 3000 la cantidad de condiciones simples que se puden agregar por promoción.

Un ejemplo de creación, inactivación o actualización de un conjunto de promociones, es el siguiente:

-- {
"companyId": "napse",
"promotions": [
{
    "operation": "I",
    "name": "promo import10",
    "code": "promo import10",
    "promotionType": "tipo 1",
    "promotionSubType": "tipo 1",
    "promotionApplicationForm": "tipo 1",
    "reportParticipants": "false",
    "suggest": "not",
    "sets": {
      "set": {
        "name": "631642d4cfaa7738300ff981",
        "type": "item"
      }
    },
    "condition": {
      "type": "basic",
      "name": "Exists",
      "parameter": {
        "key": "use-set",
        "value": "631642d4cfaa7738300ff981"
      }
    },
    "benefits": {
      "benefit": {
        "instance": "PercentageDiscount",
        "parameter": [
          {
            "key": "displayMessage",
            "value": "promo import"
          },
          {
            "key": "printerMessage",
            "value": "promo import"
          },
          {
            "key": "TLOGMessage",
            "value": "promo import"
          },
          {
            "key": "applicationMethod",
            "value": "resume"
          },
          {
            "key": "prorationMethod",
            "value": "proportional"
          },
          {
            "key": "applicationPriceType",
            "value": "benefited-price"
          },
          {
            "key": "name",
            "value": "631642c3cfaa7738300ff97e"
          },
          {
            "key": "percent",
            "value": "10"
          },
          {
            "key": "unit",
            "value": "qty"
          },
          {
            "key": "prorateBCP",
            "value": "false"
          },
          {
            "key": "recoveryValue",
            "value": "0"
          },
          {
            "key": "recoveryType",
            "value": ""
          }
        ],
        "applied-elements": {
          "use-set": {"name": "631642d4cfaa7738300ff981"}
        }
      }
    }
    }
]
}

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.

Napse > PROMO 7.8 - Manual de Integración - Servicios > image-2022-05-05-15-10-17-795.png

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: Productos de marca X Productos de familia "Y" Medio de pago "VISA"
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 FixedDiscount : Descuento fijo PercentageDiscount : Descuento porcentaje LoyaltyBenefit : Puntos de fidelización FactorLoyaltyBenefit : Coeficiente de fidelización CouponBenefit : Cupón PaymentPlanBenefit : Plan de pagos GiftBenefit : Regalo GeneralBenefit : Beneficio General PercentLoyaltyBenefit : Porcentaje de fidelización BankRefundBenefit : Reintegro bancario ExternalBenefit : Beneficio Externo RedeemWithOptionsBenefit : Canje con Opciones CatalogRedeemBenefit : Canje de Puntos por Catalogo CalculatedCouponApplicationBenefit : Aplicacion de Cupón Calculado CalculatedCouponBenefit : Cupón Calculado RedeemPointsBenefit : Redención de Puntos ContractPercentageDiscount : Descuento por convenio

Respuestas del servicio

Si la solicitud ha sido exitosa, se podrá visualizar la siguiente respuesta:

-- {
    "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:

-- {
    "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:

1. Nombre de la Promoción

-- {
   
"companyId": "1",
"promotions": [
{
    "operations": "R",
    "name": "Promo4"
}
]
}

La respuesta sará:

-- {
    "status": "Información Recibida OK",
    "description": "La importación de promociones será procesada"
}

2. Código de la Promoción

-- {
    "companyId": "1",
    "promotions":[
    {
        "operation": "R",
        "code": "Promo1"
    } 
    ]
}

La respuesta será:

-- {
    "status": "Información Recibida OK",
    "description": "La importación de promociones será procesada"
}

3. Código y Nombre de la Promoción

-- {
    "companyId": "1",
    "promotions":[
    {
        "operation": "R",
        "code":"Promo7",
        "name":"Promo7"
    } 
    ]
}

La respuesta será:

-- {
    "status": "Información Recibida OK",
    "description": "La importación de promociones será procesada"
}

Ejemplo 1: Se invoca el servicio de importación masiva de promociones 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/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"
}

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:

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2022-5-19_17-19-17.png

-- <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>

Luego, ir al sitio web https://www.oxygenxml.com/xml_json_converter.html, para convertir el xml a formato json.

Pegar el xml dentro del campo XML y generar el Json presionando el botón con la ->

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2022-5-19_17-21-47.png

Esto generará el siguiente resultado, del cual solo se deberá copiar lo que está dentro de "promotion" tal como se muestra en el siguiente ejemplo:

-- {

  "promotion": {

    "nro": "62867033c9512b0184381178",

    "name": "Promos con limites 1",

    "code": "30",

    "className": "com.synthesis.promo.engine.promotion.ModularPromotion",

    "reportParticipants": "false",

    "suggest": "not",

    "sets": {

      "set": {

        "name": "62867340c9512b01843811b5",

        "type": "item",

        "attribute": "code",

        "comparator": "Into",

        "value": "111"

      }

    },

    "condition": {

      "type": "composite",

      "name": "And",

      "condition": [

        {

          "type": "basic",

          "name": "Exists",

          "parameter": {

            "key": "use-set",

            "value": "62867340c9512b01843811b5"

          }

        },

        {

          "type": "basic",

          "name": "Header",

          "parameter": [

            {

              "key": "attribute",

              "value": "store"

            },

            {

              "key": "value",

              "value": "napse,napse2"

            }

          ]

        }

      ]

    },

    "benefits": {

      "benefit": {

        "instance": "FixedDiscount",

        "nro": "628670c9c9512b018438117f",

        "parameter": [

          {

            "key": "displayMessage",

            "value": "Promos con limites 1"

          },

          {

            "key": "printerMessage",

            "value": "Promos con limites 1"

          },

          {

            "key": "TLOGMessage",

            "value": "Promos con limites 1"

          },

          {

            "key": "applicationMethod",

            "value": "resume"

          },

          {

            "key": "prorationMethod",

            "value": "proportional"

          },

          {

            "key": "applicationPriceType",

            "value": "benefited-price"

          },

          {

            "key": "hasLimit",

            "value": "true"

          },

          {

            "key": "name",

            "value": "62867033c9512b0184381178"

          },

          {

            "key": "amount",

            "value": "300"

          },

          {

            "key": "unit",

            "value": "qty"

          },

          {

            "key": "prorateBCP",

            "value": "false"

          },

          {

            "key": "recoveryValue",

            "value": "0"

          },

          {

            "key": "recoveryType",

            "value": ""

          }

        ],

        "applied-elements": {

          "use-set": {"name": "62867340c9512b01843811b5"}

        }

      }

    }

  }

}

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.

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2022-5-19_19-7-30.png

Esto da el siguiente resultado con el formato de importación ya completo y listo para usar desde POSTMAN:

-- {

  "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"}

          }

        }

      }

    }

  ]

}

Importación del json desde POSTMAN:

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2022-5-19_19-9-47.png

Al importar una promoción, la misma se importará con el workflow general por default.

Tipo, subtipo y Forma de Aplicación

Promo admite tanto por servicio Rest como por importación de promociones en xml, importar promociones con tipo, subtipo y forma de aplicación.

Json de ejemplo:

-- {
	"companyId": "napse",
	"promotions": [{
		"operation": "I",
		"name": "Promo Import4",
		"code": "Promo Import4",
		"promotionType": "tipo 1",
		"promotionSubType": "tipo 1",
		"promotionApplicationForm": "tipo 1",
		"reportParticipants": "false",
		"suggest": "not",
		"sets": {
			"set": {
				"name": "6324b5f8be13d734e87ccc14",
				"type": "item"
			}
		},
		"condition": {
			"type": "basic",
			"name": "Exists",
			"parameter": {
				"key": "use-set",
				"value": "6324b5f8be13d734e87ccc14"
			}
		},
		"benefits": {
			"benefit": {
				"instance": "PercentageDiscount",
				"parameter": [{
						"key": "displayMessage",
						"value": "promo import"
					},
					{
						"key": "printerMessage",
						"value": "promo import"
					},
					{
						"key": "TLOGMessage",
						"value": "promo import"
					},
					{
						"key": "applicationMethod",
						"value": "resume"
					},
					{
						"key": "prorationMethod",
						"value": "proportional"
					},
					{
						"key": "applicationPriceType",
						"value": "benefited-price"
					},
					{
						"key": "name",
						"value": "6324b5a1be13d734e87ccc0e"
					},
					{
						"key": "percent",
						"value": "10"
					},
					{
						"key": "unit",
						"value": "qty"
					},
					{
						"key": "prorateBCP",
						"value": "false"
					},
					{
						"key": "recoveryValue",
						"value": "0"
					},
					{
						"key": "recoveryType",
						"value": ""
					}
				],
				"applied-elements": {
					"use-set": {
						"name": "6324b5f8be13d734e87ccc14 "
					}
				}
			}
		}
	}]
}

Desde el servicio Rest:

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_12-34-46.png

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_12-35-15.png

Request:

-- {
    "status":"Informacion recibida OK",
    "description":"La importacion de Promociones será procesada"
 
}

Servicio De importación de promociones con los atributos de cabecera deshabilitados

Es posible insertar promociones, cuando se deshabiliten e inactiven los atributos de cabecera, en la consola (Módulo de Administración/Atributos de cabecera)

JSON de ejemplo:

-- {
    "companyId": "napse",
    "promotions": [
        {
    "nro": "",
    "name": "promoIT1",
    "code": "",
    "className": "com.synthesis.promo.engine.promotion.ModularPromotion",
    "reportParticipants": "false",
    "suggest": "not",
    "sets": {
      "set": {
        "name": "627b93e926a51910c877b0e5",
        "type": "item",
        "attribute": "code",
        "comparator": "Into",
        "value": "1234"
      }
    },
    "combo": {
      "combo-component": {
        "min": "1",
        "max": "4",
        "attribute": "qty",
        "use-set": "627b93e926a51910c877b0e9"
      }
    },
    "benefits": {
      "benefit": {
        "instance": "FixedDiscount",
        "nro": "627b953326a51910c877b0f1",
        "parameter": [
          {
            "key": "displayMessage",
            "value": "Bug305863-Limite_71-47440-47573"
          },
          {
            "key": "printerMessage",
            "value": "Bug305863-Limite_71-47440-47573"
          },
          {
            "key": "TLOGMessage",
            "value": "Bug305863-Limite_71-47440-47573"
          },
          {
            "key": "applicationMethod",
            "value": "lineByLine"
          },
          {
            "key": "prorationMethod",
            "value": "proportional"
          },
          {
            "key": "applicationPriceType",
            "value": "original-price"
          },
          {
            "key": "hasLimit",
            "value": "true"
          },
          {
            "key": "name",
            "value": "627b939926a51910c877b0e4"
          },
          {
            "key": "amount",
            "value": "1000"
          },
          {
            "key": "unit",
            "value": "qty"
          },
          {
            "key": "recoveryValue",
            "value": "100"
          },
          {
            "key": "recoveryType",
            "value": "p"
          },
          {
            "key": "margengasto",
            "value": "1"
          },
          {
            "key": "prorateBCP",
            "value": "false"
          }
        ],
        "applied-elements": {
          "use-set": {"name": "627b93e926a51910c877b0e9"}
        },
        "staggered": {
          "unit": "qty",
          "staggeredStep": [
            {
              "nro": "627b947426a51910c877b0ed",
              "min": "1",
              "max": "1",
              "applyValue": "50000"
            },
            {
              "nro": "627b949c26a51910c877b0f0",
              "min": "4",
              "max": "4",
              "applyValue": "1000"
            }
          ]
        }
      }
    },
    "operation":"I"
  }

 



    ]
}

Desde Postman:

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_12-36-4.png

Napse > PROMO 7.8 - Manual de Integración - Servicios > image2023-2-9_12-36-25.png

Servicio De Exclusión de Fechas para no ser ejecutada una promoción

Servicio que permite tener la posibilidad de configurar una exclusión de fechas determinadas durante todo el período de vigencia para NO ser ejecutada una promoción por sucursal.

Esta opción va a permitir controlar que en determinadas fechas(que son días especiales) no se aplique las promociones que tienen productos que participan en estos días.

Este método accesible desde api/rest/catalogs es el encargado de devolver en formato JSON las fechas en que deben excluirse las promociones y en las tiendas informadas solicitado por medio de la acción POST. (http://{{SERVER}}:{{PORT}}/promo/api/rest/catalogs)

Ejemplo:

-- http://localhost:8073/promo/api/rest/catalogs

El formato para el servicio será:

Campo	Ejemplos	Tipo de dato	Detalle
companyId	napse	Alfanumérico	Código de la compañía - Requerido
catalog	CatalogExclusionDates	string	Catálogo de Fechas de Exclusión - Requerido
params	[ ]	Listado	Parámetros adicionales - Requerido
storeCode	napse	Alfanumérico	Código de la tienda - Requerido
promotionNames	Promo test	Alfanumérico	Nombre de la promoción que será excluida para la tienda y fecha indicada. No obligatorio para la operación R, solo en los casos en que se quiera eliminar todas las exclusiones de días específicos, este campo podrá quedar como vacío es decir "", indicando que todas las exclusiones de promociones en las fechas indicadas serán removidas.
exclusionDates	["2022-07-21", "2022-07-22"]	Listado de fechas	Fechas en las que será excluida la promoción, cada fecha deberá seguir el formato de "año-mes-día" - Requerido
operation	I	Alfanumérico	Identifica el tipo de operación a realizar por cada limite a procesar (requerido), dentro de las opciones disponibles están: I → Insertar U → Modificar R → Eliminar

Ejemplo:

-- {
    "companyId": "napse",
    "catalog": "CatalogExclusionDates",
    "params": [],
    "items": [
        {
            "storeCode": "3",
            "promotionName": "Promo Puntos I",
            "exclusionDates": ["2023-07-10","2023-07-11","2023-07-12"],
            "operation": "I" //Tipo de operación asociada a I (insertar), U (actualizar) y R (remover)
        },
		{
            "storeCode": "3",
            "promotionName": "Promo Puntos I",
            "exclusionDates": ["2023-07-13"],
            "operation": "U"
        },
		{
            "storeCode": "3",
            "promotionName": "Promo Puntos I",
            "exclusionDates": ["2023-07-13"],
            "operation": "R"
        }
    ]
}

-- {
    "status": "200",
    "description": "CatalogExclusionDates",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Formato de una exclusión con operación I (insert)

El siguiente json representa el formato para el registro de nuevas exclusiones de promociones por fecha para una tienda y promoción especifica.

Tenga en cuenta que en el campo exclusionDates solo podrá indicar datos de la fecha con el formato "año-mes-día"
Solo se crearan las exclusiones con las fechas que sean validas, es decir que tengan el formato del punto anterior y que no sean menor a la fecha actual.
Si la promoción sobre la cual se procesaran las exclusiones tiene vigencia definida (Fecha inicio y fin), las fechas incluidas en el campo exclusionDates deberá estar dentro del rango de vigencia de la promo, de lo contrario las exclusiones fuera de la vigencia serán ignoradas, creando solo las exclusiones sobre las fechas que estén dentro de la vigencia.

-- {
    "companyId": "napse",
    "catalog": "CatalogExclusionDates",
    "params": [],
    "items": [
        {
            "storeCode": "3",
            "promotionName": "Promo A",
            "exclusionDates": ["2023-07-10","2023-07-11","2023-07-12"],
            "operation": "I"
        }
    ]
}

-- {
    "status": "200",
    "description": "CatalogExclusionDates",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Formato de una exclusión con operación U (update)

El proceso de actualización de la exclusión de promociones por fecha, considera los puntos indicados para la operación I, teniendo solo las siguientes particularidades:

El proceso de actualización incorporara nuevos registros de fechas de exclusión para la promoción siempre y cuando ya no exista un registro previo sobre esa misma promoción, tienda y fecha.

-- {
    "companyId": "napse",
    "catalog": "CatalogExclusionDates",
    "params": [],
    "items": [
        {
            "storeCode": "napse",
            "promotionName": "Promo Puntos I",
            "exclusionDates": ["2023-07-14"],
            "operation": "U"
        }
    ]
}

-- {
    "status": "200",
    "description": "CatalogExclusionDates",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Formato de limite con operación R (remove)

El proceso de remover exclusiones contempla dos casos:

Cuando se quiere remover la exclusión de una promoción en una fecha especifica, deberá indicar el siguiente formato.

-- {
    "companyId": "napse",
    "catalog": "CatalogExclusionDates",
    "params": [],
    "items": [
        {
            "storeCode": "napse",
            "promotionName": "Promo Puntos I",
            "exclusionDates": ["2023-07-14"],
            "operation": "R"
        }
    ]
}

-- {
    "status": "200",
    "description": "CatalogExclusionDates",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Cuando se quiere remover la exclusión de todas las promociones en una fecha especifica, deberá indicar el siguiente formato.

La diferencia con el formato anterior es que el valor del campo promotionName se deja como un string vacío igual a ""

-- {
    "companyId": "napse",
    "catalog": "CatalogExclusionDates",
    "params": [],
    "items": [
        {
            "storeCode": "3",
            "promotionName": "",
            "exclusionDates": ["2023-07-10"],
            "operation": "R"
        }
    ]
}

Si la solicitud ha sido exitosa, se podrá visualizar la siguiente respuesta (Interfaz Rest):

-- {
    "status": "200",
    "description": "CatalogExclusionDates",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

En el caso de indicar un código de compañía que no existe, visualizara la siguiente respuesta:

-- {
    "status": "400",
    "description": "CatalogExclusionDates",
    "detail": {
        "result": "error",
        "detail": "El código de compañía napse no pertenece a una compañía existente."
    }
}

Servicio De Canje de Puntos por Catalogo

Como soporte al beneficio de Canje de Puntos por Catalogo), se deben especificar la tabla de productos que poseen equivalente en puntos a través de un catalogo definido para tal uso.

-- http://localhost:8073/promo/api/rest/catalogs

Siguiendo el formato especificado anteriormente tendremos:

Campo	Valor
companyId	El código de la compañia correspondiente. Requerido.
catalog	"CatalogRedeemBenefit". No se debe modificar. Requerido.
params	Un listado vacío. No se debe modificar. Requerido.
items	Un listado con cada item del catálogo de Canje de puntos. Requerido.

Dentro de items, el formato es:

Campo	Valor
store	Código de tienda. Requerido. Alfanumérico. Si se aplica a todas las tiendas, el código de la tienda debe ser "-".
code	Código del producto. Requerido. Alfanumérico.
points	Puntos requeridos. Numérico con decimales.
discountValue	Valor descuento. Numérico con decimales.
discountType	Tipo descuento. Acepta sólo los valores "perc" (porcentaje), "fix" (descuento fijo), o bien, "nprice" (nuevo precio)
operation	La operación a realizar sobre el elemento. Ver tabla con valores posibles.

Así tendremos que un ejemplo de request para insertar registros en este catálogo será:

-- {
    "companyId": "napse",
    "catalog": "CatalogRedeemBenefit",
    "params": [],
    "items": [
        {
            "store": "3",
            "code": "10",
            "points": "10.5",
            "discountValue":"15" ,
            "discountType": "perc",
            "operation": "I"
        },
        {
            "store": "3",
            "code": "20",
            "points": "20.5",
            "discountValue":"20" ,
            "discountType": "fix",
            "operation": "I"
        },
        {
            "store": "3",
            "code": "30",
            "points": "50",
            "discountValue":"25" ,
            "discountType": "nprice",
            "operation": "I"
        }
    ]
}

-- {
    "status": "200",
    "description": "CatalogRedeemBenefit",
    "detail": {
        "result": "ok",
        "detail": "Se generó con éxito el registro de importación. Puede ver su estado correspondiente en el monitor de importación."
    }
}

Servicio De Asignación de Elementos de Fidelidad

Esta operación es el equivalente a la función de asignacion/actualización de elementos, mas la importación de clientes nuevos (Ver proceso actual de asignación de convenios).

Asignación a un elemento de fidelidad de un cliente, un convenio y su monto

Esta operación realiza la asignación de tarjeta, cliente, convenio, y monto.

Debe existir previamente la tarjeta (activa o inactiva), un convenio activo, y el cliente, en caso de no existir, se da de alta.

En relación al monto, se le puede asignar o no un operador adelante del monto; especificando el operador + suma un valor al monto que la tarjeta tiene; especificando el operador - resta saldo al monto que la tarjeta tiene; si no se pone operador reemplaza el monto que la tarjeta tiene (ver más abajo el ejemplo del campo amount).

Un esquema de ejemplo es el siguiente:

-- {
    "companyId": "napse",
    "catalog": "CatalogCardAssign",
    "params": [
        {
            "cardType": "tipo1"
        },
        {
            "contract": "convenio1"
        }
    ],
    "items": [
        {
            "operation": "I",
            "id": "1111000000030",
            "customer": "codCliente1",
            "amount": "90.37",
            "name": "Juan",
            "surname": "Perez",
            "gender": "hom",
            "birthDate": "19900506",
            "idType": "dni",
            "identifier": "33334444",
            "idDate": "21001005",
            "nacionality": "Argentina",
            "email": "[email protected]",
            "customerType": "gold",
            "address": "Urquiza 20",
            "country": "ar",
            "state": "bsas",
            "city": "tig",
            "postalCode": "7669",
            "phone": "2222-4444"
        }
	,{otro item.......}
	,{otro item.......}
	,{otro item.......}
	,{otro item.......}
	,{otro item.......}
	,{otro item.......}
    ]
}

Donde:

Campo	Descripción
*params*	cardType: Tipo de elemento de fidelidad a importar que sera validado. Requerido contract: codigo de convenio al que pertenecen estos elementos/clientes. Requerido
*operation*	I: Inserción / U: Actualización / R: Eliminación. Requerido
id	El elemento debe existir. Requerido
*customer*	Si viene informado el cliente y en la DB el elemento no tiene un cliente asociado, se verificara si el cliente informado existe en la DB, y de ser así, se actualizara el campo con el valor informado en el archivo. Si el cliente informado, no existe en la DB, *se darà de alta con los datos correspondientes al cliente (ver name inclusive en adelante). Si viene informado el cliente, y en la DB el elemento tiene asociado el mismo cliente, queda el campo como esta. Si viene informado el cliente, y en la DB el elemento tiene asociado otro cliente, informara en el detalle de errores que el elemento tiene asociado otro cliente en la DB, y no permitirá procesar ese registro. Si no viene informado el cliente, informara un mensaje indicando que el campo cliente es mandatorio, y no permitirá procesar ese registro*. Campo Requerido
*amount*	Numérico con decimales (string). Requerido Si se agrega un operador a la izquierda del monto, el mismo suma o resta al monto actual de la tarjeta. Para reemplazar el monto, no debe especificarse un operador. Ejemplo, con tarjeta con 100 de monto: +100 resulta en monto de 200. -60 resulta en monto de 40. 70 resulta en monto de 70.
*name*	Nombre del Cliente. Cadena libre. Requerido
*surname*	Apellido. Cadena libre. Requerido
*gender*	Género. (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin.
*birthDate*	Fecha de nacimiento. Cadena en formato "yyyyMMdd". Más Información del formato
*idType*	Tipo de identificación (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin. Requerido
*identifier*	Numero de Identificación del Cliente. Requerido
*idDate*	Fecha de Expiración de la identificación. Cadena en formato "yyyyMMdd". Más Información del formato
*nacionality*	Nacionalidad. Cadena Libre.
*email*	Dirección de correo electrónico. Cadena libre.
*customerType*	Tipo de Cliente (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin.
*address*	Dirección. Cadena libre
*country*	País. (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin.
*state*	Estado/Provincia (ver valores por Catálogo). Depende de los valores cargados en el catálogo a tal fin.
*city*	Ciudad (ver valores por catálogo). Depende de los valores cargados en el catálogo a tal fin.
*postalCode*	Código Postal
*phone*	Teléfono

Caso de uso:

Teniendo en cuenta que existe un convenio activo con código c1, y que hay un elemento existente, con código 1234000000000, y pertenece al tipo de elemento de código verano, se asigna al elemento el convenio mencionado, el monto de 100, y un nuevo cliente.

Al no existir se da de alta en la base de datos.

Asignación:

-- {
    "companyId": "{{COMPANYID}}",
    "catalog": "CatalogCardAssign",
    "params": [
        {"cardType": "verano"},
        {"contract": "c1"}
    ],
    "items": [{
            "operation": "I",
            "id": "1234000000000",
            "customer": "emc",
            "amount": "100",
            "name": "Eugenia",
            "surname": "Molina",
            "gender": "M",
            "birthDate": "19900101",
            "idType": "dni",
            "identifier": "77778888",
            "idDate": "20500101",
            "nacionality": "Argentina",
            "email": "[email protected]",
            "customerType": "vip",
            "address": "Urquiza 5050",
            "country": "ar",
            "state": "bsas",
            "city": "tig",
            "postalCode": "4433",
            "phone": "2222-9999"
        }]
}

Incremento de saldo

Para incrementar el saldo al elemento se especifica un operador + con el valor a sumar. Siguiendo el ejemplo anterior, donde el elemento tenía un saldo de 100, se le suman 50 en este ejemplo. Después de esta operación el saldo resultante será de 150.

-- {
    "companyId": "{{COMPANYID}}",
    "catalog": "CatalogCardAssign",
    "params": [
        {"cardType": "verano"},
        {"contract": "c1"}
    ],
    "items": [{
            "operation": "I",
            "id": "1234000000000",
            "customer": "emc",
            "amount": "+50",
            "name": "Eugenia",
            "surname": "Molina",
            "gender": "M",
            "birthDate": "19900101",
            "idType": "dni",
            "identifier": "77778888",
            "idDate": "20500101",
            "nacionality": "Argentina",
            "email": "[email protected]",
            "customerType": "vip",
            "address": "Urquiza 5050",
            "country": "ar",
            "state": "bsas",
            "city": "tig",
            "postalCode": "4433",
            "phone": "2222-9999"
        }]
}

Disminución de saldo

Similar al incremento. Para restar saldo se usa el operador - y luego el valor del monto a restar. Si el elemento anteriormente tenía 150, al restar 20 queda en 130 de monto.

-- {
    "companyId": "{{COMPANYID}}",
    "catalog": "CatalogCardAssign",
    "params": [
        {"cardType": "verano"},
        {"contract": "c1"}
    ],
    "items": [{
            "operation": "I",
            "id": "1234000000000",
            "customer": "emc",
            "amount": "-20",
            "name": "Eugenia",
            "surname": "Molina",
            "gender": "M",
            "birthDate": "19900101",
            "idType": "dni",
            "identifier": "77778888",
            "idDate": "20500101",
            "nacionality": "Argentina",
            "email": "[email protected]",
            "customerType": "vip",
            "address": "Urquiza 5050",
            "country": "ar",
            "state": "bsas",
            "city": "tig",
            "postalCode": "4433",
            "phone": "2222-9999"
        }]
}

Servicio De Importación de Segmentos

Servicio Rest que opera de forma sincrónica para administrar clientes asociados a segmentos.

Una vez obtenido el token de acceso, el servicio puede ser invocado utilizando el método POST, desde la URL:

-- <promo>/api/rest/segments

El formato general de solicitud es:

-- {
 "companyId": "myCompanyId",
"params":[      
	{"param1":"param1value", "paramN":"paramNvalue", ...}
],
"items": [
{.... primer item .......},
{.... otro item .......},
{.... otro item .......},
{.... otro item .......},
{.... otro item .......},
]
}

Donde:

Campo	Descripción	Tipo de Dato
companyId	código de Empresa	alfanumérico. Requerido
params	Parámetros extra	Listado de objetos de tipo clave, valor. Cada catalogo puede tener sus parámetros específicos, pero como valor genérico tenemos: "deleteAllCollectionFirst" : "true" Indica que antes de realizar la importación de este conjunto de registros se realice el borrado de todos los registros existentes. "segmentCode": "mySegmentCode" Indica el código de segmento al cual se asocian estos "ítems". En caso de no existir el segmento, será creado automáticamente. Es un campo requerido. alfanumérico y sin limitaciones de longitud.
items	Registros a importar	Colección de objetos dependientes de cada catálogo. requerido

El formato de los ítems es el siguiente:

Campo	Descripción
operation	Operación que se intenta realizar sobre el registro: "I" Insertar, "R" remover, "IU" insertar/actualizar
customer	Código del cliente que se quiere asociar/remover respecto al segmento informado en segmentcode

En este caso se envían para el segmento "ts02c", 10 registros que son 2 remociones (R), 1 Actualización/inserción (IU) y 7 Inserciones (I)

-- {
    "companyId": "napse",
    "params": [
        {"segmentCode": "ts02c", "deleteAllCollectionFirst":"false"}
    ],
    "items": [
        { "operation": "R", "customer": "c1" },
        { "operation": "IU", "customer": "c2" },
        { "operation": "R", "customer": "c3" },
        { "operation": "I", "customer": "c4" },
        { "operation": "I", "customer": "c5" },
        { "operation": "I", "customer": "c6" },
        { "operation": "I", "customer": "c7" },
        { "operation": "I", "customer": "c8" },
        { "operation": "I", "customer": "c9" },
        { "operation": "I", "customer": "c0" }    
    ]
}

El formato general de respuesta es:

-- {
    "status": 200,
    "description": "customerSegment",
    "detail": {
        "result": "ok",
        "detail": "",
        "updated": 0,
        "ignored": 0,
        "inserted": 0,
        "removed": 0,
        "errors": 0,
        "processed": 0,
        "errorDetails": [
            {
                "rec": 1,
                "customer": "mycustomer",
                "msg": "my error message"
            },
            ...
        ]
    }
}

Donde

Campo	Descripción	Resultado
status	Código de respuesta	200 indica que ha sido procesada correctamente.
description	Descripción general indicando que se trata de customerSegment.
detail	Detalle del proceso
detail.result	Resultado general del proceso	ok indicando proceso realizado
detail.detail	Mensaje detallado respecto al proceso	vacío en el caso de ok
detail.updated	cantidad de ítems actualizados
detail.ignored	cantidad de ítems ignorados
detail.inserted	cantidad de ítems agregados
detail.removed	cantidad de ítems removidos
detail.errors	cantidad de ítems erróneos
detail.processed	cantidad de ítems procesados
errorDetails	Detalle de cada registro con error.	rec: numero de registro en la solicitud customer: código de cliente correspondiente msg: mensaje informativo del error.

Aquí se observa status 200 indicando que se ha procesado el request, donde en este caso se han actualizado 1 registro, existen 9 errores sobre un total de 10 registros procesados. Por otra parte errorDetails nos indica cada uno de los 9 que han tenido error.

-- {
    "status": 200,
    "description": "customerSegment",
    "detail": {
        "result": "ok",
        "detail": "",
        "updated": 1,
        "ignored": 0,
        "inserted": 0,
        "removed": 0,
        "errors": 9,
        "processed": 10,
        "errorDetails": [
            {
                "rec": 1,
                "customer": "c1",
                "msg": "not found"
            },
            {
                "rec": 3,
                "customer": "c3",
                "msg": "not found"
            },
            {
                "rec": 4,
                "customer": "c4",
                "msg": "already exists"
            },
            {
                "rec": 5,
                "customer": "c5",
                "msg": "already exists"
            },
            {
                "rec": 6,
                "customer": "c6",
                "msg": "already exists"
            },
            {
                "rec": 7,
                "customer": "c7",
                "msg": "already exists"
            },
            {
                "rec": 8,
                "customer": "c8",
                "msg": "already exists"
            },
            {
                "rec": 9,
                "customer": "c9",
                "msg": "already exists"
            },
            {
                "rec": 10,
                "customer": "c0",
                "msg": "already exists"
            }
        ]
    }
}

Para cualquier tipo de Programa de Objetivos, si un cliente no ha consumido durante un período igual o mayor a la frecuencia máxima y por el proceso ha sido quitado del segmento en que se encontraba; puede ser restituido al mismo segmento, a través del servicio Rest.

Servicio De Administración de Elementos de Fidelidad

Servicio Rest que opera de forma sincrónica para administrar elementos de fidelidad.

Una vez obtenido el token de acceso, el servicio puede ser invocado utilizando el método POST, desde la URL:

-- <promo>/api/rest/cards/admin

El formato general de solicitud es:

-- {
 "companyId": "myCompanyId",
"params":[      
	{"param1":"param1value", "paramN":"paramNvalue", ...}
],
"items": [
{.... primer item .......},
{.... otro item .......},
{.... otro item .......},
{.... otro item .......},
{.... otro item .......},
]
}

Donde

Campo	Descripción	Tipo de Dato
companyId	código de Empresa	alfanumérico. Requerido
params	Parámetros extra	Requerido detailedErrors: indica si se desea el detalle de errores en la respuesta. Default: true detailedSuccess: indica si se desea el detalle de registros correctos en la respuesta. Default: true validateCard: Realiza todas las validaciones del elemento de fidelidad. Por ej: el uso de cvv. Default: false. oneActiveCardByCustomer: Valida si un cliente posee un elemento de fidelidad activo. Default: true
items	Registros a importar	Colección de elementos y su operación asociada. Requerido

El formato de los ítems es el siguiente:

Campo	Descripción
operation	Operación a realizar sobre el registro. Ver tabla siguiente Requerido
code	código de elemento. En este caso si se solicita crear un elemento, el mismo será creado con este código. Si se deja por defecto genera un número automáticamente. Valor por defecto: ''
type	Tipo de Elemento en cuestión. Obligatorio, debe existir previamente.
validFrom	Valida desde. Opcional, si se deja vacío se generara acorde al tipo de elemento. El formato es "YYYY-MM-DD"
validTo	Valida Hasta. Opcional, ídem anterior. El formato es "YYYY-MM-DD"
amount	Monto asociado a la operación. Requerido
customerId	Código de cliente asociado. Valor por defecto: ''". Opcional
cvv	CVV asociado. Valor por defecto: ''". Opcional
reason	Motivo de la operación. Generalmente se utiliza en los cambios de saldo. Opcional.
stroreCode	Tienda donde se realizó la transacción. Opcional.
terminalCode	Terminal donde se realizó la transacción. Opcional.

Se puede agregar a la mensajeria el storeCode y el terminalCode

-- {
    "companyId": "2",
    "params": [],
    "items": [
        { "operation": "ACTIVATION", "code": "6000000010", "type": "15", "validFrom":"2023-08-11", "validTo":"2023-08-11", "amount":"100", "customerId":"12", "cvv":"", "reason":"", storeCode:"3", terminalCode:"1" }
    ]
}

Los cuales se detallarán en la consola en: Gestión de Elementos de Fidelidad, en el botón "acciones" /"ver"

Los valores posibles del campo operation son:

Valor	Descripción
ACTIVATION	Activación del elemento con código "code". Si se utiliza la operación "ACTIVATION" sobre un Elemento de Fidelidad que no existe, Promo lo creará además de activarlo.
AMOUNT_UPDATE	Actualización de saldo. Sumará o restará el valor según lo enviado en el Json de la operación.
RECHARGE	Recarga
CHARGE	Carga Inicial. Esta operación se utiliza exclusivamente cuando se activa una tarjeta con saldo, porque realiza la carga inicial activándola y cargándole el saldo. Nota: si activa la tarjeta sin saldo inicial, al realizar la primer carga esa operación es recharge.
CONSUME	Consumo
CANCEL	Desactivar el elemento en cuestión

Este servicio no permite crear mas de una tarjeta activa para un mismo cliente (sin importar si está o no asociada a un convenio).

Esto se controla con la variable: "oneActiveCardByCustomer", que por default es TRUE.

Elementos de Fidelidad Nominados

Ejemplo 1: Se solicita la activación de un elemento de fidelidad nominado con el parámetro oneActiveCardByCustomer en true y con el cliente, que ya tiene un elemento de fidelidad activo

-- {
    "companyId": "napse",
    "params": [
        {}
    ],
    "items": [
        {
            "operation": "ACTIVATION",
            "code": "12110",
            "type": "13",
            "validFrom": "",
            "validTo": "",
            "amount": "0",
            "customerId": "9",
            "cvv": "",
            "reason": "",
            "storeCode": "",
            "terminalCode": ""
        }
    ]
}

-- {
    "status": "400",
    "description": "rest::cardAdmin",
    "detail": {
        "result": "error",
        "detail": "El cliente 9 ya posee un elemento de fidelidad activo"
    }
}

Ejemplo 2: Se solicita la activación de un elemento de fidelidad nominado con el parámetro oneActiveCardByCustomer en false y con el cliente:

-- {
    "companyId": "napse",
    "params": [
        {"oneActiveCardByCustomer": "false" }
    ],
    "items": [
        {
            "operation": "ACTIVATION",
            "code": "12100",
            "type": "13",
            "validFrom": "",
            "validTo": "",
            "amount": "0",
            "customerId": "9",
            "cvv": "",
            "reason": "",
            "storeCode": "",
            "terminalCode": ""
        }
    ]
}

-- {
    "status": 200,
    "description": "rest::cardAdmin",
    "transactionId": "SVC_CRD_20231023171240",
    "detail": {
        "result": "ok",
        "detail": "",
        "updated": 0,
        "ignored": 0,
        "inserted": 1,
        "removed": 0,
        "errors": 0,
        "processed": 1,
        "errorDetails": [],
        "successDetails": [
            {
                "rec": 1,
                "code": "12100",
                "amount": "0.0"
            }
        ]
    }
}

Se observa que se crea la tarjeta; aunque el cliente ya tiene asociada una tarjeta activa.

Ejemplo 3: Se solicita la activación de un elemento de fidelidad nominado con el parámetro oneActiveCardByCustomer en true y con un cliente.

-- {
    "companyId": "napse",
    "params": [
        {}
    ],
    "items": [
        {
            "operation": "ACTIVATION",
            "code": "12200",
            "type": "13",
            "validFrom": "",
            "validTo": "",
            "amount": "0",
            "customerId": "10",
            "cvv": "",
            "reason": "",
            "storeCode": "",
            "terminalCode": ""
        }
    ]
}

-- {
    "status": 200,
    "description": "rest::cardAdmin",
    "transactionId": "SVC_CRD_20231023171241",
    "detail": {
        "result": "ok",
        "detail": "",
        "updated": 0,
        "ignored": 0,
        "inserted": 1,
        "removed": 0,
        "errors": 0,
        "processed": 1,
        "errorDetails": [],
        "successDetails": [
            {
                "rec": 1,
                "code": "12200",
                "amount": "0.0"
            }
        ]
    }
}

Se observa que se creó la tarjeta.

Elemento de Fidelidad no Nominado

Ejemplo 1: Se solicita la activación de un elemento de fidelidad no nominado sin enviar el cliente:

-- {
    "companyId": "2",
    "params": [{}],
    "items": [
        {
            "operation": "ACTIVATION",
            "code": "10001",
            "type": "12",
            "validFrom": "",
            "validTo": "",
            "amount": "",
            "customerId": "",
            "cvv": "",
            "reason": ""
        }
    ]
}

-- {
    "status": "400",
    "description": "rest::cardAdmin",
    "detail": {
        "result": "error",
        "detail": "El cliente es requerido para el registro : 1"
    }
}

Ejemplo 2: Se solicita la activación de un elemento de fidelidad no nominado con el cliente:

-- {
    "companyId": "napse",
    "params": [
        {"oneActiveCardByCustomer":"false"}
    ],
    "items": [
        {
            "operation": "ACTIVATION",
            "code": "10002",
            "type": "12",
            "validFrom": "",
            "validTo": "",
            "amount": "0",
            "customerId": "clientec",
            "cvv": "",
            "reason": "",
            "storeCode": "",
            "terminalCode": ""
        }
    ]
}

-- {
    "status": 200,
    "description": "rest::cardAdmin",
    "transactionId": "SVC_CRD_20231023162247",
    "detail": {
        "result": "ok",
        "detail": "",
        "updated": 0,
        "ignored": 0,
        "inserted": 1,
        "removed": 0,
        "errors": 0,
        "processed": 1,
        "errorDetails": [],
        "successDetails": [
            {
                "rec": 1,
                "code": "10002",
                "amount": "0.0"
            }
        ]
    }
}

Se observa que se ha creado la tarjeta.

Ejemplo 3: Se solicita la activación de un elemento de fidelidad no nominado con el parámetro oneActiveCardByCustomer en true y sin el cliente:

-- {
    "companyId": "napse",
    "params": [
        {"oneActiveCardByCustomer":"true"}
    ],
    "items": [
        {
            "operation": "ACTIVATION",
            "code": "10008",
            "type": "12",
            "validFrom": "",
            "validTo": "",
            "amount": "0",
            "customerId": "",
            "cvv": "",
            "reason": "",
            "storeCode": "",
            "terminalCode": ""
        }
    ]
}

{
    "status": "400",
    "description": "rest::cardAdmin",
    "detail": {
        "result": "error",
        "detail": "El cliente es requerido para el registro : 1"
    }
}

Ejemplo 4: Se solicita la activación de un elemento de fidelidad no nominado con el parámetro oneActiveCardByCustomer en false y sin el cliente:

-- {
    "companyId": "napse",
    "params": [
        {"oneActiveCardByCustomer":"false"}
    ],
    "items": [
        {
            "operation": "ACTIVATION",
            "code": "10012",
            "type": "12",
            "validFrom": "",
            "validTo": "",
            "amount": "0",
            "customerId": "",
            "cvv": "",
            "reason": "",
            "storeCode": "",
            "terminalCode": ""
        }
    ]
}

-- {
    "status": 200,
    "description": "rest::cardAdmin",
    "transactionId": "SVC_CRD_20231023164008",
    "detail": {
        "result": "ok",
        "detail": "",
        "updated": 0,
        "ignored": 0,
        "inserted": 1,
        "removed": 0,
        "errors": 0,
        "processed": 1,
        "errorDetails": [],
        "successDetails": [
            {
                "rec": 1,
                "code": "10012",
                "amount": "0.0"
            }
        ]
    }
}

Se observa que el elemento ha sido creado.

Ejemplo de Envío de registro.

En este caso se envían las siguientes tarjetas:

solicitar crear una tarjeta "1000000005", de tipo 1, con saldo de 1000.
solicitar crear una tarjeta "1010000000", de tipo 2, con saldo de 150.
solicitar crear una tarjeta "2010000001", de tipo 3, con saldo de 50.
solicitar crear una tarjeta "7010000000", de tipo 4, con saldo de 1000.
solicitar crear una tarjeta "1100000001", de tipo 5, con saldo de 1000.
solicitar crear una tarjeta "1300000001", de tipo 6, con saldo de 100.
solicitar crear una tarjeta "7000000000", de tipo 7, con saldo de 1000.
solicitar crear una tarjeta "1000000005", de tipo 8, con saldo de 1000

-- {
    "companyId": "2",
    "params": [{"oneActiveCardByCustomer":"false", "validateCard":"true"}],
    "items": [
        { "operation": "ACTIVATION", "code": "1000000005", "type": "1", "validFrom":"", "validTo":"", "amount":"1000", "customerId":"", "cvv":"", "reason":""  },
        { "operation": "ACTIVATION", "code": "1010000000", "type": "2", "validFrom":"", "validTo":"", "amount":"150", "customerId":"", "cvv":"", "reason":""  },
        { "operation": "ACTIVATION", "code": "2010000001", "type": "3", "validFrom":"", "validTo":"", "amount":"50", "customerId":"", "cvv":"", "reason":""  },
        { "operation": "ACTIVATION", "code": "7010000000", "type": "4", "validFrom":"2023-08-14", "validTo":"2024-08-14", "amount":"1000", "customerId":"", "cvv":"", "reason":""  },
        { "operation": "ACTIVATION", "code": "1100000001", "type": "5", "validFrom":"", "validTo":"", "amount":"1000", "customerId":"", "cvv":"", "reason":""  },
        { "operation": "ACTIVATION", "code": "1300000001", "type": "6", "validFrom":"", "validTo":"", "amount":"100", "customerId":"", "cvv":"", "reason":""  },
        { "operation": "ACTIVATION", "code": "7000000000", "type": "7", "validFrom":"", "validTo":"", "amount":"1000", "customerId":"", "cvv":"", "reason":""  },
        { "operation": "ACTIVATION", "code": "1000000005", "type": "8", "validFrom":"", "validTo":"", "amount":"1000", "customerId":"", "cvv":"", "reason":""  }
    ]
}

-- {
    "status": 200,
    "description": "rest::cardAdmin",
    "transactionId": "SVC_CRD_20230814181744",
    "detail": {
        "result": "ok",
        "detail": "",
        "updated": 0,
        "ignored": 0,
        "inserted": 5,
        "removed": 0,
        "errors": 3,
        "processed": 8,
        "errorDetails": [
            {
                "rec": 1,
                "code": "9520",
                "info": null
            },
            {
                "rec": 5,
                "code": "9520",
                "info": null
            },
            {
                "rec": 8,
                "code": "9520",
                "info": null
            }
        ],
        "successDetails": [
            {
                "rec": 2,
                "code": "1010000000",
                "amount": "150.0"
            },
            {
                "rec": 3,
                "code": "2010000001",
                "amount": "50.0"
            },
            {
                "rec": 4,
                "code": "7010000000",
                "amount": "1000.0"
            },
            {
                "rec": 6,
                "code": "1300000001",
                "amount": "100.0"
            },
            {
                "rec": 7,
                "code": "7000000000",
                "amount": "1000.0"
            }
        ]
    }
}

La respuesta informa que en la transacción "transactionId": "SVC_CRD_20230814181744", se procesaron 8 registros, de los cuales 5 se procesaron correctamente y 3 dieron error.

En la sección "errorDetails" muestra información relacionada a los 3 registros que dieron error, y en la sección "successDetails" muestra para cada elemento de fidelidad insertado correctamente el monto que le quedó asignado a cada uno.

Se solicita modificar la carga de la tarjeta 1000000010 con 1.000. Inicialmente tenia ya cargados 1.000, es por ese motivo que en el Response muestra en "successDetails" que queda en "amount": "2000.0".

-- {
    "companyId": "2",
    "params": [{"oneActiveCardByCustomer":"false", "validateCard":"true"}],
    "items": [
        { "operation": "AMOUNT_UPDATE", "code": "1000000010", "type": "1", "validFrom":"", "validTo":"", "amount":"1000.00", "customerId":"", "cvv":"", "reason":""  }
        
    ]
}

-- {
    "status": 200,
    "description": "rest::cardAdmin",
    "transactionId": "SVC_CRD_20230814182939",
    "detail": {
        "result": "ok",
        "detail": "",
        "updated": 1,
        "ignored": 0,
        "inserted": 0,
        "removed": 0,
        "errors": 0,
        "processed": 1,
        "errorDetails": [],
        "successDetails": [
            {
                "rec": 1,
                "code": "1000000010",
                "amount": "2000.0"
            }
        ]
    }
}

Se solicita consumir 30 de la tarjeta "1010000000"

-- {
    "companyId": "2",
    "params": [{"oneActiveCardByCustomer":"false", "validateCard":"true"}],
    "items": [
        { "operation": "CONSUME", "code": "1010000000", "type": "1", "validFrom":"", "validTo":"", "amount":"30.00", "customerId":"", "cvv":"", "reason":""  }
        
    ]
}

-- {
    "status": 200,
    "description": "rest::cardAdmin",
    "transactionId": "SVC_CRD_20230814183317",
    "detail": {
        "result": "ok",
        "detail": "",
        "updated": 1,
        "ignored": 0,
        "inserted": 0,
        "removed": 0,
        "errors": 0,
        "processed": 1,
        "errorDetails": [],
        "successDetails": [
            {
                "rec": 1,
                "code": "1010000000",
                "amount": "120.0"
            }
        ]
    }
}

Se observa que ahora la tarjeta tiene un saldo de 120; cuando inicialmente era de 150

Se solicita recargar 30 a la tarjeta "4200000002"

-- {
    "companyId": "2",
    "params": [{"oneActiveCardByCustomer":"false", "validateCard":"true"}],
    "items": [
        { "operation": "RECHARGE", "code": "4200000002", "type": "6", "validFrom":"", "validTo":"", "amount":"30.00", "customerId":"", "cvv":"", "reason":""  }
        
    ]
}

-- {
    "status": 200,
    "description": "rest::cardAdmin",
    "transactionId": "SVC_CRD_20230814183628",
    "detail": {
        "result": "ok",
        "detail": "",
        "updated": 1,
        "ignored": 0,
        "inserted": 0,
        "removed": 0,
        "errors": 0,
        "processed": 1,
        "errorDetails": [],
        "successDetails": [
            {
                "rec": 1,
                "code": "4200000002",
                "amount": "1180.0"
            }
        ]
    }
}

Se solicita cargar 1000 a la tarjeta "7000000000"

-- {
    "companyId": "2",
    "params": [{"oneActiveCardByCustomer":"false", "validateCard":"true"}],
    "items": [
        { "operation": "CHARGE", "code": "7000000000", "type": "7", "validFrom":"", "validTo":"", "amount":"1000.00", "customerId":"", "cvv":"", "reason":""  }
        
    ]
}

-- {
    "status": 200,
    "description": "rest::cardAdmin",
    "transactionId": "SVC_CRD_20230814184411",
    "detail": {
        "result": "ok",
        "detail": "",
        "updated": 1,
        "ignored": 0,
        "inserted": 0,
        "removed": 0,
        "errors": 0,
        "processed": 1,
        "errorDetails": [],
        "successDetails": [
            {
                "rec": 1,
                "code": "7000000000",
                "amount": "2000.0"
            }
        ]
    }
}

Se solicita cancelar la tarjeta "7000000000"

-- {
    "companyId": "2",
    "params": [{"oneActiveCardByCustomer":"false", "validateCard":"true"}],
    "items": [
        { "operation": "CANCEL", "code": "7000000000", "type": "7", "validFrom":"", "validTo":"", "amount":"1000.00", "customerId":"", "cvv":"", "reason":""  }
        
    ]
}

-- {
    "status": 200,
    "description": "rest::cardAdmin",
    "transactionId": "SVC_CRD_20230814184627",
    "detail": {
        "result": "ok",
        "detail": "",
        "updated": 1,
        "ignored": 0,
        "inserted": 0,
        "removed": 0,
        "errors": 0,
        "processed": 1,
        "errorDetails": [],
        "successDetails": [
            {
                "rec": 1,
                "code": "7000000000",
                "amount": "2000.0"
            }
        ]
    }
}

Donde

Campo	Descripción	Tipo de Dato
status	código de respuesta	200 indica que ha sido procesada correctamente.
description	Descripción general	Fijo "-- rest::cardAdmin'
transactionId	Id de la transaccion	string
detail	Detalle del proceso	array
detail.result	Resultado general del proceso	ok indicando proceso realizado
detail.detail	Mensaje detallado respecto al proceso	vacío en el caso de ok
detail.updated	cantidad de ítems actualizados	integer
detail.ignored	cantidad de ítems ignorados	integer
detail.inserted	cantidad de ítems agregados	integer
detail.removed	cantidad de ítems removidos	integer
detail.errors	cantidad de ítems erróneos	integer
detail.processed	cantidad de ítems procesados	integer
detail.errorDetails	Detalle de cada registro con error.	rec: numero de registro en la solicitud code: código de error. Ver lista de errores en el Manual de Integración - Motor 7.2, info: mensaje informativo del error, puede devolver NULL.
detail.successDetails	Detalle de cada registro procesado correctamente	rec: Numero de registro en la solicitud code: código del elemento. amount: carga del elemento de fidelidad

Los resultados de estas operaciones se verán reflejados en la Consola/Módulo de Fidelidad/Elementos de Fidelidad.

Servicio De Transferencia de saldos entre Elementos de Fidelidad

Transferencia parcial

Se puede realizar una transferencia parcial desde un elemento de fidelidad a otro.

Para permitir una transferencia parcial, el tipo de elemento de fidelidad debe tener seleccionada esta opción.

Al operar con postman, como el mensaje correspondiente será en formato xml, la cabecera content type tendrá el valor application/xml en lugar de application/json.

Napse > PROMO 7.8 - Manual de Integración - Servicios > image-2023-7-11_9-3-25.png

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.

Napse > PROMO 7.8 - Manual de Integración - Servicios > image-2023-7-12_15-51-28.png

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.

Napse > PROMO 7.8 - Manual de Integración - Servicios > image-2023-7-12_17-7-55.png

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.

Napse > PROMO 7.8 - Manual de Integración - Servicios > image-2023-7-12_17-7-13.png

Al confirmar la operación....

Napse > PROMO 7.8 - Manual de Integración - Servicios > image-2023-7-12_16-23-56.png

Servicio De Administración de Cupones

Crear, Activar y redimir Cupones

Servicio Rest que opera de forma sincrónica para administrar Cupones.

Una vez obtenido el token de acceso, el servicio puede ser invocado utilizando el método POST, desde la URL:

-- <promo>/api/rest/coupons/admin

El formato general de solicitud es:

-- {
 "companyId": "myCompanyId",
"params":[      
	{"param1":"param1value", "paramN":"paramNvalue", ...}
],
"items": [
{.... primer item .......},
{.... otro item .......},
{.... otro item .......},
{.... otro item .......},
{.... otro item .......},
]
}

Donde

Campo	Descripción	Tipo de Dato
companyId	código de Empresa	alfanumérico. Requerido
params	Parámetros extra	detailedErrors: indica si se desea el detalle de errores en la respuesta. Default: true detailedSuccess: indica si se desea el detalle de registros correctos en la respuesta. Default: true
items	Registros a importar	Colección de cupones y su operación asociada. Requerido

El formato de los ítems es el siguiente:

Campo	Descripción
operation	Operación a realizar sobre el registro. Ver tabla siguiente
barcode	Código de barras del cupón. En este caso si se solicita crear un elemento, el mismo será creado con este código. Si se deja por defecto genera un número automáticamente. Valor por defecto: ''
email	Correo electrónico destino para cupones de tipo electrónico. Opcional. Valor por defecto: ""
type	Tipo de Cupón. Obligatorio, debe existir previamente.
amount	Monto asociado a la operación.
customerId	Código de cliente asociado. Valor por defecto: ''
storeCode	Tienda donde se realizó la transacción. Opcional.
terminalCode	Terminal donde se realizó la transacción. Opcional.

Los valores posibles del campo operation son:

Valor

Descripción

CREATE

Emitir/Crear el cupón informado.

REDEEM

Redención

VOID

Desactivar

UPDATE

Bajo la operación UPDATE se puede modificar la fecha de vigencia de cupones utilizando el campo "validTo".
Si como parte de una operación de UPDATE de un cupón, se informa un customerId, ese customer será asignado al cupón.
En modo normal, será validado que el customerId exista previamente, dando un error si no existe el cliente en la base de datos de Promo. Si el flag "promo.allowNonExistingCustomers" está activo, entonces esta verificación no se llevará a cabo, pudiéndose asignar un cupón a un cliente inexistente en la base de Promo.

La operación UPDATE no modifica los datos del cliente que se ven desde la pantalla "Gestión de Clientes". La operación UPDATE actualiza los datos del cupón.

Como máximo se podrán operar 1.000 cupones por vez, sin importar el tipo de operación (create, redeem, void, update). Por ejemplo como máximo se podrán crear 1.000 cupones en una transacción.

Ejemplo de Envío de registro. En este caso se envían los siguientes cupones:

Se solicitar crear el cupón 1050000018 con valor de 1000.
Se solicita redimir el cupón 1050000018 por 700.
Se solicita anular el cupón 1050000020

-- {
    "companyId": "2",
    "params": [],
    "items": [
        { "operation": "CREATE", "barcode": "1050000018", "type": "1", "email":"", "storeCode":"3",
            "terminalCode":"1", "amount":"1000", "customerId":"3" },
        { "operation": "REDEEM", "barcode": "1050000018", "type": "1", "email":"", "storeCode":"3",
            "terminalCode":"1", "amount":"700", "customerId":""  },
        { "operation": "VOID", "barcode": "1050000020", "type": "1", "email":"", "storeCode":"3",
            "terminalCode":"1","amount":"500", "customerId":"" }
    ]
}

-- {
    "status": 200,
    "description": "rest::couponAdmin",
    "transactionId": "SVC_CPN_20230814185528",
    "detail": {
        "result": "ok",
        "detail": "",
        "updated": 0,
        "ignored": 0,
        "inserted": 0,
        "removed": 0,
        "errors": 3,
        "processed": 3,
        "errorDetails": [
            {
                "rec": 1,
                "code": "9105",
                "info": null
            },
                      
        ],
        "successDetails": [
            {
                "rec": 1,
                "code": "1050000018"
            },
            {
                "rec": 2,
                "code": "1050000018"
            } 
                         ]
    }
}

Donde

Campo	Descripción	Tipo de Dato
status	código de respuesta	200 indica que ha sido procesada correctamente.
description	Descripción general	Fijo "-- rest::couponAdmin'
transactionId	Id de la transacción	string
detail	Detalle del proceso	array
detail.result	Resultado general del proceso	ok indicando proceso realizado
detail.detail	Mensaje detallado respecto al proceso	vacío en el caso de ok
detail.updated	cantidad de ítems actualizados	integer
detail.ignored	cantidad de ítems ignorados	integer
detail.inserted	cantidad de ítems agregados	integer
detail.removed	cantidad de ítems removidos	integer
detail.errors	cantidad de ítems erróneos	integer
detail.processed	cantidad de ítems procesados	integer
detail.errorDetails	Detalle de cada registro con error.	rec: numero de registro en la solicitud code: código de error. Ver lista de errores en el Manual de Integración 7.2- Motor. info: mensaje informativo del error, puede devolver NULL.
detail.successDetails	Detalle de cada registro procesado correctamente	rec: Numero de registro en la solicitud code: código de cupón

Modificar Fecha de vigencia de cupones:

Se debe hacer la consulta en:

-- POST http://{{SERVER}}:{{PORT}}/promo/api/rest/coupon/admin

Para la modificación de la vigencia de cupones se debe enviar bajo la operación "UPDATE" (solo se puede realizar con esta operación) un nuevo campo dentro del listado ítems: campo validTo.

Ejemplo:

-- {
    "companyId": "{{COMPANY}}",
    "params": [],
    "items": [
        {
            "operation": "UPDATE",        
            "barcode": "3335",
            "type": "tipo123",
            "email": "",
            "amount": "",
            "customerId": ""
            "validTo": "2022-01-15"
        }
    ]
}

La respuesta será:

-- {
    "status": 200,
    "description": "rest::couponAdmin",
    "detail": {
        "result": "ok",
        "detail": "",
        "updated": 0,
        "ignored": 0,
        "inserted": 0,
        "removed": 0,
        "errors": 1,
        "processed": 1,
        "errorDetails": [          <--------- Caso de error
            {
                "rec": 1,
                "code": "9520",
                "info": null
            }
        ],
        "successDetails": [{        <--------- Caso satisfactorio
            {
                "rec": 1,
                "code": "12345678"
            }
        }]
    }
}

Servicio De Administración de Clientes

Crear, Modificar y Eliminar Clientes y Creación automática de elementos de fidelidad asociados

Servicio rest sincrónico de clientes (alta, baja y modificación) además crea y asocia elementos (el número de elemento se genera con el prefijo más el identificador del cliente).

Se pueden generar hasta 100 clientes.

Utilizando el método POST :

-- http://localhost:8073/promo/api/rest/customer

El campo “autoCard” contendrá un tipo de elemento, que si el cliente no posee será creada.

Ese elemento seguirá la definición de su tipo pero en el número asignará el nro de documento del cliente además del prefijo y largo de numeración.

Si el elemento existe no es creado. Si se crea, respeta el saldo inicial, vencimientos y todos los datos definidos en el tipo de elemento. Queda asociado al cliente en el mismo acto en que se crea.

-- {
    "companyId": "2",
    "catalog": "CatalogCustomer",
    "params": [],
    "items": [    
               {           
                "code": "8",           
                "name": "Marcela",           
                "lastName": "Sanchez",           
                "gender": "m",           
                "birthDate": "1972-12-07",           
                "identificationType": "dni",           
                "identifier": "21563286",           
                "identificationExpiration": "2050-01-01",           
                "nacionality": "arg",           
                "email": "[email protected]",           
                "customerType": "EMPLEADO",           
                "address": "calle1",           
                "addressCountry": "arg",           
                "addressState": "bsas",           
                "addressCity": "tig",           
                "addressPostalCode": "3053",           
                "phone": "46517131",           
                "isActive": "true",           
                "operation": "I"    
               },
               {           
                "code": "1",           
                "name": "Juan",           
                "lastName": "Perez",           
                "gender": "m",           
                "birthDate": "1900-05-31",           
                "identificationType": "dni",           
                "identifier": "12345",           
                "identificationExpiration": "2050-01-01",           
                "nacionality": "arg",           
                "email": "[email protected]",           
                "customerType": "EMPLEADO",           
                "address": "Avda. Libertador 3400",           
                "addressCountry": "arg",           
                "addressState": "bsas",           
                "addressCity": "tig",           
                "addressPostalCode": "2000",           
                "phone": "1555555555",           
                "isActive": "true",           
                "operation": "U"                    
               },
               {           
                "code": "13",           
                "name": "JOAQUIN",           
                "lastName": "Torres",           
                "gender": "m",           
                "birthDate": "1972-03-23",           
                "identificationType": "dni",           
                "identifier": "20587777",           
                "identificationExpiration": "2050-01-01",           
                "nacionality": "arg",           
                "email": "[email protected]",           
                "customerType": "EMPLEADO",           
                "address": "diagonal 12 2233",           
                "addressCountry": "arg",           
                "addressState": "bsas",           
                "addressCity": "tig",           
                "addressPostalCode": "3053",           
                "phone": "46667134",           
                "isActive": "true",           
                "operation": "R",           
                "autoCard":"Tipo1"       
               }
    ]
}

-- {
    "status": 200,
    "description": "catalogCustomer",
    "detail": {
        "result": "ok",
        "detail": "[]",
        "updated": 1,
        "ignored": 0,
        "inserted": 1,
        "removed": 1,
        "errors": 0,
        "processed": 3,
        "errorDetails": [],
        "successDetails": []
    }
}

También se puede administrar clientes a través del servicio de Importación de Catálogos/Catálogos de Clientes

Servicio De Administración de Límites

Crear, Modificar y Eliminar Límites de Promociones por tiendas

Se pueden dar de alta masiva de limites vía api rest, utilizando el método POST:

 -- http://localhost:8073/promo/api/rest/limits/import

El Json para insertar límites será:

-- {
    "companyId":"2",
    "limits": [
        {
            "operation":"I",
            "promotionName":"Promo P1",
            "benefitId": "64ddfc2d92889f36286c9d8f",
            "limitId": "",
            "limitScope":"RETAILER",
            "storeCode": "3",
            "description": "",
            "limitPeriod":"DAY",
            "numberDays":"2",
            "limitTypeCode": "benefiedProductCount",
            "value": "4"
        },
        {
            "operation":"I",
            "promotionName":"Promo P1",
            "benefitId": "64ddfc2d92889f36286c9d8f",
            "limitId": "",
            "limitScope":"STORE",
            "storeCode": "3",
            "description": "",
            "limitPeriod":"DAY",
            "numberDays":"5",
            "limitTypeCode": "benefiedProductCount",
            "value": "2"
        }
    ]
}

-- {
    "status": "Información Recibida OK",
    "description": "La importación de limites será procesada"
}

Donde:

Campo	Descripción	Tipo de Dato	Valores posibles
operation	Tipo de operación a realizar	string	I(Insert), U(Update), R (Remove)
promotionName	Nombre de la promoción, en la que se va a ingresar el límite o si ya existe se va a modificar o remover	string
benefitId	Identificador único del beneficio en el cual se va a ingresar, modificar o remover el/los limite/s	string
limitdId	Identificador único del limite que se quiere modificar o remover. Sólo se informa cuando la operacion sea U o R	string
limitScope	Tipo de límite	string	General, Tienda, Cliente
storeCode	Código de la tienda. Sólo se informa si el tipo de límite seleccionado fue por tienda
description	Descripción del limite	string
limitPeriod	Período a contabilizar del límite	string	Indefinido, Día
numerDays	Cantidad de días si el período a contabilizar seleccionado fue días	integer
limitTypeCode	Tipo de variable a la que se va a aplicar el limite.	string	Cantidad de productos beneficiados Cantidad de dinero Cantidad de aplicaciones Cantidad de cupones emitidos
value	valor del limite	double

El json para modificar límites será:

-- {
    "companyId":"2",
    "limits": [
        {
            "operation":"U",
            "limitId": "64ae87ceab7b185554057c7c",
            "limitScope":"RETAILER",
            "storeCode": "3",
            "description": "",
            "limitPeriod":"DAY",
            "numberDays":"2",
            "limitTypeCode": "benefiedProductCount",
            "value": "5"
        }
    ]
}

-- {
    "status": "Informacion Recibida OK",
    "description": "La importación de limites será procesada"
}

El json para eliminar límites será:

-- {
    "companyId":"napse",
    "limits": [
        {
            "operation":"R",
            "limitId": "64ae87ceab7b185554057c7c"
    
        }
    ]
}

-- {
    "status": "Informacion Recibida OK",
    "description": "La importación de limites será procesada"
}

Cada vez que se ejecute un Json con límites para las promociones esto generará un registro de importación, cuyo estado será visible desde Soporte/ Monitor de Importación.