Branches

Tag: branches
Descripción: Operaciones para gestión de sucursales de empresas

---

1. Crear nueva sucursal (POST /branches)

• Descripción: Registra una nueva sucursal para una empresa
• Operation ID: BranchesController_create
• Autenticación requerida: 🔒 Sí (ROLE_ADMIN o ROLE_BRANCH_MANAGER)

Request Body

{
    "name": "Sucursal Centro",
    "code": "MAIN-001",
    "address": "Av. Principal 123",
    "phone": "+1 555 123 4567",
    "email": "centro@empresa.com",
    "companyId": 1,
    "isActive": true
}

Responses

Código	Descripción
201	Sucursal creada exitosamente
400	Datos de entrada inválidos
401	No autorizado
404	Empresa no encontrada

---

2. Listar todas las sucursales (GET /branches)

• Descripción: Obtiene todas las sucursales con filtros avanzados
• Operation ID: BranchesController_findAll
• Autenticación requerida: 🔒 Sí (ROLE_ADMIN o ROLE_BRANCH_VIEWER)

Query Parameters

Parámetro	Tipo	Requerido	Descripción
page	integer	❌ No	Número de página (default: 1)
limit	integer	❌ No	Límite por página (default: 20)
companyId	integer	❌ No	Filtrar por ID de empresa
activeOnly	boolean	❌ No	Filtrar solo sucursales activas
search	string	❌ No	Buscar por nombre o código

Responses

Código	Descripción
200	Lista de sucursales obtenida
401	No autorizado

---

3. Obtener sucursal por ID (GET /branches/:id)

• Descripción: Obtiene los detalles completos de una sucursal específica
• Operation ID: BranchesController_findOne
• Autenticación requerida: 🔒 Sí (ROLE_ADMIN o ROLE_BRANCH_VIEWER)

Path Parameters

Parámetro	Tipo	Descripción
id	integer	ID de la sucursal

Responses

Código	Descripción
200	Sucursal obtenida exitosamente
401	No autorizado
404	Sucursal no encontrada

---

4. Actualizar sucursal (PATCH /branches/:id)

• Descripción: Actualiza los datos de una sucursal existente
• Operation ID: BranchesController_update
• Autenticación requerida: 🔒 Sí (ROLE_ADMIN o ROLE_BRANCH_MANAGER)

Path Parameters

Parámetro	Tipo	Descripción
id	integer	ID de la sucursal

Request Body

{
    "phone": "+1 555 987 6543",
    "email": "nuevoemail@empresa.com",
    "isActive": false
}

Responses

Código	Descripción
200	Sucursal actualizada exitosamente
400	Datos de entrada inválidos
401	No autorizado
404	Sucursal no encontrada

---

5. Eliminar sucursal (DELETE /branches/:id)

• Descripción: Desactiva una sucursal (soft delete)
• Operation ID: BranchesController_remove
• Autenticación requerida: 🔒 Sí (ROLE_ADMIN)

Path Parameters

Parámetro	Tipo	Descripción
id	integer	ID de la sucursal

Responses

Código	Descripción
204	Sucursal desactivada exitosamente
401	No autorizado
404	Sucursal no encontrada
409	Sucursal no puede ser desactivada (tiene usuarios asignados)

---

6. Obtener usuarios de sucursal (GET /branches/:id/users)

• Descripción: Lista todos los usuarios asociados a una sucursal
• Operation ID: BranchesController_findBranchUsers
• Autenticación requerida: 🔒 Sí (ROLE_ADMIN o ROLE_BRANCH_MANAGER)

Path Parameters

Parámetro	Tipo	Descripción
id	integer	ID de la sucursal

Responses

Código	Descripción
200	Usuarios obtenidos exitosamente
401	No autorizado
404	Sucursal no encontrada

---

Resumen de Endpoints de Branches

Método	Endpoint	Descripción	Permiso Requerido
POST	/branches	Crear nueva sucursal	ROLE_ADMIN/BRANCH_MANAGER
GET	/branches	Listar todas las sucursales	ROLE_ADMIN/BRANCH_VIEWER
GET	/branches/:id	Obtener sucursal por ID	ROLE_ADMIN/BRANCH_VIEWER
PATCH	/branches/:id	Actualizar sucursal	ROLE_ADMIN/BRANCH_MANAGER
DELETE	/branches/:id	Desactivar sucursal	ROLE_ADMIN
GET	/branches/:id/users	Obtener usuarios de la sucursal	ROLE_ADMIN/BRANCH_MANAGER

Modelo de Datos

interface Branch {
    id: number;
    name: string;
    code: string;
    address: string;
    phone: string;
    email: string;
    isActive: boolean;
    companyId: number;
    createdAt: string; // ISO 8601
    updatedAt: string; // ISO 8601
    deletedAt: string | null; // ISO 8601
    company?: Company;  // Relación opcional
    users?: User[];     // Relación opcional
}

Ejemplo de Respuesta Completa

{
    "id": 1,
    "name": "Sucursal Centro",
    "code": "MAIN-001",
    "address": "Av. Principal 123",
    "phone": "+1 555 123 4567",
    "email": "centro@empresa.com",
    "isActive": true,
    "companyId": 1,
    "createdAt": "2023-02-10T09:15:00.000Z",
    "updatedAt": "2023-05-18T14:30:00.000Z",
    "deletedAt": null,
    "company": {
        "id": 1,
        "name": "Empresa Principal"
    },
    "users": [
        {
            "id": 101,
            "name": "Gerente Sucursal",
            "email": "gerente@empresa.com"
        }
    ]
}

Reglas de Validación

1. Datos requeridos:

   • Nombre, código y companyId son obligatorios
   • Código debe ser único por empresa

2. Formatos:

   • Email debe ser válido (opcional)
   • Teléfono debe seguir formato internacional (opcional)

3. Restricciones:

   • No se puede eliminar una sucursal con usuarios asignados
   • Solo ciertos roles pueden modificar/eliminar sucursales
   • El código no puede modificarse después de creación