PortalCuponesController

Estado: Planificado

Responsabilidad

Manejar requests HTTP relacionados con cupones de pago del portal. Este controller NO implementa logica propia de cupones: delega a los servicios existentes CuponPagoService y CuponValidacionService del modulo CtaCte, exponiendolos via endpoints autenticados con JWT del portal.

Arquitectura

PortalCuponesController (Modules/Portal/Cupon/)
    |
    +-- CuponPagoService (existente, modulo CtaCte)
    |     Genera cupones con codigo ITF
    |
    +-- CuponValidacionService (existente, modulo CtaCte)
          Valida cupones por codigo de barras

No hay tabla portal_cupones. Los cupones se almacenan y gestionan desde la infraestructura existente del ERP. El portal solo actua como una interfaz de acceso para clientes autenticados.

Diferencia con el uso interno del ERP

Aspecto	Uso interno (ERP)	Uso portal (cliente)
Autenticacion	Session PHP del operador	JWT del portal
Identificacion de cliente	cliente_id en el request	portal_user_id del JWT -> ordcon
Servicios usados	CuponPagoService, CuponValidacionService	Los mismos, sin cambios
Permisos	Permisos del operador	Solo cupones propios del cliente

Endpoints

POST /portal/cupones/generar

Genera un nuevo cupon de pago con codigo de barras.

Request:

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

Validaciones del controller:

• facturas es requerido y debe ser array no vacio
• total es requerido y debe ser numerico positivo
• dias_vencimiento es opcional (default: 30)
• El cliente_id se resuelve del JWT (portal_user_id -> ordcon)

Flujo del controller:

1. Extraer portal_user_id del JWT
2. Resolver cliente_id desde portal_user -> ordcon
3. Validar estructura del request
4. Delegar a CuponPagoService::generarCupon(clienteId, facturas, total, diasVencimiento)
5. Retornar respuesta con datos del cupon

Response 200:

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

---

GET /portal/cupones/mis-cupones

Obtiene la lista de cupones del usuario autenticado.

Query Parameters:

• estado (opcional): pending, used, expired, cancelled
• limit (opcional): numero de registros (default: 50, max: 100)
• offset (opcional): offset para paginacion (default: 0)

Flujo del controller:

1. Extraer portal_user_id del JWT
2. Resolver cliente_id desde portal_user -> ordcon
3. Delegar a CuponPagoService::getCuponesByCliente(clienteId, estado, limit, offset)
4. Retornar lista de cupones

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"
      }
    ],
    "total": 1,
    "has_more": false
  }
}

---

GET /portal/cupones/

Obtiene un cupon especifico por su codigo de barras.

Flujo del controller:

1. Extraer portal_user_id del JWT
2. Resolver cliente_id desde portal_user -> ordcon
3. Delegar a CuponValidacionService::validarCupon(codigoBarras)
4. Verificar que el cupon pertenece al cliente autenticado
5. Retornar detalle del cupon

Response 200:

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

Response 404:

{
  "success": false,
  "error": "Cupon no encontrado",
  "code": "CUPON_NOT_FOUND"
}

Response 403:

{
  "success": false,
  "error": "No tiene acceso a este cupon",
  "code": "FORBIDDEN"
}

Validaciones:

• codigo_barras debe tener 19 digitos
• Digito verificador debe ser valido (delegado a CuponValidacionService)
• Cupon debe pertenecer al cliente autenticado

Errores Comunes

Codigo	code	Causa
400	INVALID_REQUEST	Parametros invalidos
401	UNAUTHORIZED	JWT invalido o expirado
403	FORBIDDEN	Cupon no pertenece al cliente autenticado
404	CUPON_NOT_FOUND	Codigo de barras no encontrado
500	INTERNAL_ERROR	Error del servidor