> For the complete documentation index, see [llms.txt](https://senselab.gitbook.io/senselab-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://senselab.gitbook.io/senselab-docs/docs/api/controllers_summary.md).

# API Controllers - Implementación Completa

**Proyecto:** Senselab Core API\
**Empresa:** Senselab\
**País:** Costa Rica\
**Desarrollador:** Jeremy Arias Solano\
**Fecha:** 20 de noviembre de 2025\
**Estado:** FASE 3 Completada (Autenticación y Autorización RBAC)

***

## ✅ Controladores Implementados

Se han creado **60 controladores** completamente funcionales (44 en API/, 16 en raíz):

### 🔐 0. **AuthController** ✅ (NUEVO - FASE 3)

* **Rutas**: `/api/login`, `/api/logout`, `/api/me`
* **Funcionalidades**:
  * ✅ **POST /login**: Autenticación con email y password
    * Valida credenciales
    * Verifica que usuario esté activo
    * Genera token Sanctum
    * Retorna usuario + token + 68 permisos
  * ✅ **POST /logout**: Cierre de sesión
    * Revoca token actual
    * No afecta otros tokens del mismo usuario
  * ✅ **GET /me**: Información del usuario autenticado
    * Retorna usuario con empresa, cargo, roles y permisos
* **Autenticación**: Laravel Sanctum (tokens personales)
* **RBAC**: Retorna todos los permisos del usuario a través de sus roles
* **Middleware**: `auth:sanctum` (excepto en /login)
* **Validaciones**:
  * Email requerido y formato válido
  * Password requerido (mínimo 6 caracteres)
  * Usuario debe estar activo para login
* **Respuestas**:
  * 200: Login exitoso con token
  * 401: Credenciales incorrectas
  * 403: Usuario inactivo
* **Nota**: Endpoint `/register` está comentado por seguridad

***

### 1. **EmpresaController** ✅

* **Rutas**: `/api/empresas`
* **Middleware**: `permission:empresas.{accion}`
* **Funcionalidades**:
  * ✅ Listado paginado con búsqueda
  * ✅ Creación con validación completa
  * ✅ Vista detallada con relaciones (régimen tributario, sucursales, usuarios, configuraciones)
  * ✅ Actualización parcial/completa
  * ✅ Soft delete (marca activo=false, eliminado=true)
* **Filtros**: search, activos
* **Eager Loading**: regimenTributario

### 2. **SucursalController** ✅

* **Rutas**: `/api/sucursales`
* **Funcionalidades**:
  * ✅ Listado por empresa
  * ✅ Creación con lógica de sucursal principal
  * ✅ Vista con almacenes y cajas
  * ✅ Actualización
  * ✅ Soft delete (no permite eliminar sucursal principal)
* **Filtros**: empresa\_id, activos
* **Lógica especial**: Auto-desmarca otras sucursales principales al marcar una como principal

### 3. **AlmacenController** ✅

* **Rutas**: `/api/almacenes`
* **Funcionalidades**:
  * ✅ Listado por empresa y sucursal
  * ✅ Creación con lógica de almacén principal
  * ✅ Vista detallada
  * ✅ Actualización
  * ✅ Soft delete (no permite eliminar almacén principal)
* **Filtros**: empresa\_id, sucursal\_id, activos
* **Eager Loading**: empresa, sucursal

### 4. **ProductoController** ✅

* **Rutas**: `/api/productos`
* **Funcionalidades**:
  * ✅ Listado con búsqueda avanzada
  * ✅ Creación con validación de campos obligatorios
  * ✅ Vista con todas las relaciones (empresa, categoría, unidad medida, marca, proveedor, impuesto, cabys)
  * ✅ Actualización
  * ✅ Soft delete
* **Filtros**: search, empresa\_id, categoria\_id, tipo, activos
* **Scopes utilizados**: activos(), porEmpresa(), porCategoria(), porTipo()
* **Búsqueda**: nombre, código, código de barras, descripción

### 5. **ClienteController** ✅

* **Rutas**: `/api/clientes`
* **Funcionalidades**:
  * ✅ Listado con búsqueda multi-campo
  * ✅ Creación con validación de identificación única por empresa
  * ✅ Vista con últimas 10 ventas y cuentas por cobrar pendientes
  * ✅ Actualización con validación de unicidad
  * ✅ Soft delete
* **Filtros**: search, empresa\_id, tipo\_identificacion, activos
* **Validaciones especiales**:
  * Identificación única por empresa
  * Tipos de identificación: fisica, juridica, dimex, nite, extranjero
* **Métodos auxiliares**: getNombreCompletoAttribute(), getTipoIdentificacionDescripcionAttribute(), tieneIdentificacionValida()

### 6. **ProveedorController** ✅

* **Rutas**: `/api/proveedores`
* **Funcionalidades**:
  * ✅ Listado con búsqueda
  * ✅ Creación (normalización automática de campos)
  * ✅ Vista con últimas 10 órdenes de compra y cuentas por pagar pendientes
  * ✅ Actualización
  * ✅ Soft delete
* **Filtros**: search, empresa\_id, activos
* **Boot logic**: Normaliza automáticamente nombre, razón\_social, nit\_ruc, email, teléfono

### 7. **VentaController** ✅

* **Rutas**: `/api/ventas`
* **Funcionalidades**:
  * ✅ Listado con filtros de fechas
  * ✅ Creación con detalles y cálculo automático de totales
  * ✅ Vista completa con todas las relaciones
  * ✅ Actualización (solo observaciones y estado)
  * ✅ Anulación (marca estado=anulada + soft delete)
* **Filtros**: empresa\_id, sucursal\_id, cliente\_id, fecha\_inicio, fecha\_fin
* **Proceso automático**:
  * Genera número de comprobante único: FAC-00000001, TIQ-00000001, NC-00000001, ND-00000001
  * Crea detalles de venta con cálculo de impuestos
  * Calcula monto\_subtotal, monto\_descuentos, monto\_impuestos, monto\_total
* **Tipos de comprobante**: factura, tiquete, nota\_credito, nota\_debito
* **Estados**: pendiente, pagada, anulada
* **Transacciones**: Usa DB::beginTransaction() para integridad

### 8. **OrdenCompraController** ✅

* **Rutas**: `/api/ordenes-compra`
* **Funcionalidades**:
  * ✅ Listado con múltiples filtros
  * ✅ Creación con detalles y generación de número de orden
  * ✅ Vista con cálculo de saldo pendiente
  * ✅ Actualización (solo en estado borrador o pendiente)
  * ✅ Eliminación (solo en estado borrador)
* **Filtros**: empresa\_id, proveedor\_id, estado, pendientes, activas
* **Scopes utilizados**: porEmpresa(), porProveedor(), pendientes(), activas()
* **Estados**: borrador, pendiente, aprobada, recibida, cancelada
* **Proceso automático**:
  * Genera número de orden: OC-000001
  * Calcula totales automáticamente
  * Método calcularSaldoPendiente() para control de pagos
* **Transacciones**: Rollback automático en caso de error

### 9. **AuthController** ⚠️ (Ya existía)

* **Rutas**: `/api/login`, `/api/register`, `/api/logout`, `/api/user`
* **Funcionalidades**:
  * Login con Laravel Sanctum
  * Registro de usuarios
  * Logout
  * Obtener usuario autenticado

***

## 📊 Estadísticas

* **Total de controladores**: 9
* **Total de rutas API**: 44
* **Rutas protegidas**: 42 (requieren autenticación)
* **Rutas públicas**: 2 (login, register)

### Desglose de rutas por controlador:

| Controlador    | GET    | POST   | PUT/PATCH | DELETE | Total  |
| -------------- | ------ | ------ | --------- | ------ | ------ |
| Empresas       | 2      | 1      | 1         | 1      | 5      |
| Sucursales     | 2      | 1      | 1         | 1      | 5      |
| Almacenes      | 2      | 1      | 1         | 1      | 5      |
| Productos      | 2      | 1      | 1         | 1      | 5      |
| Clientes       | 2      | 1      | 1         | 1      | 5      |
| Proveedores    | 2      | 1      | 1         | 1      | 5      |
| Ventas         | 2      | 1      | 1         | 1      | 5      |
| Órdenes Compra | 2      | 1      | 1         | 1      | 5      |
| Auth           | 2      | 2      | 0         | 0      | 4      |
| **TOTAL**      | **18** | **10** | **8**     | **8**  | **44** |

***

## 🔒 Características de Seguridad Implementadas

### 1. **Autenticación**

* ✅ Laravel Sanctum en todos los endpoints (excepto login/register)
* ✅ Bearer token authentication
* ✅ Middleware auth:sanctum

### 2. **Validación**

* ✅ Validación robusta con Validator::make()
* ✅ Mensajes de error estructurados (422)
* ✅ Validaciones personalizadas (ej: identificación única por empresa)

### 3. **Soft Deletes**

* ✅ Todos los controladores usan soft delete
* ✅ Campos: activo (boolean), eliminado (boolean)
* ✅ Nunca se elimina físicamente del registro

### 4. **Transacciones**

* ✅ DB::beginTransaction() en operaciones complejas
* ✅ Rollback automático en caso de error
* ✅ Integridad de datos garantizada

### 5. **Eager Loading**

* ✅ Carga anticipada de relaciones con with()
* ✅ Evita problema N+1
* ✅ Optimización de consultas

### 6. **Paginación**

* ✅ Todos los listados usan paginate()
* ✅ Default: 15 registros por página
* ✅ Parámetro configurable: per\_page

### 7. **Manejo de Errores**

* ✅ Try-catch en todos los métodos
* ✅ Mensajes de error descriptivos
* ✅ Status codes HTTP apropiados:
  * 200: OK
  * 201: Created
  * 404: Not Found
  * 422: Validation Error
  * 500: Server Error

***

## 📝 Validaciones Implementadas

### Empresas

```php
'nombre' => 'required|string|max:255'
'razon_social' => 'required|string|max:255'
'nit_ruc' => 'required|string|max:50|unique:empresas,nit_ruc'
'regimen_tributario_id' => 'required|exists:regimen_tributario,id'
'email' => 'nullable|email|max:255'
'sitio_web' => 'nullable|url|max:255'
```

### Productos

```php
'empresa_id' => 'required|exists:empresas,id'
'categoria_id' => 'required|exists:categorias_productos,id'
'unidad_medida_id' => 'required|exists:unidades_medida,id'
'tipo' => 'required|in:producto,servicio'
'precio_compra' => 'nullable|numeric|min:0'
'precio_venta' => 'required|numeric|min:0'
'stock_minimo' => 'nullable|integer|min:0'
```

### Clientes

```php
'tipo_identificacion' => 'required|in:fisica,juridica,dimex,nite,extranjero'
'identificacion' => 'required|string|max:50' // Único por empresa
'email' => 'nullable|email|max:255'
'limite_credito' => 'nullable|numeric|min:0'
'dias_credito' => 'nullable|integer|min:0'
```

### Ventas

```php
'fecha_venta' => 'required|date'
'tipo_comprobante' => 'required|in:factura,tiquete,nota_credito,nota_debito'
'detalles' => 'required|array|min:1'
'detalles.*.producto_id' => 'required|exists:productos,id'
'detalles.*.cantidad' => 'required|numeric|min:0.01'
'detalles.*.precio_unitario' => 'required|numeric|min:0'
'detalles.*.porcentaje_impuesto' => 'nullable|numeric|min:0|max:100'
```

### Órdenes de Compra

```php
'fecha_orden' => 'required|date'
'fecha_entrega_estimada' => 'nullable|date|after_or_equal:fecha_orden'
'estado' => 'required|in:borrador,pendiente,aprobada,recibida,cancelada'
'detalles' => 'required|array|min:1'
```

***

## 🎨 Patrones de Diseño Aplicados

### 1. **Repository Pattern (implícito)**

* Controladores delgados
* Lógica de negocio en modelos
* Separación de responsabilidades

### 2. **Service Layer (para operaciones complejas)**

* Generación de números de comprobante
* Cálculo de totales
* Normalización de datos

### 3. **Scopes de Eloquent**

* `activos()`
* `porEmpresa($id)`
* `porCategoria($id)`
* `porTipo($tipo)`
* `pendientes()`

### 4. **Traits**

* `CustomTimestamps`
* `CustomSoftDeletes`
* `BelongsToTenant`

### 5. **Response Pattern**

* Respuestas JSON consistentes
* Estructura estándar: `{message, data, errors}`
* HTTP status codes apropiados

***

## 🚀 Próximos Pasos Recomendados

### 1. ✅ **Autenticación y RBAC** (COMPLETADO - FASE 3)

* ✅ Laravel Sanctum implementado
* ✅ Sistema RBAC con 68 permisos
* ✅ Middleware CheckPermission
* ✅ AuthController (login, logout, me)
* ✅ 9 seeders con 112 registros

### 2. **Tests** (Prioridad Alta - FASE 4 EN PROGRESO)

```bash
# Tests de autenticación
php artisan make:test AuthenticationTest
php artisan make:test PermissionTest
php artisan make:test RBACTest

# Tests de controladores
php artisan make:test ProductoControllerTest
php artisan make:test VentaControllerTest

# Tests unitarios
php artisan make:test ProductoTest --unit
php artisan make:test UsuarioTest --unit
```

### 3. **Documentación API con Swagger** (Prioridad Alta - FASE 5)

* Implementar Swagger/OpenAPI
* Usar Laravel Scribe o L5-Swagger
* Documentar todos los endpoints con ejemplos
* Incluir información de autenticación y permisos

### 4. **FormRequests** (Prioridad Media - Mayormente completado)

Crear clases de validación dedicadas:

```bash
php artisan make:request StoreProductoRequest
php artisan make:request UpdateProductoRequest
```

### 5. **API Resources** (Prioridad Media)

Para serialización consistente de respuestas:

```bash
php artisan make:resource ProductoResource
php artisan make:resource ProductoCollection
```

### 6. **Policies** (Prioridad Media)

Para autorización granular:

```bash
php artisan make:policy ProductoPolicy --model=Producto
php artisan make:policy VentaPolicy --model=Venta
```

### 7. **Observers** (Prioridad Baja)

Para eventos de modelos:

```bash
php artisan make:observer ProductoObserver --model=Producto
```

### 8. **Rate Limiting** (Prioridad Baja)

* Configurar throttle en rutas API
* Prevenir abuso de endpoints
* Implementar límites por rol

### 9. **API Versioning** (Prioridad Baja)

* Implementar versionado: `/api/v1/productos`
* Mantener compatibilidad hacia atrás

***

## 📚 Archivos de Documentación Creados

1. ✅ **README.md** - Documentación principal del proyecto (actualizada FASE 1, 2, 3)
2. ✅ **API\_DOCUMENTATION.md** - Documentación completa de endpoints (actualizada con auth)
3. ✅ **MODELS\_RELATIONS.md** - Documentación de relaciones de modelos (actualizada RBAC)
4. ✅ **DATABASE\_README.md** - Documentación de base de datos (actualizada seeders)
5. ✅ **CONTROLLERS\_SUMMARY.md** - Este archivo (actualizado AuthController)
6. ✅ **FASE\_3\_COMPLETADA.md** - Reporte de FASE 3 (autenticación y RBAC)
7. ✅ **FORMREQUESTS\_SUMMARY.md** - Resumen de FormRequests
8. ✅ **FORMREQUESTS\_USAGE\_GUIDE.md** - Guía de uso de FormRequests
9. ✅ **CONTRIBUTING.md** - Guía de contribución

***

## 🎯 Resumen Ejecutivo

Se ha completado exitosamente la implementación de **10 controladores API** completamente funcionales con:

✅ **Sistema de Autenticación (FASE 3)**

* Laravel Sanctum para tokens API
* 68 permisos granulares (17 módulos × 4 acciones)
* 7 roles predefinidos
* Middleware CheckPermission
* Usuario admin con todos los permisos

✅ **47+ rutas API** registradas y operativas (incluyendo auth) ✅ **Validación robusta** en todos los endpoints ✅ **Soft deletes** implementado consistentemente ✅ **Eager loading** para optimización de consultas ✅ **Transacciones** en operaciones críticas ✅ **Paginación** en todos los listados ✅ **Búsqueda y filtros** avanzados ✅ **Manejo de errores** apropiado ✅ **Generación automática** de números de comprobante/orden ✅ **Cálculo automático** de totales en ventas y órdenes ✅ **Lógica de negocio** implementada (sucursal/almacén principal, validaciones únicas, etc.) ✅ **Protección por permisos** en rutas críticas

**Estado del proyecto**:

* ✅ **FASE 1**: Correcciones críticas (COMPLETADA)
* ✅ **FASE 2**: Datos maestros con seeders - 96 registros (COMPLETADA)
* ✅ **FASE 3**: Autenticación y RBAC - 112 registros totales (COMPLETADA)
* 🔄 **FASE 4**: Testing (EN PROGRESO)
* 📝 **FASE 5**: Documentación API con Swagger (PENDIENTE)

**Base de datos:** 112 registros cargados (96 maestros + 16 demo/test) **Credenciales de prueba:** <admin@senselab.com> / admin123 (68 permisos)

***

## 📞 Contacto y Soporte

**Senselab**

* Email: <deadmooncr@gmail.com>
* Web: [senselab.com](https://senselab.com)
* GitHub: [github.com/SenseLab-dev](https://github.com/orgs/SenseLab-dev)

***

*Documento actualizado: 20 de noviembre de 2025*\
\&#xNAN;*Hacemos cosas con sentido — Senselab*


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://senselab.gitbook.io/senselab-docs/docs/api/controllers_summary.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.