PLUGIN PROMO LOYALTY CARDS

Fecha	Versión	Descripción de cambios	Autor
12/06/2025	1.0	Creación del documento	Martín Malievac

DESCRIPCIÓN FUNCIONAL

El plugin cubrirá los siguientes escenarios:

Transacciones que ingresaron desde canales digitales (e-commerce o marketplaces) que no se encuentran integrados con PROMO.
Transacciones que han sido hechas en forma offline, es decir, no se ha podido agregar a la misma el programa de fidelidad de ese cliente, debido a que no había conexión con PROMO Central.
Primera compra de un cliente. En este caso al comprar por primera vez, el cliente aún no posee asociado un programa de fidelidad. Esto se hace durante un proceso que corre una vez al día.

El plugin recorrerá las transacciones realizadas en BRIDGE de los siguientes tipos:

Venta
Devolución
Venta asociada a un pedido Omni

Las reglas de negocio serán las siguientes:

Primero daremos una descripción de los parámetros de configuración:
1. processReturns: indica si las devoluciones, debería restarle puntos al cliente si este pertenece a un programa de fidelidad.
2. loyaltyProgramCode: indica el código de programa de fidelidad que se da de alta en PROMO, en la sección "Fidelidad" => "Tipo de elementos de fidelidad".
3. loyaltyPointsPerUnitOfMoney": indica cuantos puntos sumará por cada peso / dólar gastado.
4. channelsIncluded: indica los canales para los cuales se deben evaluar estas reglas de negocio. Estos deben estar separados por coma (",")
Reglas de negocio:
- Si la transacción fue "fidelizada", es decir, tuvo como parte de la misma, un programa o tarjeta de fidelidad asociada a ese cliente, no se realiza acción alguna.
- Si la transacción no fue fidelizada, se realiza el siguiente análisis:
  - Si la transacción es una devolución (Return) y el atributo processReturns es false, no se realiza acción alguna.
  - Si la transacción es una devolución (Return) y el atributo processReturns es true, se realizará una resta de puntos (ver reglas de negocio en esta misma sección, al final).
  - Si la transacción es una venta y el canal no se encuentra dentro del parámetro "channelsIncluded", no se realiza acción alguna.
  - Verifica si el cliente posee un programa de fidelidad con el código configurado en loyaltyProgramCode, si no tiene, no realiza acción alguna.
- Si la transacción se debe procesar (ventas con canal configurado o devoluciones que deben procesarse, y además, el cliente posee un programa de fidelidad asociado).
  - Se realiza el cálculo del dinero de la venta o devolución y se multiplica por el factor definido en loyaltyPointsPerUnitOfMoney
  - Ejemplo:
    - Cliente que posee 1000 puntos en el programa de fidelidad, realiza una compra de $ 1000 con un factor de 1, pasará a sumarle 1000 puntos ($ 1000 x 1).
    - Cliente que posee 1000 puntos en el programa de fidelidad, realiza una compra de $ 100 con un factor de 2, pasará a sumarle 200 puntos ($ 100 x 2).
    - Clientes que posee 1000 puntos en el programa de fidelidad, realiza una devolución de $ 500 con un factor de 1, pasará a restarle 500 puntos ($ 500 x 1).

INTRODUCCIÓN

Este documento tiene como finalidad, explicar el funcionamiento del plugin que asigna puntos de fidelidad en 3 escenarios:

Pedidos ingresados por OMNI que no fueron evaluados por PROMO.
Pedidos realizados sin conexión, a los cuales no se les pudo adicionar un programa de fidelidad y consecuentemente, no sumaron puntos.
Primera compra en la cual, el cliente aún no posee un programa de fidelidad asociado.

En conclusión y más importante: este plugin evalúa transacción a transacción y en caso de encontrar pedidos que no han sumado puntos, los evalúa contra PROMO.

DESCRIPCIÓN DE LOS COMPONENTES

PROMO

Solución que tiene definido un programa de fidelidad que otorga puntos por compra de acuerdo a determinadas condiciones.

BRIDGE MANAGER CENTRAL

Base de datos central de la solución BRIDGE en donde constan todas las transacciones realizadas en tienda física y pedidos omni que ingresan a través de otros canales y marketplace.

PLUGIN PROMO - LOYALTY - CARDS

Es un plugin que se instala en el servidor central (en donde están BRIDGE API CENTRAL, BMC y demás).

Se configura la base de datos productiva central.
Se configura el ENDPOINT de servicios contra PROMO para la empresa.
El plugin NO posee una base de datos propia.

FLUJO DE DATOS

El Plugin realiza las siguientes acciones:

Recorre la tabla TransactionRetail del modelo de datos de BRIDGE, buscando transacciones con el atributo "lake" en false.
Obtiene la transacción de la tabla Transaction, del modelo de datos de BRIDGE.
Si dicha transacción posee el atributo "promoGiftCardRecharge" la da por válida, ya que a la misma se la ha evaluado en el contexto de un programa de fidelidad.
Si no posee dicho atributo, validará lo siguiente:
1. Si el atributo "processReturns" es false, entonces marca la transacción como válida (lake = true).
2. Si el atributo "processReturns" es true, entonces debe verificar la lógica de suma y resta de puntos.
Lógica de suma y resta de puntos, parámetros de configuración:
1. processReturns: indica si las devoluciones, debería restarle puntos al cliente si este pertenece a un programa de fidelidad.
2. loyaltyProgramCode: indica el código de programa de fidelidad que se da de alta en PROMO, en la sección "Fidelidad" => "Tipo de elementos de fidelidad".
3. loyaltyPointsPerUnitOfMoney": indica cuantos puntos sumará por cada peso / dólar gastado.
4. channelsIncluded: indica los canales para los cuales se deben evaluar estas reglas de negocio. Estos deben estar separados por coma (",")
Marca el atributo "lake" en true.

VISUALIZACIÓN EN BRIDGE MANAGER CENTRAL

Se podrá visualizar el plugin en BRIDGE MANAGER CENTRAL, ingresando en Monitoreo => Monitor de Integraciones

Napse > Plugin Promo - Loyalty - Cards > image-2025-8-25_16-22-37.png

INSTALACIÓN DEL PLUGIN

Para que el plugin funcione, deben haberse dado los siguientes pasos:
- Haber instalado el plugin NodeJS.
- Haber configurado bien el plugin, apuntando a la base de datos central o comúnmente llamada BMC y a la de PROMO.

El próximo paso, es configurar el archivo de configuración:

{
  "app":{
    "server":{
      "host": "dev.napse.global",
      "port": 8685,
      "logMode": "debug",
      "isSsl": false
    },
    "bridgeApi": {
      "baseUrl": "https://bmc-test.napse.global:8445",
      "clientId": "bridge-api",
      "clientSecret": "DAFAFAFAFAFAFAFAFAFAFAFAFAFAA",
      "jwtSecret": "0077SECRET00AA0011AA00881100",
      "authPath": "/auth/login",
      "statusPath": "/integration/status"
    },
    "businessRules": {
      "processReturns": false,
      "loyaltyProgramCode": "1018",
      "loyaltyPointsPerUnitOfMoney": 1,
      "channelsIncluded": "bridge,R008",
      "promoCompanyId": "TEST"
    },
	"promo": {
      "url": "https://xx.xx.com/promo",
      "username": "usuario",
      "password": "clave"
    },     
	"mongoDb":{
      "uriBridge": "mongodb://sa:[email protected]:27017/base-bmc?authSource=admin&authMechanism=SCRAM-SHA-1",
      "uriPromo": "mongodb://sa:[email protected]:27017/base-promo?authSource=admin&authMechanism=SCRAM-SHA-1"
    }
  }
}

Los datos del archivo, son los siguientes:
- bridgeApi
  - baseUrl: es la URL de Bridge Api del servidor central de BRIDGE para el cliente que instalemos el plugin.
  - clientId: es el clientId de Bridge API para conectarse a los servicios REST.
  - clientSecret: idem punto anterior.
- businessRules:
  - processReturns: indica si las devoluciones, debería restarle puntos al cliente si este pertenece a un programa de fidelidad.
  - loyaltyProgramCode: indica el código de programa de fidelidad que se da de alta en PROMO, en la sección "Fidelidad" => "Tipo de elementos de fidelidad".
  - loyaltyPointsPerUnitOfMoney": indica cuantos puntos sumará por cada peso / dólar gastado.
  - channelsIncluded: indica los canales para los cuales se deben evaluar estas reglas de negocio. Estos deben estar separados por coma (",")
  - promoCompanyId: es el ID de compañía de PROMO (recordemos que PROMO es multi empresa)
- promo
  - url: es la url del servidor de PROMO incluyendo el /promo
  - username: es el usuario de la API de PROMO
  - password: es la clave de la API de PROMO
- mongoDB:
  - uriBridge: es la cadena de conexión a la base de BRIDGE Central, comúnmente llamada BMC.
  - uriPROMO: es la base de datos de PROMO
Luego, se instala el plugin como cualquier otro, es decir, si es en Linux, se configura en ecosystem o si es en Windows, como servicio.