# 📘 MANUAL DE PRUEBAS: API DE VENTAS POR CLIENTE ### Endpoint: `GET /api/ia/ventas-clientes` Este manual está diseñado exclusivamente para que puedas **probar, integrar y consumir** el nuevo endpoint de ventas por cliente desde cualquier cliente HTTP (Postman, cURL, n8n, Make, Python, JavaScript o agentes de IA). --- ## 🎯 1. ¿Qué hace este Endpoint? 1. Consulta los **productos exactos comprados por cada cliente** en un rango de fechas. 2. Calcula automáticamente el **valor neto real** (Ventas menos Devoluciones Parciales y Totales). 3. Muestra las unidades físicas entregadas tanto en **Cajas enteras** como en **Fracciones/Pastillas**. 4. Entrega los **datos básicos del cliente** (cédula, nombre, teléfono, dirección, correo, alias y ciudad) y **protege la información crediticia** (omite cupos, saldos o deudas). 5. Permite filtrar por cliente, producto, bodega o fechas, con paginación de alto rendimiento. --- ## 🔑 2. Autenticación Debes enviar el **Token de Seguridad** de la empresa/tienda. Tienes dos opciones: * **Opción A (Recomendada - Header HTTP):** ```http Authorization: Bearer TU_TOKEN_AQUI ``` * **Opción B (Query Param en la URL):** ```text ?token=TU_TOKEN_AQUI ``` > 💡 **Formato del Token de ejemplo:** > - `token_ejemplo_sucursal_1` (Conecta a la base de datos de la Sucursal Principal) > - `token_ejemplo_sucursal_2` (Conecta a la base de datos de la Sucursal Secundaria) --- ## 📋 3. Tabla Completa de Parámetros | Parámetro | Tipo | Obligatorio | Por Defecto | Descripción | Ejemplo de Uso | | :--- | :---: | :---: | :---: | :--- | :--- | | `token` | Texto | 🔴 **SÍ** | — | Token asignado a la empresa. | `token=TU_TOKEN_AQUI` | | `fi` | Fecha | 🟢 No | Hace 30 días | Fecha Inicial (`YYYY-MM-DD`). | `fi=2026-08-01` | | `ff` | Fecha | 🟢 No | Hoy | Fecha Final (`YYYY-MM-DD`). | `ff=2026-08-31` | | `cliente` / `cedula` | Texto | 🟢 No | Todos | Cédula, NIT o celular para ver solo 1 cliente. | `cliente=1085245890` | | `nombre` | Texto | 🟢 No | Todos | Busca por coincidencia en nombre, apellido o alias. | `nombre=maria` | | `producto` | Texto | 🟢 No | Todos | Busca clientes que compraron un producto específico. | `producto=acetaminofen` | | `bodega` | Número/Texto| 🟢 No | Todas | Filtra ventas de una bodega o lista (`1` o `1,2`). | `bodega=1` | | `limit` | Número | 🟢 No | `50` | Cantidad de clientes por página. | `limit=20` | | `page` | Número | 🟢 No | `1` | Número de página a consultar. | `page=2` | --- ## 🧪 4. Ejemplos de Pruebas Rápidas ### Caso 1: Consultar todas las ventas del último mes (General) ```text GET https://tu-dominio.com/api/ia/ventas-clientes?token=TU_TOKEN_AQUI ``` ### Caso 2: Consultar ventas en un rango de fechas específico ```text GET https://tu-dominio.com/api/ia/ventas-clientes?token=TU_TOKEN_AQUI&fi=2026-08-01&ff=2026-08-31 ``` ### Caso 3: Consultar compras de un cliente específico por su cédula ```text GET https://tu-dominio.com/api/ia/ventas-clientes?token=TU_TOKEN_AQUI&cliente=1085245890 ``` ### Caso 4: Buscar qué clientes han comprado un producto (ej. Acetaminofén) ```text GET https://tu-dominio.com/api/ia/ventas-clientes?token=TU_TOKEN_AQUI&producto=acetaminofen ``` ### Caso 5: Filtrar por Bodega 1 con paginación ```text GET https://tu-dominio.com/api/ia/ventas-clientes?token=TU_TOKEN_AQUI&bodega=1&limit=25&page=1 ``` --- ## 📤 5. Estructura de la Respuesta JSON ```json { "estado": "ok", "periodo_consultado": { "fecha_inicio": "2026-08-01", "fecha_fin": "2026-08-31" }, "paginacion": { "total_clientes": 1, "pagina_actual": 1, "limite": 50, "total_paginas": 1 }, "data": [ { "cliente": { "cedula": "1085245890", "nombre": "MARIA ELENA", "apellido": "GOMEZ PAREDES", "nombre_completo": "MARIA ELENA GOMEZ PAREDES", "telefono": "3154879621", "direccion": "Cra 25 # 18-40", "correo": "maria.gomez@gmail.com", "alias": "Doña María", "codigo_ciudad": "52001" }, "resumen_cliente": { "total_comprado_neto": 52500.00, "total_cajas": 3.0, "total_fracciones": 12.0, "cantidad_facturas": 2, "total_items_distintos": 2 }, "productos_comprados": [ { "codigo": "7702001", "nombre": "ACETAMINOFEN 500MG X 100 TAB", "marca": "GENFAR", "categoria": "ANALGESICOS", "factor": 100, "cant_cajas": 2.0, "cant_fracciones": 0.0, "valor_total_neto": 30000.00, "precio_promedio_caja": 15000.00, "precio_promedio_fraccion": 150.00, "bodega_id": 1, "nombre_bodega": "Bodega Principal", "ultima_compra": "2026-08-25 16:40:12" }, { "codigo": "7702005", "nombre": "DOLEX FORTE TAB X 24", "marca": "GSK", "categoria": "ANALGESICOS", "factor": 24, "cant_cajas": 1.0, "cant_fracciones": 12.0, "valor_total_neto": 22500.00, "precio_promedio_caja": 15000.00, "precio_promedio_fraccion": 625.00, "bodega_id": 1, "nombre_bodega": "Bodega Principal", "ultima_compra": "2026-08-28 11:20:00" } ] } ] } ``` --- ## 💻 6. Ejemplos de Código para Pruebas ### A. cURL (Línea de comandos / Terminal) ```bash curl -X GET "http://localhost/Admin_PosCloud_V12/public/api/ia/ventas-clientes?fi=2026-08-01&ff=2026-08-31" \ -H "Authorization: Bearer TU_TOKEN_AQUI" \ -H "Accept: application/json" ``` ### B. JavaScript / Fetch (Navegador o NodeJS) ```javascript const token = 'TU_TOKEN_AQUI'; const url = `http://localhost/Admin_PosCloud_V12/public/api/ia/ventas-clientes?fi=2026-08-01&ff=2026-08-31&token=${token}`; fetch(url) .then(res => res.json()) .then(data => { console.log(`Total clientes: ${data.paginacion.total_clientes}`); data.data.forEach(item => { console.log(`👤 ${item.cliente.nombre_completo} - Total: $${item.resumen_cliente.total_comprado_neto}`); item.productos_comprados.forEach(prod => { console.log(` 📦 ${prod.nombre} | Cajas: ${prod.cant_cajas} | Fracc: ${prod.cant_fracciones} | Neto: $${prod.valor_total_neto}`); }); }); }) .catch(err => console.error('Error:', err)); ``` ### C. Python (Requests) ```python import requests url = "http://localhost/Admin_PosCloud_V12/public/api/ia/ventas-clientes" headers = { "Authorization": "Bearer TU_TOKEN_AQUI" } params = { "fi": "2026-08-01", "ff": "2026-08-31", "limit": 10 } response = requests.get(url, headers=headers, params=params) data = response.json() if data.get("estado") == "ok": for item in data.get("data", []): cliente = item["cliente"] resumen = item["resumen_cliente"] print(f"Cliente: {cliente['nombre_completo']} ({cliente['cedula']})") print(f"Total Comprado Neto: ${resumen['total_comprado_neto']:,.2f}") print("Productos:") for prod in item["productos_comprados"]: print(f" - {prod['nombre']} | Cajas: {prod['cant_cajas']} | Fracc: {prod['cant_fracciones']} | Valor: ${prod['valor_total_neto']:,.2f}") print("-" * 50) ``` ### D. PHP (cURL) ```php