Companies

Tag: companies
Descripción: Operaciones para gestión de empresas en el sistema

---

1. Crear nueva empresa (POST /companies)

• Descripción: Registra una nueva empresa en el sistema
• Operation ID: CompaniesController_create
• Autenticación requerida: 🔒 Sí (ROLE_ADMIN)

Request Body

{
    "name": "Tech Solutions Inc.",
    "legalName": "Tech Solutions Incorporated",
    "taxId": "TECH123456789",
    "address": "123 Business Ave, New York",
    "phone": "+1 555 123 4567",
    "email": "contact@techsolutions.com",
    "website": "https://techsolutions.com",
    "isActive": true
}

Responses

Código	Descripción
201	Empresa creada exitosamente
400	Datos de entrada inválidos
401	No autorizado
409	Empresa ya existe

---

2. Listar todas las empresas (GET /companies)

• Descripción: Obtiene todas las empresas registradas con paginación
• Operation ID: CompaniesController_findAll
• Autenticación requerida: 🔒 Sí (ROLE_ADMIN o ROLE_COMPANY_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)
activeOnly	boolean	❌ No	Filtrar solo empresas activas
search	string	❌ No	Buscar por nombre o taxId

Responses

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

---

3. Obtener empresa por ID (GET /companies/:id)

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

Path Parameters

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

Responses

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

---

4. Actualizar empresa (PATCH /companies/:id)

• Descripción: Actualiza los datos de una empresa existente
• Operation ID: CompaniesController_update
• Autenticación requerida: 🔒 Sí (ROLE_ADMIN)

Path Parameters

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

Request Body

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

Responses

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

---

5. Eliminar empresa (DELETE /companies/:id)

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

Path Parameters

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

Responses

Código	Descripción
204	Empresa desactivada exitosamente
401	No autorizado
404	Empresa no encontrada
409	Empresa no puede ser desactivada (tiene sucursales activas)

---

6. Obtener sucursales de empresa (GET /companies/:id/branches)

• Descripción: Lista todas las sucursales asociadas a una empresa
• Operation ID: CompaniesController_findCompanyBranches
• Autenticación requerida: 🔒 Sí (ROLE_ADMIN o ROLE_COMPANY_VIEWER)

Path Parameters

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

Responses

Código	Descripción
200	Sucursales obtenidas exitosamente
401	No autorizado
404	Empresa no encontrada

---

Resumen de Endpoints de Companies

Método	Endpoint	Descripción	Permiso Requerido
POST	/companies	Crear nueva empresa	ROLE_ADMIN
GET	/companies	Listar todas las empresas	ROLE_ADMIN/COMPANY_VIEWER
GET	/companies/:id	Obtener empresa por ID	ROLE_ADMIN/COMPANY_VIEWER
PATCH	/companies/:id	Actualizar empresa	ROLE_ADMIN
DELETE	/companies/:id	Desactivar empresa	ROLE_ADMIN
GET	/companies/:id/branches	Obtener sucursales de la empresa	ROLE_ADMIN/COMPANY_VIEWER

Modelo de Datos

interface Company {
    id: number;
    name: string;
    legalName: string;
    taxId: string;
    address: string;
    phone: string;
    email: string;
    website: string;
    isActive: boolean;
    createdAt: string; // ISO 8601
    updatedAt: string; // ISO 8601
    deletedAt: string | null; // ISO 8601
    branches?: Branch[]; // Relación opcional
}

Ejemplo de Respuesta Completa

{
    "id": 1,
    "name": "Tech Solutions Inc.",
    "legalName": "Tech Solutions Incorporated",
    "taxId": "TECH123456789",
    "address": "123 Business Ave, New York",
    "phone": "+1 555 123 4567",
    "email": "contact@techsolutions.com",
    "website": "https://techsolutions.com",
    "isActive": true,
    "createdAt": "2023-01-15T10:30:00.000Z",
    "updatedAt": "2023-05-20T14:15:00.000Z",
    "deletedAt": null,
    "branches": [
        {
            "id": 1,
            "name": "Sucursal Central",
            "code": "TC-NY-001"
        }
    ]
}

Reglas de Validación

1. Datos requeridos:

   • Nombre, nombre legal y taxId son obligatorios
   • TaxId debe ser único en el sistema

2. Formatos:

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

3. Restricciones:

   • No se puede eliminar una empresa con sucursales activas
   • Solo admins pueden modificar/eliminar empresas
   • El taxId no puede modificarse después de creación

Consideraciones de Seguridad

1. Protección de datos:

   • Los datos fiscales son sensibles y deben protegerse
   • Considerar enmascarar taxId en respuestas para ciertos roles

2. Integridad referencial:

   • Las empresas no se eliminan físicamente (soft delete)
   • Validar relaciones antes de desactivar

3. Auditoría:

   • Registrar quién crea/modifica/desactiva empresas
   • Mantener historial de cambios importantes