{
  "name": "IA_PosCloud_API",
  "description": "API Oficial para que cualquier agente de Inteligencia Artificial interactúe con el inventario, ventas, rotación y traslados de productos del sistema POS. El agente debe usar exclusivamente estos endpoints.",
  "base_url": "https://administracion.posnube2.xyz",
  "authentication": {
    "type": "Bearer",
    "token_asignado": "token_ejemplo_ia_123",
    "description": "Debes usar SIEMPRE el 'token_asignado' enviándolo como query param (?token=token_ejemplo_ia_123) o en el Header (Authorization: Bearer token_ejemplo_ia_123) en tus peticiones."
  },
  "endpoints": [
    {
      "name": "Consultar Inventario",
      "method": "GET",
      "path": "/api/ia/inventario",
      "description": "Obtiene el inventario en tiempo real con sus precios de venta (VentaCaja, VentaFrcc, VentaCaja2, VentaFrcc2, VentaCaja3, VentaFrcc3). Soporta filtros opcionales.",
      "parameters": {
        "bodega": "(Opcional) ID de la bodega. Ejemplo: 1",
        "codigo": "(Opcional) Código de producto.",
        "nombre": "(Opcional) Fragmento del nombre del producto a buscar.",
        "modificado_hoy": "(Opcional) Enviar 1 para filtrar únicamente productos que tuvieron ventas o entradas en el día.",
        "desde_fecha": "(Opcional) Filtrar productos con movimientos desde esta fecha/hora (YYYY-MM-DD HH:MM:SS)."
      }
    },
    {
      "name": "Consultar Cambios de Inventario (Optimizado)",
      "method": "GET",
      "path": "/api/ia/inventario-cambios",
      "description": "Obtiene únicamente los productos del inventario que tuvieron ventas o entradas durante el día (o desde una fecha). Endpoint optimizado para reducir uso de CPU y memoria.",
      "parameters": {
        "bodega": "(Opcional) ID de la bodega. Ejemplo: 1",
        "modificado_hoy": "(Opcional) Enviar 1 para filtrar cambios de hoy.",
        "desde_fecha": "(Opcional) Fecha u hora inicial YYYY-MM-DD HH:MM:SS."
      }
    },
    {
      "name": "Consultar Ventas y Estadísticas Globales",
      "method": "GET",
      "path": "/api/ia/ventas",
      "description": "Devuelve las métricas principales de negocio (KPIs, totales de dinero, costos, utilidad, ventas por categoría y marca) en un periodo.",
      "parameters": {
        "fi": "(Opcional) Fecha inicial YYYY-MM-DD.",
        "ff": "(Opcional) Fecha final YYYY-MM-DD."
      }
    },
    {
      "name": "Consultar Rotación de Unidades",
      "method": "GET",
      "path": "/api/ia/rotacion",
      "description": "Obtiene los productos con más movimiento en UNIDADES FÍSICAS (calculando ventas netas). Devuelve la rotación global del producto Y UN DESGLOSE por bodega indicando cuánto rotó en cada bodega y el INVENTARIO ACTUAL. IMPORTANTE: También incluye productos que tienen inventario pero SIN rotación (ventas = 0), para identificar productos estancados. Esto es CRUCIAL para tomar decisiones de traslados.",
      "parameters": {
        "bodega": "(Opcional) Filtrar por una bodega específica.",
        "codigo": "(Opcional) Filtrar por código de barras o código interno.",
        "nombre": "(Opcional) Término de búsqueda universal. Busca coincidencias en: Nombre del producto, Marca, Categoría o Código.",
        "fecha_inicio": "(Opcional) Fecha de inicio YYYY-MM-DD.",
        "fecha_fin": "(Opcional) Fecha de fin YYYY-MM-DD.",
        "limit": "(Opcional) Limita la cantidad de registros. RECOMENDACIÓN PARA LA IA: Usa limit=60 para no saturar tu contexto y navega por páginas.",
        "page": "(Opcional) Número de página a consultar cuando usas limit. Por defecto es 1."
      }
    },
    {
      "name": "Crear Traslado (Mover inventario)",
      "method": "POST",
      "path": "/api/ia/traslados",
      "description": "Descuenta productos de una bodega_salida y los transfiere a una bodega_entrada. Solo necesitas saber qué código, cuántas cajas y cuántas fracciones se van a mover. ¡IMPORTANTE! Al finalizar, lee las reglas en ai_instructions.",
      "headers": {
        "Content-Type": "application/json"
      },
      "body_example": {
        "bodega_salida": 1,
        "bodega_entrada": 2,
        "productos": [
          {
            "codigo": "7702001",
            "caja": 5,
            "frcc": 0
          }
        ]
      }
    },
    {
      "name": "Finalizar y Guardar Traslado (OBLIGATORIO)",
      "method": "POST",
      "path": "/api/ia/traslados/guardar",
      "description": "Cierra el consecutivo del traslado en la base de datos. Solo ocupa el id de la bodega_salida.",
      "headers": {
        "Content-Type": "application/json"
      },
      "body_example": {
        "bodega_salida": 1
      }
    },
    {
      "name": "Consultar Clientes",
      "method": "GET",
      "path": "/api/ia/clientes",
      "description": "Busca clientes por cédula/identificación, teléfono o nombre (búsqueda parcial en Nombre, apellido o Alias).",
      "parameters": {
        "cedula": "(Opcional) Cédula o NIT exacto del cliente.",
        "telefono": "(Opcional) Número de teléfono/celular (búsqueda parcial).",
        "nombre": "(Opcional) Término para buscar por nombre, apellido o alias del cliente.",
        "limit": "(Opcional) Límite de registros. Por defecto 50.",
        "page": "(Opcional) Número de página a consultar. Por defecto 1."
      }
    },
    {
      "name": "Crear Cliente",
      "method": "POST",
      "path": "/api/ia/clientes",
      "description": "Crea y registra un nuevo cliente en el sistema POS.",
      "headers": {
        "Content-Type": "application/json"
      },
      "body_example": {
        "cedula": "12345678",
        "nombre": "Juan Carlos",
        "apellido": "Pérez Gómez",
        "telefono": "3001234567",
        "direccion": "Calle 45 # 12-34",
        "correo": "juan.perez@email.com",
        "codigociudad": "11001",
        "fechaNacimiento": "1992-08-20"
      }
    },
    {
      "name": "Consultar Ventas Detalladas por Cliente",
      "method": "GET",
      "path": "/api/ia/ventas-clientes",
      "description": "Obtiene qué productos se le vendieron a cada cliente en un rango de fechas con cálculo neto de devoluciones (cajas, fracciones, precios facturados, bodega de despacho) y datos básicos del cliente (sin crédito).",
      "parameters": {
        "fi": "(Opcional) Fecha inicial YYYY-MM-DD. Por defecto hace 30 días.",
        "ff": "(Opcional) Fecha final YYYY-MM-DD. Por defecto hoy.",
        "cliente": "(Opcional) Cédula, NIT o teléfono para filtrar un cliente específico.",
        "nombre": "(Opcional) Término para buscar por nombre, apellido o alias del cliente.",
        "producto": "(Opcional) Término para buscar por código o nombre de producto.",
        "bodega": "(Opcional) ID de bodega a consultar.",
        "limit": "(Opcional) Límite de clientes por página. Por defecto 50.",
        "page": "(Opcional) Número de página. Por defecto 1."
      }
    }
  ],
  "ai_instructions": [
    "REGLA 1: Si el usuario quiere ver métricas monetarias (cuánto dinero se vendió, utilidad, estadísticas), USA EL ENDPOINT /api/ia/ventas.",
    "REGLA 2: Si el usuario quiere ver unidades físicas movidas (qué productos rotaron más, cuántas cajas se vendieron netas), USA EL ENDPOINT /api/ia/rotacion.",
    "REGLA 3 – TRASLADOS (MUY IMPORTANTE, SIGUE ESTOS PASOS AL PIE DE LA LETRA):",
    "  PASO 1: Agrupa TODOS los productos que van de la MISMA bodega_salida a la MISMA bodega_entrada en UN SOLO POST a /api/ia/traslados. El campo 'productos' es un ARRAY, mete ahí todos los productos del mismo par origen→destino.",
    "  PASO 2: Si hay traslados a DIFERENTES pares de bodegas (ej: bodega 1→3 y bodega 5→2), haz un POST separado para CADA par.",
    "  PASO 3: Después de CADA POST exitoso a /api/ia/traslados, DEBES ejecutar INMEDIATAMENTE /api/ia/traslados/guardar con la bodega_salida correspondiente para CERRAR ese traslado. NO esperes, NO preguntes al usuario, CIÉRRALO.",
    "  PASO 4: Repite PASO 2 y PASO 3 para cada par de bodegas diferente.",
    "  PASO 5: Al final de todo, muestra un resumen de los traslados realizados.",
    "  EJEMPLO: Si quieres mover Producto-A y Producto-B de bodega 1 a bodega 3, y Producto-C de bodega 5 a bodega 2:",
    "    → POST /api/ia/traslados {bodega_salida:1, bodega_entrada:3, productos:[{codigo:'A',caja:1,frcc:0},{codigo:'B',caja:2,frcc:0}]}",
    "    → POST /api/ia/traslados/guardar {bodega_salida:1}",
    "    → POST /api/ia/traslados {bodega_salida:5, bodega_entrada:2, productos:[{codigo:'C',caja:1,frcc:0}]}",
    "    → POST /api/ia/traslados/guardar {bodega_salida:5}",
    "REGLA 4: Al consultar la rotación, el volumen de datos es inmenso. SE TE EXIGE usar limit=60 y avanzar usando el parámetro page para procesar la información de forma segura.",
    "REGLA 5: Cuando elabores tablas o desgloses por bodega, muestra SIEMPRE el nombre real de la bodega (campo 'nombre_bodega' o 'nombreBodega') en lugar de usar textos como 'Bodega 1' o solo el ID."
  ]
}