Documentación del Sistema

Appearance

CuponPagoService ​

Responsabilidad ​

Generar y validar cupones de pago con código de barras ITF (19 dígitos).

Código ITF (19 dígitos) ​

SUCU(4) + CLIENTE(6) + TIMESTAMP(8) + DV(1) = 19 dígitos

Ejemplo:
0001 + 056789 + 20260127 + 4 = 0001056789202601274

DV = Dígito Verificador (Módulo 10, ponderación 3-1)

Métodos ​

generarCupon() ​

Parámetros:

  • clienteId: ID del cliente
  • facturas: Array de facturas a incluir en el cupón
  • total: Monto total del cupón
  • diasVencimiento: Días hasta el vencimiento del cupón
  • tenantContext: Contexto del tenant

Retorna:

json
{
  "cupon_id": "uuid",
  "codigo_barras": "0001056789202601274",
  "monto": 10000.00,
  "fecha_vencimiento": "2026-02-27",
  "facturas": [...]
}

getCuponesByCliente() ​

Parámetros:

  • clienteId: ID del cliente
  • tenantContext: Contexto del tenant (database, schema)
  • estado: (opcional) Filtrar por estado: 'pending', 'used', 'expired', 'cancelled'
  • limit: Número de registros a retornar (default: 50)
  • offset: Offset para paginación (default: 0)

Retorna:

json
{
  "cupones": [
    {
      "cupon_id": "uuid",
      "codigo_barras": "0001056789202601274",
      "monto": 10000.00,
      "estado": "pending",
      "fecha_generacion": "2026-01-27",
      "fecha_vencimiento": "2026-02-27",
      "fecha_uso": null,
      "facturas": [],
      "recibo_id": null
    }
  ],
  "total": 2,
  "has_more": false
}

validarCupon() ​

Parámetros:

  • codigo: Código de barras del cupón
  • tenantContext: Contexto del tenant

Retorna: Datos del cupón si es válido, null si no existe o está vencido

Lógica de Negocio ​

Generación de Cupón ​

  1. Generar código ITF único de 19 dígitos
  2. Calcular fecha de vencimiento (días desde hoy)
  3. Crear registro en portal_cupones con estado "pending"
  4. Retornar datos del cupón con código de barras

Obtener Cupones por Cliente ​

  1. Buscar cupones del cliente con filtros opcionales (estado)
  2. Aplicar paginación (limit/offset)
  3. Actualizar cupones vencidos automáticamente (si fecha_vencimiento < hoy)
  4. Retornar lista con metadata de paginación

Validar Cupón ​

  1. Buscar cupón por código de barras
  2. Verificar que no esté vencido
  3. Verificar que esté en estado "pending"
  4. Retornar datos del cupón o null si no es válido

Generación de Código ITF ​

Formato: SUCU(4) + CLIENTE(6) + TIMESTAMP(8) + DV(1)

Ejemplo: 0001 + 056789 + 20260127 + 4 = 0001056789202601274

Cálculo del dígito verificador (DV):

  • Módulo 10 con ponderación 3-1

Validación del Código ​

El código de barras debe:

  • Tener exactamente 19 dígitos
  • El último dígito (DV) debe coincidir con el cálculo usando módulo 10 y ponderación 3-1

Casos de Prueba ​

Escenarios clave a testear:

  1. Generar código ITF: Debe generar 19 dígitos con formato correcto
  2. Dígito verificador: Debe calcular correctamente el DV con módulo 10
  3. Obtener cupones por cliente: Debe retornar lista con paginación
  4. Filtrar por estado: Debe filtrar cupones por estado especificado
  5. Paginación: Debe paginar correctamente con limit/offset

Integración con Caja ​

El sistema de caja existente puede:

  1. Validar cupones usando validarCupon()
  2. Procesar el pago si el cupón es válido
  3. Marcar el cupón como "used" y vincular el recibo generado