Reportería de Loyalty
Conoce los reportes que te enviaremos para que hagas seguimiento a la actividad de tus campañas de fidelidad.
Archivos disponibles
| Reporte | Frecuencia | Disponible | Contenido |
|---|---|---|---|
| TRANSACTIONS | Diario | 11:00 UTC | Detalle de operaciones que impactaron el programa de loyalty. |
| EFFECTS | Diario | 11:00 UTC | Movimientos de puntos/cashback: acumulación, redención y ajustes. |
| BALANCE | Diario | 11:00 UTC | Estado de balance por tarjeta al cierre del día anterior. |
| MONTHLY | Mensual | Día 1 del mes | Consolidado de evolución de balances del mes anterior. |
Nomenclatura de archivos
Todos los archivos siguen la siguiente convención de nombre: LOYALTY_<TIPO_REPORTE>_
A continuación te dejamos un ejemplo: loyalty_balance_20251203_banisi_pan.csv
| Componente | Formato | Ejemplo |
|---|---|---|
| Tipo de reporte | TRANSACTIONS, EFFECTS, BALANCE, MONTHLY | BALANCE |
| Fecha (diario) | YYYYMMDD | 20251203 |
| Fecha (mensual) | YYYYMM | 202512 |
| Country code | ISO 3166-1 alpha-3 | PAN |
Veamos cada uno en detalle.
Reporte Transactions
Contiene el detalle de las operaciones que impactaron el programa de loyalty. Se genera diariamente con las transacciones del día calendario anterior (00:00:00 a 23:59:59).
Estructura del reporte
| Campo | Descripción | Ejemplo |
|---|---|---|
public_loyalty_member_id | Identificador único del member sobre el cual se acumulan puntos o cashback (card_id o user_id). | crd-3BfqAziX9Blt9j1Ku1hEAzhtHBw |
public_parent_loyalty_member_id | Identificador de la tarjeta titular asociada. Vacío si la compra se hizo con la tarjeta titular. | |
transaction_id | Número único que identifica la transacción. | ctx-3B0yQrc784pB... |
card_bin | Primeros dígitos del número de tarjeta. Identifican el banco emisor y tipo de tarjeta. | 451234 |
affinity_group | Grupo de afinidad al que pertenece la tarjeta. Determina qué beneficios aplican. | GROUP_A |
card_product_type | Tipo de producto de la tarjeta. | DEBIT / CREDIT / PREPAID |
card_network | Red de pagos por la que se procesó la transacción. | VISA / MASTERCARD |
account_type | Esquema de beneficios: indica si acumula puntos o cashback. | points |
amount | Monto total de la transacción sobre el cual se calculan los puntos. | 6000 |
authorization_points | Puntos generados al momento de la autorización. | 6000 |
capture_points | Puntos capturados al confirmarse la transacción. | 6000 |
loyalty_rule_applied | Nombre(s) de las campañas que determinaron la acumulación de puntos. | Base Points Campaign |
authorization_date | Fecha y hora de autorización de la transacción. | 2026-03-04T18:12:22Z |
capture_date | Fecha de presentación y confirmación del impacto en puntos. | 2026-03-05T10:00:00Z |
merchant_id | Identificador único del comercio. | MCH-001 |
merchant_name | Nombre del comercio donde se realizó la compra. | El Preferido Restaurante |
mcc | Merchant Category Code. Clasifica el rubro del negocio. | 5812 |
card_type | Indica si la tarjeta es física o virtual. | PHYSICAL |
cardholder_presence | Indica si el titular estaba físicamente presente. | CARDHOLDER_PRESENCE_PRESENT |
card_presence | Indica si la tarjeta física estuvo presente en la transacción. | PRESENT |
entry_mode | Modo de ingreso de los datos de la tarjeta. | CHIP / CONTACTLESS / MANUAL |
country_code | Código del país donde se realizó la transacción. | PAN |
recurring | Indica si es un cobro recurrente o suscripción automática. | true / false |
type | Tipo de transacción. | PURCHASE / WITHDRAWAL |
origin | Indica si la transacción fue doméstica o internacional. | DOMESTIC / INTERNATIONAL |
Reporte Efects
Refleja los movimientos de puntos: acumulación, redención y ajustes. Incluye tanto los movimientos generados automáticamente por transacciones como los mint/burn manuales.
Estructura del reporte
| Campo | Descripción | Ejemplo |
|---|---|---|
public_loyalty_member_id | Identificador único del member (card_id o user_id). | crd-3BfqAziX9Blt9j1Ku1hEAzhtHBw |
transaction_id | ID de la transacción que originó el movimiento. Vacío en ajustes manuales. | ctx-3B0yQrc784pB... |
event_type | Tipo de evento registrado. | payment / mint / burn |
payment_event_key | Clave de idempotencia del evento de pago. Presente solo en movimientos originados por transacciones. | 01KJX0TPQMPNWAH5A3SENNCT0T |
account_type | Tipo de cuenta afectada. | points / cashback |
amount | Monto del movimiento de puntos. | 1000 |
balance_before | Saldo del member antes del evento. | 3580 |
balance_after | Saldo del member después del evento. | 4640 |
card_bin | Primeros dígitos del número de tarjeta. | 451234 |
affinity_group | Grupo de afinidad de la tarjeta. | GROUP_A |
card_product_type | Tipo de producto de la tarjeta. | CREDIT |
card_network | Red de pagos. | VISA |
event_date | Fecha y hora en que se registró el evento de puntos. | 2026-03-04T18:12:22.521Z |
El campo
payment_event_key está presente únicamente en movimientos originados por transacciones (event_type = payment). En ajustes manuales (mint/burn) este campo estará vacío.
Reporte Balance
Representa el estado de puntos por tarjeta al cierre del día anterior. Incluye saldos actuales, acumulados en el año, puntos próximos a vencer y fechas relevantes.
Estructura del reporte
| Campo | Descripción | Ejemplo |
|---|---|---|
public_loyalty_member_id | Identificador único del member (card_id o user_id). | crd-3BfqAziX9Blt9j1Ku1hEAzhtHBw |
points_amount | Saldo actual de puntos disponibles. | 8000 |
points_last_updated_at | Fecha y hora de la última actualización del saldo. | 2025-12-03T15:15:00.000-03:00 |
points_earning | Total de puntos acumulados en el año calendario en curso. | 31066 |
points_redeemed | Total de puntos utilizados/canjeados en el año calendario en curso. | 0 |
points_expired | Total de puntos vencidos en el año calendario en curso. | 0 |
points_pending | Puntos autorizados pero aún no confirmados (flotantes). | 125148 |
points_to_expire_30_days | Cantidad de puntos que vencerán en los próximos 30 días. | 0 |
points_to_expire_60_days | Cantidad de puntos que vencerán en los próximos 60 días. | 0 |
points_to_expire_90_days | Cantidad de puntos que vencerán en los próximos 90 días. | 0 |
next_expiration_date | Fecha más próxima en la que vencerá un lote de puntos. | 2026-12-31 |
last_redemption_date | Fecha del último canje realizado por el member. | 2026-03-25T19:41:22.856Z |
card_bin | Primeros dígitos del número de tarjeta. | 451234 |
affinity_group | Grupo de afinidad de la tarjeta. | GROUP_A |
card_product_type | Tipo de producto de la tarjeta. | CREDIT |
card_network | Red de pagos. | VISA |
Reporte Monthly
Consolida la evolución de balances durante el mes calendario anterior. Se genera el día 1 de cada mes e incluye todos los miembros con actividad en el período.
Estructura del reporte
| Campo | Descripción | Ejemplo |
|---|---|---|
year | Año calendario al que corresponde el resumen. | 2026 |
month | Mes al que corresponde el resumen. | 2 |
public_loyalty_member_id | Identificador único del member (card_id o user_id). | crd-3BfqAziX9Blt9j1Ku1hEAzhtHBw |
opening_balance | Saldo de puntos con el que el member inició el mes. | 0 |
points_earning | Total de puntos acumulados durante el mes. | 8500 |
points_redeemed | Total de puntos utilizados o canjeados durante el mes. | 9000 |
points_expired | Total de puntos vencidos durante el mes. | 0 |
points_pending | Puntos autorizados pero aún no confirmados al cierre del mes. | 1000 |
closing_balance | Saldo al cierre del mes. Resulta de: saldo anterior + ganados + ajustes positivos - canjeados - vencidos. No incluye pendientes. | 6100 |
points_to_expire_30_days | Puntos que vencerán en los próximos 30 días a partir del cierre del mes. | 900 |
last_redemption_date | Fecha del último canje realizado por el member en el mes. | 2025-01-01 |
adjustments_positive | Ajustes de puntos a favor del member en el mes (ej: créditos por resolución de reclamos). Se acreditan vía Mint. | 100 |
adjustments_negative | Ajustes de puntos en contra del member en el mes (ej: débitos por reversas). Se aplican vía Burn. | 500 |
La fórmula del closing_balance es: opening_balance + points_earning + adjustments_positive - points_redeemed - points_expired. Los puntos pendientes (flotantes) no se incluyen en el cierre.