API Endpoints - Portal de Clientes

Documentacion completa de todos los endpoints REST disponibles para el Portal de Clientes.

Estado: Planificado

Base URL: /portal/*

Autenticacion: Todos los endpoints (excepto los de /auth/*) requieren header Authorization: Bearer {jwt_token}

Grupos de Endpoints

Autenticacion (/portal/auth/*)

Registro, login y gestion de credenciales. Estos endpoints son publicos (no requieren JWT).

Metodo	Endpoint	Descripcion
POST	/portal/auth/register	Auto-registro con DNI/CUIT + password
POST	/portal/auth/login	Login con credenciales + tenant_id/sucursal_id
POST	/portal/auth/forgot-password	Solicitar codigo de recuperacion por email
POST	/portal/auth/reset-password	Restablecer password con codigo
POST	/portal/auth/refresh-token	Renovar JWT con refresh token

Cuenta Corriente (/portal/cuenta/*)

Consulta de estado de cuenta y deudas. Requieren JWT.

Metodo	Endpoint	Descripcion
GET	/portal/mi-cuenta	Resumen de cuenta del usuario autenticado
GET	/portal/deudas	Listado de deudas pendientes

Pagos (/portal/pagos/*)

Pagos online con gateways externos. Requieren JWT excepto el webhook.

Metodo	Endpoint	Descripcion
POST	/portal/pagos/iniciar	Iniciar pago online con gateway
POST	/portal/pagos/webhook	Webhook del gateway (publico, validado por firma)
GET	/portal/pagos/historial	Historial de pagos del usuario

Cupones (/portal/cupones/*)

Generacion y consulta de cupones de pago. Requieren JWT.

Metodo	Endpoint	Descripcion
POST	/portal/cupones/generar	Generar cupon de pago con codigo de barras
GET	/portal/cupones/mis-cupones	Listar cupones del usuario autenticado
GET	/portal/cupones/{codigo_barras}	Detalle de un cupon por codigo

Ver endpoints.md para documentacion detallada de cada endpoint con schemas de request/response.

Headers Requeridos

Endpoints protegidos (con JWT)

Authorization: Bearer {jwt_token}
Content-Type: application/json

Endpoints publicos (auth)

Content-Type: application/json

NO se usa header X-Client-Domain. El tenant se resuelve desde el JWT (endpoints protegidos) o desde el body del request (login/register).

Resolucion de Tenant

El tenant se resuelve de forma diferente segun el contexto:

• Login/Register: El frontend envia tenant_id + sucursal_id en el body (valores de .env del deploy Docker)
• Endpoints protegidos: Se extraen tenant_id + sucursal_id del JWT
• Webhook: El payment_id del payload permite ubicar el tenant desde portal_payments

sequenceDiagram
    participant F as Frontend
    participant M as Middleware
    participant C as Controller
    participant DB as PostgreSQL

    F->>M: Request + JWT
    M->>M: Decodificar JWT
    M->>M: Extraer tenant_id, sucursal_id
    M->>DB: Resolver DB desde ini.sistema (tenant_id)
    M->>DB: Resolver schema (sucXXXX) desde sucursal_id
    M->>C: Request con conexion configurada

Formato de Respuestas

Respuesta exitosa

{
  "success": true,
  "data": {}
}

Respuesta de error

{
  "success": false,
  "error": "Mensaje descriptivo",
  "code": "ERROR_CODE"
}

Codigos de Error

Codigo	Descripcion
400	Parametros invalidos o request malformado
401	JWT invalido, expirado o credenciales incorrectas
403	Usuario no autorizado para este recurso
404	Recurso no encontrado
409	Conflicto (ej: email ya registrado)
422	Validacion de negocio fallida
429	Rate limit excedido
500	Error interno del servidor

Seguridad

• Rate Limiting: Login 5/min por IP, API 100/min por usuario
• CORS: Configurado por deploy Docker (origen fijo por tenant)
• Input Validation: Validacion estructural en middleware, validacion de negocio en services
• Webhook Security: Firma especifica por gateway, idempotencia via external_id

Documentos Detallados

• Endpoints detallados - Request/response schemas completos
• Portal Cupones Controller - Controller de cupones