horux-strategy-platform/docs/04-api-reference.md

# 4. API Reference

## Base URL
```
http://localhost:8000/api
```

## Autenticación

Todos los endpoints (excepto login) requieren token Bearer:
```
Authorization: Bearer {token}
```

---

## Endpoints de Autenticación

### POST /login
Iniciar sesión

**Request:**
```json
{
  "email": "admin@horux360.com",
  "password": "password"
}
```

**Response 200:**
```json
{
  "user": {
    "id": 1,
    "nombre": "Administrador",
    "email": "admin@horux360.com",
    "role": "admin",
    "cliente_id": null
  },
  "token": "1|abc123..."
}
```

### POST /logout
Cerrar sesión (requiere autenticación)

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

### GET /user
Obtener usuario actual

**Response 200:**
```json
{
  "id": 1,
  "nombre": "Administrador",
  "email": "admin@horux360.com",
  "role": "admin",
  "cliente_id": null,
  "cliente": null
}
```

---

## Endpoints de Giros

### GET /giros
Listar giros activos

**Response 200:**
```json
[
  { "id": 1, "nombre": "Hotelería", "activo": true },
  { "id": 2, "nombre": "Comercio", "activo": true }
]
```

---

## Endpoints de Clientes

### GET /clientes
Listar clientes (filtrado por rol)

**Response 200:**
```json
[
  {
    "id": 1,
    "nombre_empresa": "Hotel Boutique HSA",
    "logo": "logos/abc123.png",
    "giro_id": 1,
    "moneda": "MXN",
    "giro": { "id": 1, "nombre": "Hotelería" }
  }
]
```

### POST /clientes
Crear cliente (multipart/form-data)

**Request:**
```
nombre_empresa: Hotel Ejemplo
giro_id: 1
moneda: MXN
logo: [archivo imagen]
```

**Response 201:**
```json
{
  "id": 2,
  "nombre_empresa": "Hotel Ejemplo",
  "giro_id": 1,
  "moneda": "MXN",
  "logo": "logos/xyz789.png"
}
```

### GET /clientes/{id}
Obtener cliente con balanzas y reportes

### PUT /clientes/{id}
Actualizar cliente

### DELETE /clientes/{id}
Eliminar cliente (solo admin)

---

## Endpoints de Balanzas

### GET /clientes/{id}/balanzas
Listar balanzas de un cliente

**Response 200:**
```json
[
  {
    "id": 1,
    "cliente_id": 1,
    "periodo_inicio": "2024-01-01",
    "periodo_fin": "2024-12-31",
    "sistema_origen": "contpaqi",
    "status": "completado"
  }
]
```

### POST /clientes/{id}/balanzas
Subir balanza (multipart/form-data)

**Request:**
```
archivo: [archivo PDF/Excel/CSV]
periodo_inicio: 2024-01-01
periodo_fin: 2024-12-31
```

**Response 201:**
```json
{
  "id": 2,
  "sistema_origen": "contpaqi",
  "status": "procesando"
}
```

### GET /balanzas/{id}/cuentas
Listar cuentas de una balanza

**Response 200:**
```json
[
  {
    "id": 1,
    "codigo": "001-100-000",
    "nombre": "ACTIVO CIRCULANTE",
    "nivel": 1,
    "saldo_final_deudor": 1500000.00,
    "saldo_final_acreedor": 0,
    "excluida": false,
    "es_cuenta_padre": true,
    "requiere_revision": false,
    "categoria_contable": {
      "id": 1,
      "nombre": "Activos Circulantes"
    }
  }
]
```

### PUT /balanzas/{id}/exclusiones
Actualizar cuentas excluidas

**Request:**
```json
{
  "exclusiones": [5, 12, 23]
}
```

---

## Endpoints de Cuentas

### PUT /cuentas/{id}/clasificacion
Corregir clasificación de cuenta

**Request:**
```json
{
  "reporte_contable_id": 1,
  "categoria_contable_id": 3,
  "requiere_revision": false
}
```

### POST /cuentas/{id}/toggle-exclusion
Alternar exclusión de cuenta

### GET /anomalias
Listar cuentas que requieren revisión

---

## Endpoints de Reportes

### GET /clientes/{id}/reportes
Listar reportes de un cliente

### POST /clientes/{id}/reportes
Generar nuevo reporte

**Request:**
```json
{
  "nombre": "Reporte Anual 2024",
  "balanza_ids": [1, 2, 3]
}
```

**Response 201:**
```json
{
  "id": 1,
  "nombre": "Reporte Anual 2024",
  "periodo_tipo": "anual",
  "status": "completado",
  "data_calculada": { ... }
}
```

### GET /reportes/{id}
Obtener reporte con datos calculados

### GET /reportes/{id}/pdf
Descargar PDF del reporte

**Response:** Archivo PDF

### DELETE /reportes/{id}
Eliminar reporte

---

## Endpoints de Administración

Requieren rol `admin`.

### Usuarios
- `GET /admin/usuarios` - Listar usuarios
- `POST /admin/usuarios` - Crear usuario
- `PUT /admin/usuarios/{id}` - Actualizar usuario
- `DELETE /admin/usuarios/{id}` - Eliminar usuario

### Giros
- `GET /admin/giros` - Listar todos los giros
- `POST /admin/giros` - Crear giro
- `PUT /admin/giros/{id}` - Actualizar giro
- `DELETE /admin/giros/{id}` - Eliminar giro

### Umbrales
- `GET /admin/umbrales` - Listar umbrales
- `POST /admin/umbrales` - Crear umbral
- `PUT /admin/umbrales/{id}` - Actualizar umbral
- `DELETE /admin/umbrales/{id}` - Eliminar umbral

### Reglas de Mapeo
- `GET /admin/reglas-mapeo` - Listar reglas
- `POST /admin/reglas-mapeo` - Crear regla
- `PUT /admin/reglas-mapeo/{id}` - Actualizar regla
- `DELETE /admin/reglas-mapeo/{id}` - Eliminar regla

---

## Códigos de Error

| Código | Descripción |
|--------|-------------|
| 401 | No autenticado |
| 403 | No autorizado |
| 404 | Recurso no encontrado |
| 422 | Error de validación |
| 500 | Error del servidor |

**Ejemplo error 422:**
```json
{
  "message": "The email field is required.",
  "errors": {
    "email": ["The email field is required."]
  }
}
```