Etusivu Tutki Apua
Rekisteröidy Kirjaudu sisään
Masterstreet
/
pedidos-express
1
0
Haarauta 0
Tiedostot Esitykset 0 Vetopyynnöt 0 Wiki
Puu: b169a08cf6
Haarat Tunnisteet
pedidos-express
/
doc_api.md

doc_api.md 9.7 KB
Historia Raaka

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",
"price": 1500.0,
"description": "Descripción del producto"
}
],
"message": "Productos obtenidos exitosamente"
}

🛒 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)

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

  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

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