PortalCuponesController

Responsabilidad

Manejar requests HTTP relacionados con cupones de pago del portal. Orquesta el servicio CuponPagoService y retorna respuestas HTTP estandarizadas.

Endpoints

POST /portal/cupones/generar

Genera un nuevo cupón de pago con código de barras.

Request:

{
  "cliente_id": 123,
  "facturas": [
    {"id": "uuid-1234", "tipo": "Factura A", "numero": 123, "monto": 10000.00}
  ],
  "total": 10000.00,
  "dias_vencimiento": 30
}

Response 200:

{
  "success": true,
  "data": {
    "cupon_id": "uuid-cupon-123",
    "codigo_barras": "0001056789202601274",
    "monto": 10000.00,
    "fecha_vencimiento": "2026-02-27",
    "facturas": [...]
  }
}

Validaciones:

• cliente_id es requerido y debe ser entero
• facturas es requerido y debe ser array
• total es requerido y debe ser numérico
• dias_vencimiento es opcional (default: 30)

---

GET /portal/cupones/cliente/

Obtiene la lista de cupones de un cliente.

Query Parameters:

• estado (opcional): pending, used, expired, cancelled
• limit (opcional): número de registros (default: 50, max: 100)
• offset (opcional): offset para paginación (default: 0)

Response 200:

{
  "success": true,
  "data": {
    "cupones": [
      {
        "cupon_id": "uuid-cupon-123",
        "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": 1,
    "has_more": false
  }
}

Validaciones:

• cliente_id debe ser entero válido
• estado debe ser uno de: pending, used, expired, cancelled
• limit máximo: 100 registros
• offset debe ser no negativo

---

GET /portal/cupones/

Obtiene un cupón específico por su código de barras.

Response 200:

{
  "success": true,
  "data": {
    "cupon_id": "uuid-cupon-123",
    "cliente_id": 123,
    "cliente_nombre": "Juan Pérez",
    "codigo_barras": "0001056789202601274",
    "monto": 10000.00,
    "estado": "pending",
    "fecha_generacion": "2026-01-27",
    "fecha_vencimiento": "2026-02-27",
    "fecha_uso": null,
    "recibo_id": null,
    "facturas": [...]
  }
}

Response 404:

{
  "success": false,
  "error": "Cupón no encontrado o vencido"
}

Validaciones:

• codigo_barras debe tener 19 dígitos
• Dígito verificador debe ser válido
• Cupón debe pertenecer al tenant actual

---

Errores Comunes

Código	Error	Causa
400	Invalid request	Parámetros inválidos
404	Cupón no encontrado	Código no existe o vencido
401	Unauthorized	Token inválido o expirado
500	Internal error	Error del servidor