Glop

Compara ventas entre dos períodos diferentes: ingresos, transacciones y ticket promedio de cada período, más el cambio porcentual. Úsala para comparaciones año-contra-año, mes-contra-mes o cualquier comparación entre dos rangos de fechas.

glop_ventas_compare_sales_periods

Compara el GASTO EN COMPRAS con la FACTURACIÓN del período, ambos sin IVA. Devuelve compras (purchases_base), ventas netas (sales_net), margen bruto en euros y en porcentaje, y qué proporción de lo facturado se va en compras (purchase_ratio_percentage). Con granularity="month" añade el desglose mensual para ver la tendencia. Úsala cuando pregunten cuánto se les va en compras respecto a lo que venden, si el coste está subiendo, o por el margen del negocio. MUY IMPORTANTE al responder: NO es margen por artículo ni coste de la mercancía vendida —eso necesitaría el escandallo, que no está disponible—, y un mes con una compra grande de stock sale peor aunque el negocio vaya bien. Traslada siempre ese matiz al usuario: el campo disclaimer de la respuesta lo explica.

glop_compras_compare_purchases_vs_sales

Devuelve las existencias por articulo y almacen. Se puede acotar a un almacen (store_id), a un articulo (product_id) o a ambos. Solo aparecen articulos inventariables. Sin filtros devuelve el stock completo del sitio, que puede ser muy largo: conviene acotar.

glop_stock_consultar

Convierte un documento de compra en el siguiente del circuito de Glop. Solo estas tres: pedido (1) -> albaran (2), pedido (1) -> albaran valorado (3) y albaran (2) -> albaran valorado (3), que es lo que el proveedor llama factura. NUNCA al reves, y un albaran valorado no se puede convertir: es el final del circuito. EXISTENCIAS: convertir un pedido SUMA stock (la mercancia entra ahora); convertir un albaran en valorado NO lo vuelve a sumar, porque ya entro con el albaran, solo reactualiza el ultimo precio de compra. El origen se identifica por type_id + serie_id + num_doc (el numero NO es unico entre tipos ni entre series). "lines" permite convertir solo parte: si se omite se convierte todo lo que quede pendiente, y una linea sin "quantity" convierte lo pendiente de esa linea. Lo que quede sin convertir sigue pendiente en el documento de origen, y si el TPV tiene el pedido automatico activado Glop crea un pedido nuevo con el resto. ASINCRONO: la conversion la ejecuta el TPV cuando la recibe, asi que tiene que estar encendido; NO se devuelve el numero del documento creado y aparece en Glop al sincronizar. Si no se ve al momento, no repitas la llamada: mientras el TPV no la procese se rechaza, y si la proceso en parte crearias un segundo documento. No se puede deshacer desde el MCP. IMPORTANTE: por defecto esta tool NO escribe nada. La primera llamada devuelve un resumen para que el usuario lo apruebe; solo repitiendo la llamada con confirmar=true se registra de verdad.

glop_compra_documento_convertir

Crea un articulo. NAME (descripcion) es obligatorio, y PACKAGING_DEFAULT_ID tambien salvo en un articulo solo de venta. Puede nacer SOLO DE COMPRA (por defecto) o DE COMPRA Y VENTA (ACTIVE = 1, que exige CATEGORY_SALE_ID y hereda de esa familia sus formatos, terminales, comentarios y articulos extra). Solo si NO se esta importando un albaran ni un ticket, con fuera_de_albaran = true, puede ser tambien SOLO DE VENTA (ACTIVE = 1 y STOCK = 0): como el de compra y venta pero sin stock ni envase de compra. CON ACTIVE = 1, PREGUNTALE AL USUARIO EL PRECIO DE VENTA DE CADA FORMATO heredado y mandalo en SALE_PRICES antes de confirmar: sin el, los formatos nacen a 0 y el TPV no puede venderlos. Si el sitio tiene varias tarifas activas, preguntale tambien en cuales poner precio (RATE_ID en cada entrada). Sin confirmar=true solo previsualiza: ensena el resumen, que incluye la familia, el IVA de venta y los formatos que va a heredar (formatos_heredados, que es la lista por la que hay que preguntar). Devuelve el articulo con su PRODUCT_ID y, si es de compra y venta, un bloque compra_venta con lo heredado.

glop_articulo_crear

Registra un pedido, un albaran o una factura de proveedor. Obligatorios dentro de "datos": PROVIDER_ID (de glop_proveedores_buscar) y LINES; TERMINAL_ID solo si el sitio tiene mas de un terminal con almacen. Cada linea necesita al menos PRODUCT_ID, PRODUCT_UD (unidades) y PRICE; admite TAX_ID, PACKAGE_ID, PROVIDER_REF y DTO. Si el albaran NO viene en unidades sino en envases ("2 cajas"), manda la cantidad en PACKAGE_UD junto con PACKAGE_ID (de glop_envases_listar) y NO calcules tu las unidades: las convierte Glop con el envase configurado. Con PACKAGE_UD, PRICE se entiende POR ENVASE (el precio de la caja); si el papel lo da por unidad, anade PRICE_PER: "unit". Si el articulo no tiene envase de compra configurado el alta falla y hay que configurarlo: no lo compenses tu multiplicando. TYPE_ID es OBLIGATORIO y no tiene valor por defecto: 2 albaran, 3 albaran valorado, que es lo que el proveedor llama factura. El 2 y el 3 mueven las existencias igual: la diferencia es contable, asi que elige por lo que ponga el documento y no preguntes si esta claro. Si ese proveedor ya tiene un documento del mismo tipo con esa referencia, NO se crea nada y se devuelve el que ya estaba, con "creado": false y un "aviso": dilo tal cual, no lo presentes como un documento nuevo. La previsualizacion devuelve el documento CALCULADO POR EL TPV (lineas, bases por tipo de IVA y total definitivo): enseña esos importes tal cual y NO los recalcules tu. Manda tambien lo que ponga el papel (PRINTED_TOTAL y, por linea, PRINTED_LINE_TOTAL) y se cuadrara contra lo calculado; si no cuadra, el documento NO se registra y se te dira que linea falla. Un documento ya registrado NO se puede borrar ni corregir desde aqui: no lo intentes ni ofrezcas hacerlo. La correccion se hace desde Glop o desde la app. Los documentos creados por esta via quedan marcados con su origen, asi que se pueden localizar despues. Si lo que se registra es un PEDIDO (TYPE_ID = 1), Glop puede mandarselo por correo al proveedor, a la direccion de la ficha del proveedor y solo a esa. PREGUNTALE al usuario si quiere que se envie y, unicamente si dice que si, manda ENVIAR = "1"; nunca por tu cuenta. Advierte de que el correo lo manda el TPV: hace falta el SMTP configurado en Glop y el TPV encendido, y no hay acuse de recibo, asi que despues solo podras decir que el envio se ha pedido, no que haya llegado. IMPORTANTE: por defecto esta tool NO escribe nada. La primera llamada devuelve un resumen para que el usuario lo apruebe; solo repitiendo la llamada con confirmar=true se registra de verdad.

glop_compra_documento_crear

Crea un documento de stock (regularizacion o traspaso) que MODIFICA las existencias del almacen. Obligatorios dentro de "datos": TERMINAL_ID y STOCK_PRODUCT_STORES (almacen, de glop_almacenes_listar). IMPORTANTE: por defecto esta tool NO escribe nada. La primera llamada devuelve un resumen para que el usuario lo apruebe; solo repitiendo la llamada con confirmar=true se registra de verdad.

glop_stock_documento_crear

Asocia un articulo con un proveedor (UPSERT: si el par ya existe, actualiza referencia y precio). Escribe solo la tabla de mapeo, no cambia el proveedor por defecto del articulo. Proponlo cuando el usuario acabe de elegir a mano el articulo de una linea y venia una referencia del proveedor: a partir de ahi esa referencia se reconocera sola. El articulo tiene que ser de stock; si no lo es, la tool te lo dira y habra que preguntar al usuario antes de marcarlo. IMPORTANTE: por defecto esta tool NO escribe nada. La primera llamada devuelve un resumen para que el usuario lo apruebe; solo repitiendo la llamada con confirmar=true se registra de verdad.

glop_mapeo_crear

Crea un proveedor. NAME (nombre comercial) es el unico campo obligatorio; el resto son opcionales. Devuelve el proveedor con su nuevo PROVIDER_ID. Si vas a crearlo desde un ticket o un albaran, PREGUNTA al usuario los datos que el papel no traiga (NIF, direccion, telefono) antes de crear la ficha: no los inventes ni los dejes en blanco por comodidad.

glop_proveedor_crear

Devuelve la licencia del sitio con el que esta conectado el MCP, si el complemento MCP esta activo, las tools deshabilitadas para este sitio y la version del servidor. Util para comprobar que la credencial es correcta antes de operar.

glop_diagnostico

Devuelve un ENLACE para que el usuario suba la imagen de un articulo desde su navegador. Usala siempre que te pidan poner o cambiar la foto de un articulo: TU NO PUEDES mandar la imagen, ni aunque la veas en la conversacion, porque no tienes sus bytes. El enlace caduca en unos minutos. Esta llamada NO cambia la imagen: solo abre la puerta. Devuelve tambien una "huella" de la imagen actual: GUARDALA, porque es lo que despues le pasas a glop_articulo_imagen_estado para saber si el usuario la ha subido de verdad. Despues de darle el enlace, ESPERA a que te diga que ya esta y compruebalo.

glop_articulo_imagen_enlace

Dice si el usuario ya ha subido la imagen, comparando la que el articulo tiene AHORA con la "huella" que te devolvio glop_articulo_imagen_enlace. NO vale mirar la ficha del articulo por tu cuenta para saberlo: un articulo con foto se ve igual si la acaba de subir que si la tenia desde hace un ano, y por eso hace falta la huella de antes. Si aun no ha subido nada y el enlace ha caducado, pide otro y dale el nuevo al usuario sin presentarlo como un error: duran pocos minutos y caducar es normal.

glop_articulo_imagen_estado

Obtiene la EVOLUCIÓN DEL PRECIO DE COMPRA de un artículo: cada compra con su fecha, documento, proveedor, cantidad, precio unitario, descuento y precio neto pagado, más un resumen con primer y último precio, mínimo, máximo, precio medio ponderado y variación porcentual (change_percent). Úsala cuando pregunten cómo ha evolucionado el precio de algo ("¿cómo ha evolucionado el precio de la Coca-Cola?"), si les han subido el precio, a cuánto salió la última compra, o si un proveedor lo pone más caro que otro (combínala con supplier_id). Busca por product_name: el usuario dirá "Coca-Cola", no un identificador. Si el nombre casa con varios artículos devuelve varias series y debes explicar cuál es cuál. Son PRECIOS DE COMPRA a proveedor, no precios de venta al público.

glop_compras_get_purchase_price_history

Obtiene las ventas diarias desglosadas por fecha dentro de un período, con transacciones e ingresos de cada día. Úsala para ver la evolución diaria, tendencias o gráficas de ventas por día.

glop_ventas_get_sales_daily

Obtiene el GASTO EN COMPRAS agrupado por PROVEEDOR en un período: base imponible (total_base), IVA (total_tax), total con impuestos (total), número de documentos (num_documents), primera y última compra, y el peso de cada proveedor sobre el gasto del período (share_percentage). Úsala cuando pregunten cuánto le han comprado a un proveedor ("¿cuánto le he comprado a Pepito este mes?"), en qué proveedores se va el dinero, quién es el proveedor principal, o el gasto en compras de un período. Usa supplier_name para buscar un proveedor por su nombre: el usuario dirá "Pepito" o "Coca-Cola", no un identificador. Son COMPRAS a proveedores, NO ventas: para lo que factura el negocio usa get_sales_total.

glop_compras_get_purchases_by_supplier

Lo que se han consumido los EMPLEADOS en un periodo y no es una venta, pero si es salida de mercancia: a fin de mes explica diferencias de stock que de otro modo parecen mermas. Devuelve un registro por empleado con el numero de consumiciones, las unidades y dos valoraciones distintas, que responden a dos preguntas distintas: `importe_pvp` es lo que se ha dejado de ingresar y `importe_coste` lo que le ha costado al negocio. Con detail=true cada empleado trae ademas el desglose por articulo, que es lo que permite ver si el consumo es cafe o solomillo. IMPORTANTE al interpretar los euros: el consumo se graba a precio cero, asi que el PVP se calcula con el precio al que se ha vendido ese mismo articulo en el periodo; `unidades_sin_precio` dice cuantas unidades no se han podido valorar y NO estan sumadas en el importe. Y `importe_coste` es null cuando el sitio no tiene cargados los costes de sus articulos, que es lo habitual: null ahi significa que no se sabe, no que sea gratis.

glop_informe_consumo_personal

Informe de ventas de un periodo en forma de ASIENTO CONTABLE, que es lo que el gestor mete en su programa de contabilidad. No es un listado de tickets. Devuelve tres clases de registro, distinguidas por el campo `tipo`: `simplificada` (UN resumen por dia y serie, con num_documentos y el rango numero_desde/numero_hasta), `factura` (una fila POR FACTURA, con los datos fiscales del cliente, porque el destino es el modelo 347) y `rectificativa` (una fila por abono, con los importes en negativo). Cada registro trae su desglose por tipo de IVA en `ivas`. Las simplificadas NO traen el campo `cliente`, porque por definicion no lo tienen; una rectificativa sin cliente identificado lo trae a null. El `recargo` solo aparece cuando lo hay: si falta, es que no hay recargo de equivalencia, que es el caso de la mayoria de los sitios. El periodo se corta por la JORNADA DE APERTURA DE CAJA, igual que la exportacion contable de Glop, asi que una venta de madrugada cuenta en el dia en que se abrio la caja. El NIF sale de la ficha actual del cliente: si la ficha se edito despues de emitir, se vera el dato nuevo, no el del momento de la emision.

glop_informe_ventas_gestor

Obtiene el listado completo de terminales de un store con su jerarquía (franquicia, grupo, dirección, última venta). No requiere fechas. Úsala para saber cuántos terminales hay, su ubicación, su jerarquía, estructura organizativa, a qué establecimiento/grupo/franquicia pertenece cada terminal, o cualquier pregunta sobre la relación entre terminales y tiendas.

glop_ventas_get_terminals_list

Lista los almacenes del sitio (STORE_ID, STORE_NAME). El STORE_ID es lo que piden glop_stock_consultar y los documentos de stock.

glop_almacenes_listar

Lista los envases/formatos de compra (caja, botella, kg...) con las unidades que contiene cada uno. Es lo que resuelve "una caja de 12" al registrar un albaran.

glop_envases_listar

Lista las familias de compra del sitio. Sirven para clasificar articulos al darlos de alta (campo CATEGORY_PURCHASE_ID).

glop_familias_compra_listar

Lista las familias de venta del sitio (la carta: bebidas, entrantes, postres...). Cada familia trae ademas FORMATS: los formatos de venta que heredaria un articulo suyo (FORMAT_ID y DESCRIPTION), que son EXACTAMENTE los que el alta va a componer. Son por los que hay que preguntar el precio, uno por uno y por su nombre, antes de crear un articulo de compra y venta; van en SALE_PRICES de glop_articulo_crear. Si una familia llegara SIN FORMATS, sacalos previsualizando el alta del articulo (glop_articulo_crear sin confirmar, que no escribe nada): su resumen trae formatos_heredados con el FORMAT_ID y el nombre de cada uno. NO LE PIDAS AL USUARIO los formatos ni sus identificadores: los sabe el sistema, y el usuario no tiene por que conocerlos. A el se le pregunta el PRECIO de cada formato, no cuales son. El CATEGORY_SALE_ID de cada fila es exactamente lo que piden glop_articulo_crear y glop_articulo_actualizar en el campo CATEGORY_SALE_ID, asi que hay que llamar aqui antes de clasificar un articulo en vez de suponer el identificador. Es el maestro completo, no una agregacion de ventas: aparecen tambien las familias que no han vendido nada.

glop_familias_venta_listar

Lista las tarifas de venta del sitio. Una tarifa es una lista de precios: un bar que cobra distinto en barra, en terraza y a domicilio tiene una por cada sitio, y cada articulo guarda un precio en cada una. ACTIVATE_RATE dice cuales usa el sitio de verdad. Al crear un articulo, el RATE_ID de una tarifa activa es el que va en cada entrada de SALE_PRICES para poner el precio en esa tarifa; sin RATE_ID va a la primera activa.

glop_tarifas_listar

Lista los terminales (cajas) del sitio, cada uno con su almacen (warehouse_id). Para un documento de compra se elige el terminal del ALMACEN DONDE ENTRA LA MERCANCIA, porque de el salen el almacen de destino y la serie del documento.

glop_terminales_listar

Lista los tipos de IVA configurados (TAX_ID, TAX_RATE, TAX_NAME). El TAX_ID es lo que llevan las lineas de un documento de compra.

glop_ivas_listar

Obtiene el ranking de mejores clientes identificados en un período. Devuelve: ID de cliente, nombre y apellidos (cuando estén disponibles en los tickets), número de compras, total gastado, ticket medio, fecha primera y última compra. Úsala cuando pregunten por mejores clientes, clientes más frecuentes, clientes que más gastan, fidelización, clientes VIP, recurrencia o cualquier análisis de comportamiento de cliente. Si el cliente tiene nombre, úsalo para referirte a él en la respuesta.

glop_ventas_get_top_customers

Devuelve un articulo por su PRODUCT_ID.

glop_articulo_obtener

Devuelve un documento de compra por su numero, con todas sus lineas. Por defecto busca un PEDIDO (type_id=1): para un albaran o una factura de proveedor hay que indicar type_id, porque el numero no es unico entre tipos.

glop_compra_documento_obtener

Devuelve un documento de stock por su numero, con sus lineas.

glop_stock_documento_obtener

Devuelve un proveedor por su PROVIDER_ID.

glop_proveedor_obtener

Obtiene productos ordenados por cantidad vendida o por ingresos. Soporta orden descendente (más vendidos, por defecto) y ascendente (menos vendidos). Úsala para rankings de productos, para los productos que menos se venden (sort_order=asc), o para BUSCAR PRODUCTOS por nombre o tipo genérico usando name_filter (recomendado: busca server-side y devuelve solo los que matchean). Soporta filtrado opcional por group_id o terminal_id para desglosar productos por tienda/grupo o por terminal.

glop_ventas_get_top_products

Deja un articulo SIN imagen. No hace falta ningun enlace para esto, porque no hay ningun fichero que subir. Sin confirmar=true solo previsualiza, y el resumen dice si el articulo tiene imagen ahora mismo. Al quitarla, el boton del TPV pasa a ensenar el texto "sin foto" con sus colores.

glop_articulo_imagen_quitar

Averigua a que articulo del catalogo corresponde una linea de albaran. Pasale todo lo que traiga el papel: provider_id, provider_ref (la referencia del catalogo del proveedor), barcode y description. Prueba cuatro vias en orden (vinculo articulo-proveedor, referencia de la ficha, codigo de barras y descripcion) y para en la primera que acierta. USA ESTA TOOL ANTES DE glop_compra_documento_crear para cada linea cuyo PRODUCT_ID no conozcas; no busques a mano con glop_articulos_buscar. Si devuelve "resuelto": true puedes usar su PRODUCT_ID directamente. Si devuelve false, NUNCA elijas tu un candidato por parecido: enseñaselos al usuario y que elija. Lee siempre "siguiente_paso", que dice que hacer en cada caso.

glop_articulo_resolver

Obtiene el ranking de tickets individuales ordenados por importe total (por defecto los más caros primero). Devuelve: ID de ticket, fecha, total bruto, total neto, número de artículos, terminal, establecimiento y métodos de pago. También incluye estadísticas del período: ticket máximo, mínimo, medio y total de tickets. Úsala cuando pregunten por el ticket más grande/más caro, los N tickets de mayor importe, cuántos tickets hubo en un período (usa stats.total_tickets), tickets por encima o por debajo de cierto importe, o cuando el usuario pida un ticket concreto por su numero (parametro ticket_number). NO usar para resumen de facturación total (usar get_sales_total) ni para número de ventas por día (usar get_sales_daily).

glop_ventas_get_top_tickets

Obtiene el resumen total de ventas en un período: total bruto con impuestos (total), total neto sin impuestos (total_net), total de impuestos (total_tax), número de tickets (num_tickets), ticket promedio (average_ticket), moneda (currency), total de descuentos aplicados (total_discount), tickets con descuento (tickets_with_discount), porcentaje de descuento (discount_percentage), número de abonos/devoluciones (num_refunds) e importe de abonos (refund_amount). Úsala cuando pregunten por facturación, ventas totales, resumen de un período, impuestos, IVA, neto o bruto. Úsala también cuando pregunten por descuentos, promociones aplicadas o rebajas. Úsala también cuando pregunten por abonos, devoluciones o facturas rectificativas. Además incluye métricas de comensales cuando el establecimiento registra esta información: total de comensales (total_covers), media por mesa (average_covers_per_ticket) y gasto por comensal (revenue_per_cover). También incluye el tiempo medio de servicio por mesa (average_service_time_minutes) cuando hay datos de fecha de cobro.

glop_ventas_get_sales_total

Guarda como ha ido el alta de un documento de compra. LLAMALA UNA SOLA VEZ, despues de que glop_compra_documento_crear haya devuelto "creado": true y el usuario haya elegido una de las cuatro opciones que le ofreces. NO INSISTAS: si el usuario no contesta o cambia de tema, olvidalo y sigue; que no conteste es una respuesta valida. No la llames con una valoracion que hayas deducido tu: solo con la que el usuario haya elegido expresamente. Esto NO modifica el documento ni nada del TPV: el albaran ya esta registrado y nada de lo que se conteste aqui lo cambia.

glop_compra_valorar

Obtiene ventas agregadas por día de la semana (Lunes a Domingo), con transacciones e ingresos. Úsala para identificar qué días de la semana se vende más o menos.

glop_ventas_get_sales_by_day_of_week

Obtiene ranking de ventas por empleado en un período. SOLO para preguntas de VENTAS (quién más vendió, ranking de facturación por empleado). NO usar para anulaciones, borrados de ticket ni incidencias — para eso usar get_incidents_analysis. Para abonos y devoluciones usar get_sales_total. Usa SIEMPRE role="server". Soporta orden descendente (más vendedores, por defecto) y ascendente (menos vendedores, sort_order=asc).

glop_ventas_get_sales_by_employee

Obtiene las ventas agregadas por FAMILIA o CATEGORÍA de producto en un período. Devuelve para cada familia: id, nombre, cantidad vendida, ingresos, número de tickets y porcentaje sobre el total. Usa esta tool cuando pregunten por: familias de producto, categorías, tipos de artículo, grupos de producto, qué familia factura más, qué categoría vende más, distribución por familia, peso de cada familia en la facturación, mix de categorías. NO la uses para productos individuales (usa get_top_products). Los artículos sin categoría asignada se agrupan bajo el id "(sin_categoria)".

glop_ventas_get_sales_by_category

Obtiene ventas desglosadas por método de pago (tarjeta, efectivo, etc.) con transacciones, ingresos y porcentaje de cada método. Úsala cuando pregunten por formas de pago o distribución de medios de pago.

glop_ventas_get_sales_by_payment_method