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:
```
{
"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:

{
"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:
```
{
"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:

{
"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:
```
{
"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

{
"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

{
"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:

{
"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:

{
"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:

{
"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

{
"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:

{
"messages": [
  {
    "role": "user",
    "content": "Hola, ¿qué productos tienen disponibles?"
  }
],
"user": "juan@ejemplo.com"
}

Respuestas:

200: Respuesta del chat

{
"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)

{
  "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)

{
  "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)

{
  "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)

{
  "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)

{
  "customerId": 123,
  "items": [
    {
      "id": 1,
      "quantity": 2
    }
  ],
  "totalAmount": 3000.0,
  "orderDate": "2025-07-31T10:30:00",
  "table": 5
}

Item del Pedido (ItemWeb)

{
  "id": 1,
  "quantity": 2
}

Venta (Sale)

{
  "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)

{
  "role": "user",
  "content": "¿Qué productos tienen disponibles?"
}

Roles disponibles: user, assistant, system

Solicitud de Chat (ChatCompletionRequest)

{
  "messages": [
    {
      "role": "user",
      "content": "Hola, necesito ayuda"
    }
  ],
  "user": "usuario@ejemplo.com"
}

Lista Negra (Blacklist)

{
  "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)

{
  "name": "Juan Pérez",
  "email": "juan@ejemplo.com",
  "rut": "12345678-9"
}

Login de Usuario (LoginRequest)

{
  "email": "juan@ejemplo.com",
  "pin": "1234"
}

PIN de Usuario (PinUserRequest)

{
  "pin": "1234"
}

Validación: PIN debe ser exactamente 4 dígitos

ID de Usuario (UserIDRequest)

{
  "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

Autenticación: La mayoría de endpoints requieren un token JWT válido
Límites de intentos: El sistema bloquea usuarios después de 5 intentos fallidos de login
Verificación por email: El registro requiere verificación por email antes de completarse
Integración con Fudo: Los pedidos se sincronizan automáticamente con el sistema Fudo
Impresión automática: Los pedidos se envían automáticamente a la impresora USB configurada
Logs: Todas las interacciones importantes se registran para auditoría
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

doc_api.md 13 KB Historie Surový

API Documentation - Web Pedidos Klein

Información General

Autenticación

Endpoints

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

Verificar existencia de usuario

Registrar usuario

Crear usuario con PIN

Iniciar sesión

Eliminar usuario

Obtener todos los usuarios

📧 Verificación (/verify)

Verificar usuario

🛍️ Productos (/api/products)

Obtener productos

Obtener producto específico

Editar producto

Crear producto

Eliminar producto

🛒 Pedidos (/api/orders)

Enviar pedido

💰 Ventas (/api/sales)

Obtener ventas por usuario

💬 Chat (/api/chat)

Completar chat

🌐 Rutas Estáticas

Página principal

Página de registro

Modelos de Datos

Usuario (User)

Producto (Product)

Solicitud de Edición de Producto (ProductEditRequest)

Solicitud de Creación de Producto (ProductCreateRequest)

Pedido (OrderWeb)

Item del Pedido (ItemWeb)

Venta (Sale)

Mensaje de Chat (Message)

Solicitud de Chat (ChatCompletionRequest)

Lista Negra (Blacklist)

Modelos de Solicitud

Registro de Usuario (RegisterUserRequest)

Login de Usuario (LoginRequest)

PIN de Usuario (PinUserRequest)

ID de Usuario (UserIDRequest)

Códigos de Error Comunes

Notas Importantes

Middleware

Archivos Estáticos

doc_api.md 13 KB

Historie Surový

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

📧 Verificación (`/verify`)

🛍️ Productos (`/api/products`)

🛒 Pedidos (`/api/orders`)

💰 Ventas (`/api/sales`)

💬 Chat (`/api/chat`)