## **Diseño de API RESTful**

### **1. Autenticación y Gestión de Sesiones**

#### **1.1. Inicio de sesión**

**Endpoint:**  
`POST /api/auth/login`

**Solicitud:**

```json
{
  "email": "usuario@empresa.com",
  "password": "contraseña_segura"
}
```

**Respuesta:**

```json
{
  "token": "eyJhbGciOi...",
  "user": {
    "id": 123,
    "username": "usuario",
    "email": "usuario@empresa.com"
  },
  "companies": [
    { "id": 1, "name": "Empresa A" },
    { "id": 2, "name": "Empresa B" }
  ]
}
```

---

#### **1.2. Cierre de sesión**

**Endpoint:**  
`POST /api/auth/logout`

**Encabezados:**

```
Authorization: Bearer <token>
```

**Respuesta:**

```json
{
  "message": "Sesión cerrada exitosamente"
}
```

---

#### **1.3. Selección de empresa activa**

**Endpoint:**  
`POST /api/auth/select-company`

**Solicitud:**

```json
{
  "company_id": 1
}
```

**Respuesta:**

```json
{
  "message": "Empresa seleccionada exitosamente"
}
```

---

### **2. Gestión de Empresas**

#### **2.1. Listar empresas disponibles**

**Endpoint:**  
`GET /api/companies`

**Encabezados:**

```
Authorization: Bearer <token>
```

**Respuesta:**

```json
[
  {
    "id": 1,
    "name": "Empresa A",
    "country_code": "ES",
    "currency_code": "EUR"
  },
  { "id": 2, "name": "Empresa B", "country_code": "US", "currency_code": "USD" }
]
```

---

#### **2.2. Crear una nueva empresa**

**Endpoint:**  
`POST /api/companies`

**Solicitud:**

```json
{
  "name": "Nueva Empresa",
  "country_code": "ES",
  "currency_code": "EUR"
}
```

**Respuesta:**

```json
{
  "id": 3,
  "message": "Empresa creada exitosamente"
}
```

---

#### **2.3. Actualizar datos de una empresa**

**Endpoint:**  
`PUT /api/companies/{company_id}`

**Solicitud:**

```json
{
  "name": "Empresa Actualizada",
  "currency_code": "USD"
}
```

**Respuesta:**

```json
{
  "message": "Empresa actualizada correctamente"
}
```

---

#### **2.4. Eliminar una empresa**

**Endpoint:**  
`DELETE /api/companies/{company_id}`

**Respuesta:**

```json
{
  "message": "Empresa eliminada exitosamente"
}
```

---

### **3. Gestión de Sucursales**

#### **3.1. Listar sucursales de una empresa**

**Endpoint:**  
`GET /api/companies/{company_id}/branches`

**Respuesta:**

```json
[
  { "id": 10, "name": "Sucursal Madrid" },
  { "id": 20, "name": "Sucursal Barcelona" }
]
```

---

#### **3.2. Crear una sucursal**

**Endpoint:**  
`POST /api/companies/{company_id}/branches`

**Solicitud:**

```json
{
  "name": "Sucursal Sevilla",
  "location": "Avenida Principal 123"
}
```

**Respuesta:**

```json
{
  "id": 30,
  "message": "Sucursal creada exitosamente"
}
```

---

#### **3.3. Actualizar datos de una sucursal**

**Endpoint:**  
`PUT /api/branches/{branch_id}`

**Solicitud:**

```json
{
  "name": "Sucursal Actualizada",
  "location": "Calle Nueva 456"
}
```

**Respuesta:**

```json
{
  "message": "Sucursal actualizada correctamente"
}
```

---

#### **3.4. Eliminar una sucursal**

**Endpoint:**  
`DELETE /api/branches/{branch_id}`

**Respuesta:**

```json
{
  "message": "Sucursal eliminada exitosamente"
}
```

---

### **4. Gestión de Usuarios**

#### **4.1. Listar usuarios de una empresa**

**Endpoint:**  
`GET /api/companies/{company_id}/users`

**Respuesta:**

```json
[
  {
    "id": 1,
    "username": "admin",
    "email": "admin@empresa.com",
    "roles": ["Administrador"]
  },
  {
    "id": 2,
    "username": "usuario",
    "email": "usuario@empresa.com",
    "roles": ["Ventas"]
  }
]
```

---

#### **4.2. Crear un usuario**

**Endpoint:**  
`POST /api/users`

**Solicitud:**

```json
{
  "username": "nuevo_usuario",
  "email": "nuevo@empresa.com",
  "password": "clave_segura",
  "company_id": 1,
  "roles": ["Ventas"]
}
```

**Respuesta:**

```json
{
  "id": 3,
  "message": "Usuario creado exitosamente"
}
```

---

#### **4.3. Actualizar usuario**

**Endpoint:**  
`PUT /api/users/{user_id}`

**Solicitud:**

```json
{
  "email": "nuevo_correo@empresa.com",
  "roles": ["Compras"]
}
```

**Respuesta:**

```json
{
  "message": "Usuario actualizado correctamente"
}
```

---

#### **4.4. Eliminar usuario**

**Endpoint:**  
`DELETE /api/users/{user_id}`

**Respuesta:**

```json
{
  "message": "Usuario eliminado exitosamente"
}
```

---

### **5. Gestión de Permisos**

#### **5.1. Obtener permisos de un usuario en una empresa**

**Endpoint:**  
`GET /api/companies/{company_id}/users/{user_id}/permissions`

**Respuesta:**

```json
{
  "modules": {
    "Presupuestos": ["read", "write"],
    "Facturas": ["read"],
    "Clientes": ["read", "write", "delete"]
  }
}
```

---

#### **5.2. Actualizar permisos de un usuario**

**Endpoint:**  
`PUT /api/users/{user_id}/permissions`

**Solicitud:**

```json
{
  "modules": {
    "Presupuestos": ["read", "write"],
    "Inventario": ["read"]
  }
}
```

**Respuesta:**

```json
{
  "message": "Permisos actualizados correctamente"
}
```

---

### **6. Auditoría**

#### **6.1. Obtener historial de cambios en documentos**

**Endpoint:**  
`GET /api/audit/documents/{document_id}`

**Respuesta:**

```json
[
  {
    "timestamp": "2025-01-22T14:00:00Z",
    "user": "admin",
    "change": "Se modificó el precio de 100 a 120"
  },
  {
    "timestamp": "2025-01-20T10:30:00Z",
    "user": "usuario",
    "change": "Se creó el documento"
  }
]
```