# API Documentation - Web Pedidos Klein

## Información General

**Título:** Web Pedidos Klein - FastAPI Backend  
**Descripción:** Backend para la aplicación Web Pedidos Klein utilizando FastAPI  
**URL Base:** `http://localhost:8000` (o su dominio de producción)

## Autenticación
 
La API utiliza autenticación basada en tokens JWT. La mayoría de endpoints requieren autenticación a través del header:
```
Authorization: Bearer <token>
```

## Endpoints

### 🔐 Autenticación y Usuarios (`/api/users`)

#### Verificar existencia de usuario
- **POST** `/api/users/exists`
- **Descripción:** Verifica si un usuario existe por ID
- **Cuerpo de solicitud:**
  ```json
  {
    "id": 123
  }
  ```
- **Respuestas:**
  - `200`: Usuario existe
  - `404`: Usuario no encontrado

#### Registrar usuario
- **POST** `/api/users/register`
- **Descripción:** Registra un nuevo usuario y envía código de verificación por email
- **Cuerpo de solicitud:**
  ```json
  {
    "name": "Juan Pérez",
    "email": "juan@ejemplo.com",
    "rut": "12345678-9"
  }
  ```
- **Respuestas:**
  - `201`: Usuario registrado exitosamente
  - `400`: Usuario ya existe

#### Crear usuario con PIN
- **POST** `/api/users/create-user?q={verification_code}`
- **Descripción:** Completa el registro del usuario estableciendo un PIN de 4 dígitos
- **Parámetros de consulta:**
  - `q`: Código de verificación recibido por email
- **Cuerpo de solicitud:**
  ```json
  {
    "pin": "1234"
  }
  ```
- **Respuestas:**
  - `201`: Usuario creado exitosamente con token
  - `400`: PIN inválido o código de verificación expirado

#### Iniciar sesión
- **POST** `/api/users/login`
- **Descripción:** Autentica un usuario con email y PIN
- **Cuerpo de solicitud:**
  ```json
  {
    "email": "juan@ejemplo.com",
    "pin": "1234"
  }
  ```
- **Respuestas:**
  - `200`: Login exitoso con datos de usuario y token
  - `401`: Credenciales inválidas
  - `403`: Usuario bloqueado por intentos fallidos
  - `429`: Demasiados intentos de login

#### Eliminar usuario
- **DELETE** `/api/users/delete`
- **Descripción:** Elimina un usuario por ID
- **Cuerpo de solicitud:**
  ```json
  {
    "id": 123
  }
  ```
- **Respuestas:**
  - `200`: Usuario eliminado
  - `404`: Usuario no encontrado

#### Obtener todos los usuarios
- **GET** `/api/users/all`
- **Descripción:** Obtiene lista de todos los usuarios registrados
- **Respuestas:**
  - `200`: Lista de usuarios

### 📧 Verificación (`/verify`)

#### Verificar usuario
- **GET** `/verify/?q={verification_code}`
- **Descripción:** Página de verificación de usuario
- **Parámetros de consulta:**
  - `q`: Código de verificación
- **Respuestas:**
  - `200`: Página de verificación HTML
  - `400`: Código de verificación inválido

### 🛍️ Productos (`/api/products`)
*Requiere autenticación*

#### Obtener productos
- **GET** `/api/products/`
- **Descripción:** Obtiene lista de todos los productos disponibles
- **Headers requeridos:** `Authorization: Bearer <token>`
- **Respuestas:**
  - `200`: Lista de productos
  ```json
  {
    "products": [
      {
        "id": 1,
        "name": "Producto 1",
        "type": "bebida",
        "description": "Descripción del producto",
        "price": 1500.0,
        "image": "url_imagen.jpg",
        "status": 1,
        "quantity": 1
      }
    ],
    "message": "Productos obtenidos correctamente"
  }
  ```

#### Obtener producto específico
- **GET** `/api/products/{product_id}`
- **Descripción:** Obtiene un producto específico por su ID
- **Headers requeridos:** `Authorization: Bearer <token>`
- **Parámetros de ruta:**
  - `product_id`: ID del producto
- **Respuestas:**
  - `200`: Producto encontrado
  ```json
  {
    "product": {
      "id": 1,
      "name": "Producto 1",
      "type": "bebida",
      "description": "Descripción del producto",
      "price": 1500.0,
      "image": "url_imagen.jpg",
      "status": 1,
      "quantity": 1
    },
    "message": "Productos obtenidos correctamente"
  }
  ```
  - `404`: Producto no encontrado

#### Editar producto
- **PATCH** `/api/products/edit`
- **Descripción:** Edita un producto existente (requiere permisos de nivel 1 o superior)
- **Headers requeridos:** `Authorization: Bearer <token>`
- **Cuerpo de solicitud:**
  ```json
  {
    "id": 1,
    "name": "Producto Actualizado",
    "type": "comida",
    "description": "Nueva descripción",
    "price": 2000.0,
    "image": "nueva_imagen.jpg",
    "status": 1,
    "quantity": 5
  }
  ```
  **Nota:** Todos los campos excepto `id` son opcionales
- **Respuestas:**
  - `200`: Producto editado exitosamente
  - `403`: Sin permisos para realizar esta acción

#### Crear producto
- **POST** `/api/products/create`
- **Descripción:** Crea un nuevo producto (requiere permisos de nivel 1 o superior)
- **Headers requeridos:** `Authorization: Bearer <token>`
- **Cuerpo de solicitud:**
  ```json
  {
    "name": "Nuevo Producto",
    "type": "bebida",
    "description": "Descripción del nuevo producto",
    "price": 1800.0,
    "image": "imagen_producto.jpg",
    "status": 1,
    "quantity": 10
  }
  ```
- **Respuestas:**
  - `200`: Producto creado exitosamente
  - `403`: Sin permisos para realizar esta acción

#### Eliminar producto
- **DELETE** `/api/products/{product_id}`
- **Descripción:** Elimina un producto (requiere permisos de nivel 2 - administrador)
- **Headers requeridos:** `Authorization: Bearer <token>`
- **Parámetros de ruta:**
  - `product_id`: ID del producto a eliminar
- **Respuestas:**
  - `200`: Producto eliminado exitosamente
  - `403`: Sin permisos para realizar esta acción

### 🛒 Pedidos (`/api/orders`)
*Requiere autenticación*

#### Enviar pedido
- **POST** `/api/orders/send`
- **Descripción:** Procesa un pedido, lo envía al sistema Fudo y a la impresora
- **Headers requeridos:** `Authorization: Bearer <token>`
- **Cuerpo de solicitud:**
  ```json
  {
    "customerId": 123,
    "items": [
      {
        "id": 1,
        "quantity": 2
      },
      {
        "id": 2,
        "quantity": 1
      }
    ],
    "totalAmount": 4500.0,
    "orderDate": "2025-07-31T10:30:00",
    "table": 5
  }
  ```
- **Respuestas:**
  - `200`: Pedido procesado exitosamente
  - `400`: Campos faltantes o tipo de mesa inválido
  - `404`: Usuario no encontrado o venta activa no encontrada
  - `424`: Impresora desconectada o error agregando productos

### 💰 Ventas (`/api/sales`)
*Requiere autenticación*

#### Obtener ventas por usuario
- **GET** `/api/sales/user/{user_id}`
- **Descripción:** Obtiene el historial de ventas de un usuario específico
- **Headers requeridos:** `Authorization: Bearer <token>`
- **Parámetros de ruta:**
  - `user_id`: ID del usuario
- **Respuestas:**
  - `200`: Lista de ventas del usuario
  ```json
  {
    "sales": [
      {
        "id": 1,
        "user_id": 123,
        "total": 4500.0,
        "fudo_id": "abc123",
        "date": "2025-07-31T10:30:00",
        "table": 5,
        "username": "Juan Pérez",
        "user_email": "juan@ejemplo.com",
        "products": [...]
      }
    ],
    "message": "Ventas obtenidas correctamente"
  }
  ```
  - `404`: No se encontraron ventas

### 💬 Chat (`/api/chat`)
*Requiere autenticación*

#### Completar chat
- **POST** `/api/chat/completions`
- **Descripción:** Obtiene respuestas de chat utilizando OpenAI
- **Headers requeridos:** `Authorization: Bearer <token>`
- **Cuerpo de solicitud:**
  ```json
  {
    "messages": [
      {
        "role": "user",
        "content": "Hola, ¿qué productos tienen disponibles?"
      }
    ],
    "user": "juan@ejemplo.com"
  }
  ```
- **Respuestas:**
  - `200`: Respuesta del chat
  ```json
  {
    "response": "Respuesta generada por IA",
    "message": "Respuesta de chat generada exitosamente"
  }
  ```
  - `500`: Error interno del servidor

### 🌐 Rutas Estáticas

#### Página principal
- **GET** `/`
- **Descripción:** Sirve la página principal de la aplicación
- **Respuestas:**
  - `200`: Página HTML principal
  - `404`: Archivo no encontrado

#### Página de registro
- **GET** `/register`
- **Descripción:** Sirve la página de registro
- **Respuestas:**
  - `200`: Página HTML de registro
  - `404`: Archivo no encontrado

## Modelos de Datos

### Usuario (User)
```json
{
  "id": 123,
  "email": "usuario@ejemplo.com",
  "name": "Nombre Usuario",
  "rut": "12345678-9",
  "pin_hash": "hashed_pin_value",
  "kleincoins": "100.00",
  "created_at": "2025-07-31T10:30:00"
}
```

### Producto (Product)
```json
{
  "id": 1,
  "name": "Nombre del Producto",
  "type": "bebida",
  "description": "Descripción del producto",
  "price": 1500.0,
  "image": "url_imagen.jpg",
  "status": 1,
  "quantity": 1
}
```
**Campos:**
- `id`: Identificador único
- `name`: Nombre del producto
- `type`: Tipo/categoría del producto (opcional)
- `description`: Descripción del producto (opcional)
- `price`: Precio del producto
- `image`: URL de la imagen (opcional)
- `status`: Estado del producto (0: Inactivo, 1: Activo)
- `quantity`: Cantidad disponible (opcional, por defecto 1)

### Solicitud de Edición de Producto (ProductEditRequest)
```json
{
  "id": 1,
  "name": "Producto Actualizado",
  "type": "comida",
  "description": "Nueva descripción",
  "price": 2000.0,
  "image": "nueva_imagen.jpg",
  "status": 1,
  "quantity": 5
}
```
**Campos:**
- `id`: Identificador único (requerido)
- `name`: Nombre del producto (opcional)
- `type`: Tipo/categoría del producto (opcional)
- `description`: Descripción del producto (opcional)
- `price`: Precio del producto (opcional)
- `image`: URL de la imagen (opcional)
- `status`: Estado del producto (opcional) - 0: Inactivo, 1: Activo
- `quantity`: Cantidad disponible (opcional)

### Solicitud de Creación de Producto (ProductCreateRequest)
```json
{
  "name": "Nuevo Producto",
  "type": "bebida",
  "description": "Descripción del nuevo producto",
  "price": 1800.0,
  "image": "imagen_producto.jpg",
  "status": 1,
  "quantity": 10
}
```
**Campos:**
- `name`: Nombre del producto (requerido)
- `type`: Tipo/categoría del producto (requerido)
- `description`: Descripción del producto (requerido)
- `price`: Precio del producto (requerido)
- `image`: URL de la imagen (requerido)
- `status`: Estado del producto (opcional, por defecto 1) - 0: Inactivo, 1: Activo
- `quantity`: Cantidad disponible (opcional, por defecto 1)

### Pedido (OrderWeb)
```json
{
  "customerId": 123,
  "items": [
    {
      "id": 1,
      "quantity": 2
    }
  ],
  "totalAmount": 3000.0,
  "orderDate": "2025-07-31T10:30:00",
  "table": 5
}
```

### Item del Pedido (ItemWeb)
```json
{
  "id": 1,
  "quantity": 2
}
```

### Venta (Sale)
```json
{
  "id": 1,
  "user_id": 123,
  "total": 3000.0,
  "fudo_id": "abc123",
  "date": "2025-07-31T10:30:00",
  "table": 5,
  "username": "Juan Pérez",
  "user_email": "juan@ejemplo.com",
  "products": [
    {
      "id": 1,
      "name": "Producto 1",
      "price": 1500.0,
      "quantity": 2
    }
  ]
}
```

### Mensaje de Chat (Message)
```json
{
  "role": "user",
  "content": "¿Qué productos tienen disponibles?"
}
```
**Roles disponibles:** `user`, `assistant`, `system`

### Solicitud de Chat (ChatCompletionRequest)
```json
{
  "messages": [
    {
      "role": "user",
      "content": "Hola, necesito ayuda"
    }
  ],
  "user": "usuario@ejemplo.com"
}
```

### Lista Negra (Blacklist)
```json
{
  "id": 1,
  "user_id": 123,
  "email": "usuario@ejemplo.com",
  "name": "Juan Pérez",
  "rut": "12345678-9"
}
```
**Campos:**
- `id`: Identificador único
- `user_id`: ID del usuario en lista negra
- `email`: Email del usuario (opcional)
- `name`: Nombre del usuario (opcional)
- `rut`: RUT del usuario (opcional)

### Modelos de Solicitud

#### Registro de Usuario (RegisterUserRequest)
```json
{
  "name": "Juan Pérez",
  "email": "juan@ejemplo.com",
  "rut": "12345678-9"
}
```

#### Login de Usuario (LoginRequest)
```json
{
  "email": "juan@ejemplo.com",
  "pin": "1234"
}
```

#### PIN de Usuario (PinUserRequest)
```json
{
  "pin": "1234"
}
```
**Validación:** PIN debe ser exactamente 4 dígitos

#### ID de Usuario (UserIDRequest)
```json
{
  "id": 123
}
```

## Códigos de Error Comunes

- **400**: Solicitud incorrecta (datos faltantes o inválidos)
- **401**: No autorizado (token inválido o credenciales incorrectas)
- **403**: Prohibido (usuario bloqueado)
- **404**: No encontrado (recurso no existe)
- **424**: Dependencia fallida (problemas con servicios externos como impresora)
- **429**: Demasiadas solicitudes (límite de intentos alcanzado)
- **500**: Error interno del servidor

## Notas Importantes

1. **Autenticación**: La mayoría de endpoints requieren un token JWT válido
2. **Límites de intentos**: El sistema bloquea usuarios después de 5 intentos fallidos de login
3. **Verificación por email**: El registro requiere verificación por email antes de completarse
4. **Integración con Fudo**: Los pedidos se sincronizan automáticamente con el sistema Fudo
5. **Impresión automática**: Los pedidos se envían automáticamente a la impresora USB configurada
6. **Logs**: Todas las interacciones importantes se registran para auditoría
7. **Niveles de permisos**: 
   - **Nivel 0**: Usuario normal (solo consulta de productos)
   - **Nivel 1**: Usuario con permisos de edición (puede crear y editar productos)
   - **Nivel 2**: Administrador (puede eliminar productos)

## Middleware

- **SessionMiddleware**: Manejo de sesiones con tiempo de expiración de 60 minutos
- **CORS**: Configurado para permitir solicitudes cross-origin según necesidades

## Archivos Estáticos

- **Principales**: `/express/` - Archivos de la aplicación principal
- **Registro**: `/register/` - Archivos de la página de registro