Reportes

Consultas analíticas agrupadas sobre ventas, compras, pagos e inventario usando POST /api/v1/reports/query

Cómo funciona

POST /api/v1/reports/query ejecuta una consulta analítica agrupada. Enviá JSON con:

• source: qué datos consultar (sales, purchases, payments, applied_collections, inventory).
• dimensions: cómo agrupar resultados (producto, fecha, proveedor, etc.). Máximo 4.
• measures: qué calcular en cada grupo (total vendido, unidades, stock, etc.). Al menos 1.
• period: rango de fechas (obligatorio para sales, purchases, payments y applied_collections, y condicional para inventory).
• reportingCurrency: moneda de presentación (ARS o USD). Si la omitís, usa ARS.
• dimension_filters: filtros opcionales que reducen el dataset antes de agrupar.
• include_totals: cuando es true, la respuesta incluye totales de todas las filas en totals.

El scope siempre es la organización autenticada. No hay acceso a datos de otras organizaciones. Por defecto los reportes incluyen entidades activas y archivadas. Para limitar el alcance, usá filtros de estado como product_status, customer_status, supplier_status o warehouse_status con valores active o archived.

Con response_mode: "assistant", podés ordenar cualquier fuente con sort_by y sort_direction antes de aplicar limit. Usá una dimensión o métrica seleccionada; las dimensiones ordinales usan su valor original (fechas, semanas, días de la semana, cuotas o rangos de última compra). Las demás usan su nombre visible. Los valores vacíos van al final. El sentido predeterminado con sort_by es desc, o asc para marketplace_listings. Omití ambos campos para conservar el orden predeterminado. La respuesta registra el orden aplicado en metadata.resolved_request. Si una métrica no es válida, el error enumera las claves válidas para esa fuente.

Cuando agrupás por product, su entrada en ids identifica un grupo de variantes. No es el ID de producto que usan las herramientas de inventario. Consultá get_product y seleccioná el ID de producto en list_inventory antes de registrar un movimiento de stock.

Forma de la respuesta

{
  "request_id": "req_abc",
  "data": {
    "rows": [
      {
        "id": "9c692e8b",
        "ids": ["9c692e8b-0f9a-4f7c-8b99-061a2eb188ae"],
        "labels": ["Microfiber Pillow 80x50"],
        "measures": { "total": 998300, "units": 12, "count": 8 }
      }
    ],
    "totals": { "total": 1448300, "units": 17, "count": 12 },
    "metadata": {
      "source": "sales",
      "dimensions": ["product"],
      "measures": ["total", "units", "count"],
      "period": { "start_date": "2026-01-01", "end_date": "2026-03-31" },
      "date_basis": "commercial",
      "reporting_currency": "ARS",
      "rate_basis": "mixed_by_source"
    }
  }
}

Cada objeto en rows tiene:

Campo	Tipo	Descripción
id	string	Clave compuesta a partir de los valores de dimensión. Sirve como identificador estable de fila.
ids	string[]	IDs crudos de cada dimensión, en el mismo orden que labels.
labels	string[]	Etiquetas legibles para cada dimensión agrupada.
measures	Record<string, number>	Valores de las métricas solicitadas.

Las métricas currency son centavos enteros en la moneda indicada por metadata.reporting_currency. Dividí por 100 para obtener pesos o dólares.

La conversión se hace por operación antes de agrupar. Los importes ingresados en USD conservan su valor exacto cuando pedís USD. Las operaciones en moneda extranjera usan su tipo de cambio guardado. Los importes funcionales en ARS que se presentan en USD usan la cotización BCRA de la fecha de la operación o la última fecha anterior disponible.

El filtro currency siempre se refiere a la moneda original del comprobante y es independiente de reportingCurrency. Por ejemplo, podés consultar solo ventas originales en USD y presentar el resultado en ARS:

{
  "source": "sales",
  "period": { "startDate": "2026-01-01", "endDate": "2026-03-31" },
  "dimensions": ["product"],
  "measures": ["subtotal", "margin"],
  "reportingCurrency": "ARS",
  "filters": [{ "field": "currency", "operator": "in", "values": ["USD"] }]
}

---

Fuente: sales

Consulta las ventas de la organización.

period: obligatorio. Filtra por fecha de venta (commercial) o fecha contable (fiscal), según date_basis.

date_basis: commercial (default) o fiscal.

Dimensiones disponibles (sales)

Dimensión	Descripción
date	Día de venta
week	Semana (lunes a domingo)
week_of_year	Número de semana del año
month	Mes (año-mes)
month_of_year	Número de mes (1-12)
day_of_week	Día de la semana (1=lunes, 7=domingo)
year	Año
quarter	Trimestre
hour_of_day	Hora del día (0-23)
customer	Cliente
customer_tax_category	Código o etiqueta de categoría fiscal del cliente, según los datos fuente
province	Provincia del cliente
city	Ciudad del cliente
product	Producto
variant	Variante del producto
category	Categoría del producto
product_type	Tipo de producto (producto, servicio, combo, kit)
salesperson	Vendedor
cashier	Cajero (usuario registrado como cajero; Sin cajero si la venta no tiene uno)
point_of_sale	Punto de venta
warehouse	Depósito
register	Caja
integration_source	Sistema que originó la venta (Mercado Libre, Tiendanube, WooCommerce). Las ventas sin integración figuran como Venta Directa y cualquier otro origen se muestra con su código
channel_listing	Publicación de Mercado Libre, con su título más reciente. Las ventas sin publicación registrada figuran como Sin publicación
channel_listing_type	Tipo de publicación de Mercado Libre (Clásica, Premium, Gratuita)
channel_logistics	Logística del envío de Mercado Libre (Full, Flex, Colecta, Places, Drop off, Turbo)
voucher_type	Tipo de comprobante
currency	Moneda (ARS, USD)
payment_status	Estado de cobranza
cae_status	Estado de CAE (AFIP)
invoice_status	Estado de facturación
formatted_invoice_number	Número de comprobante formateado
payment_method	Método de pago
tax_rate	Alícuota de IVA

Métricas disponibles (sales)

Métrica	Tipo	Unidad	Descripción
total	currency	cents	Total vendido
subtotal	currency	cents	Subtotal sin IVA
tax_amount	currency	cents	IVA
count	count	integer	Cantidad de ventas: ventas menos notas de crédito, porque una nota de crédito anula una venta
sale_count	count	integer	Comprobantes de venta emitidos, sin restar notas de crédito
credit_note_count	count	integer	Cantidad de notas de crédito
units	units	integer	Unidades vendidas
units_per_sale	number	decimal	Unidades por venta (calculado: units / count)
cost	currency	cents	Costo de mercadería vendida
margin	currency	cents	Margen bruto (ventas netas sin IVA ni tributos - costo de mercadería vendida)
avg_ticket	currency	cents	Ticket promedio (calculado: total / count)
margin_percent	percentage	% (0-100)	Porcentaje de margen (calculado: margin / subtotal x 100)
channel_fee	currency	cents	Lo que cobra Mercado Libre por la venta. Sin IVA si la venta se emitió con comprobante A o B; con IVA si se emitió con comprobante C. Un Comprobante X sigue la condición actual de la organización
seller_shipping	currency	cents	Envío a cargo del vendedor en Mercado Libre. Sin IVA si la venta se emitió con comprobante A o B; con IVA si se emitió con comprobante C. Un Comprobante X sigue la condición actual de la organización
additional_costs	currency	cents	Porcentaje de costos adicionales de la cuenta de Mercado Libre sobre la venta sin IVA
contribution_margin	currency	cents	Resultado (calculado: subtotal - cost - channel_fee - seller_shipping - additional_costs)
contribution_margin_percent	percentage	% (0-100)	Resultado sobre la venta sin IVA (calculado: contribution_margin / subtotal x 100)
discount_amount	currency	cents	Descuentos aplicados
balance	currency	cents	Saldo pendiente de cobro
unique_customers	count	integer	Clientes únicos
unique_products	count	integer	Productos únicos

Dimensiones filtrables (sales)

customer, customer_status, customer_tax_category, province, city, product, product_status, category, product_type, salesperson, cashier, point_of_sale, point_of_sale_status, warehouse, warehouse_status, register, register_status, integration_source, channel_listing, channel_listing_type, channel_logistics, voucher_type, currency, payment_status, cae_status, invoice_status, formatted_invoice_number, payment_method, payment_method_status, tax_rate.

---

Fuente: purchases

Consulta las compras de la organización.

period: obligatorio. Filtra por fecha de factura.

Dimensiones disponibles (purchases)

Dimensión	Descripción
date	Día de factura
week	Semana
month	Mes (año-mes)
quarter	Trimestre
year	Año
supplier	Proveedor
supplier_tax_category	Categoría fiscal del proveedor
supplier_province	Provincia del proveedor
supplier_city	Ciudad del proveedor
product	Producto
variant	Variante del producto
category	Categoría del producto
product_type	Tipo de producto
warehouse	Depósito de recepción
voucher_type	Tipo de comprobante
currency	Moneda
tax_rate	Alícuota de IVA

Métricas disponibles (purchases)

Métrica	Tipo	Unidad	Descripción
purchase_total	currency	cents	Total comprado
purchase_subtotal	currency	cents	Subtotal sin IVA
purchase_tax_amount	currency	cents	IVA de compras
purchase_count	count	integer	Cantidad de compras
purchase_units	units	integer	Unidades compradas
purchase_cost	currency	cents	Total de costo unitario (unit_cost x quantity)
unique_suppliers	count	integer	Proveedores únicos
avg_purchase_ticket	currency	cents	Ticket promedio de compra (calculado: purchase_total / purchase_count)
avg_purchase_unit_cost	currency	cents	Costo unitario promedio (calculado: purchase_cost / purchase_units)

Dimensiones filtrables (purchases)

supplier, supplier_status, supplier_tax_category, supplier_province, supplier_city, product, product_status, category, product_type, warehouse, warehouse_status, voucher_type, currency, tax_rate.

---

Fuente: payments

Consulta cobranzas de clientes y pagos a proveedores.

period: obligatorio. Filtra por fecha de pago/cobranza.

Dimensiones disponibles (payments)

Dimensión	Descripción
date	Día de pago/cobranza
week	Semana
month	Mes (año-mes)
quarter	Trimestre
year	Año
payment_contact	Cliente o proveedor
payment_contact_name	Nombre del contacto
assigned_salesperson	Vendedor asignado hoy al cliente, no quien registró la venta
payment_contact_tax_category	Categoría fiscal del contacto
payment_contact_province	Provincia del contacto
payment_contact_city	Ciudad del contacto
point_of_sale	Punto de venta
register	Caja
pos_session	Sesión POS
safe	Caja fuerte
payment_type	Tipo de movimiento (customer o supplier)
payment_record_status	Estado del recibo
currency	Moneda
settlement_currency	Moneda de liquidación
formatted_payment_number	Número de recibo formateado
payment_method	Método de pago
payment_method_type	Tipo de método de pago

Métricas disponibles (payments)

Métrica	Tipo	Unidad	Descripción
payment_collected_total	currency	cents	Total cobrado a clientes
payment_paid_total	currency	cents	Total pagado a proveedores
payment_net_cashflow	currency	cents	Total cobrado menos total pagado
payment_gross_movement	currency	cents	Movimiento bruto total
payment_net_amount	currency	cents	Importe neto liquidado
payment_fee_amount	currency	cents	Comisiones
payment_balance	currency	cents	Saldo sin aplicar
payment_count	count	integer	Cantidad de recibos
payment_split_count	count	integer	Cantidad de líneas de pago
unique_payment_contacts	count	integer	Contactos únicos
avg_payment_amount	currency	cents	Importe promedio de recibo

Dimensiones filtrables (payments)

payment_contact, payment_contact_status, payment_contact_name, assigned_salesperson, payment_contact_tax_category, payment_contact_province, payment_contact_city, point_of_sale, point_of_sale_status, register, register_status, pos_session, safe, safe_status, payment_type, payment_record_status, currency, settlement_currency, formatted_payment_number, payment_method, payment_method_status, payment_method_type.

---

Fuente: applied_collections

Consulta cobranzas aplicadas a facturas de venta. Cada fila es un importe de un recibo aplicado a una factura. Incluye aplicaciones de anticipos; excluye notas de crédito y aplicaciones de saldo a favor.

period: obligatorio. Filtra por el día en que se aplicó la cobranza (hora de Argentina), no por la fecha del recibo ni de la factura.

Dimensiones disponibles (applied_collections)

Dimensión	Descripción
date	Día de aplicación
week	Semana
week_of_year	Número de semana del año
month	Mes (año-mes)
month_of_year	Número de mes (1-12)
day_of_week	Día de la semana (1=lunes, 7=domingo)
quarter	Trimestre
year	Año
hour_of_day	Hora del día (0-23)
customer	Cliente
assigned_salesperson	Vendedor asignado hoy al cliente, no quien registró la venta
formatted_payment_number	Número de recibo
formatted_invoice_number	Número de la factura a la que se aplicó
voucher_type	Tipo de comprobante de la factura

Métricas disponibles (applied_collections)

Métrica	Tipo	Unidad	Descripción
applied_collection_amount	currency	cents	Monto aplicado, con impuestos
applied_collection_net_amount	currency	cents	Monto aplicado proporcional al neto de la factura ((total − IVA − tributos) / total): descuenta IVA, percepciones y otros tributos; mantiene montos exentos y no gravados
applied_collection_count	count	integer	Cantidad de aplicaciones

Dimensiones filtrables (applied_collections)

customer, customer_status, assigned_salesperson, formatted_payment_number, formatted_invoice_number, voucher_type.

---

Fuente: inventory

Consulta el estado de stock. Tiene dos modos según las métricas seleccionadas:

Métricas snapshot (sin period)

Devuelven el estado actual del stock. No aceptan period ni date_basis, salvo que la solicitud agrupe o filtre por abc_grade: esa dimensión clasifica por ventas del período y exige period.

Métrica	Tipo	Unidad	Descripción
stock_on_hand	units	integer	Stock físico total
stock_available	units	integer	Stock disponible (físico - reservado)
stock_reserved	units	integer	Stock reservado
stock_incoming	units	integer	Stock entrante
stock_value_cost	currency	cents	Valor del stock a costo
stock_value_retail	currency	cents	Valor del stock a precio de venta

Métricas derivadas de ventas (requieren period)

Se calculan a partir de ventas del período. Requieren period y aceptan date_basis.

Métrica	Tipo	Unidad	Descripción
ending_inventory_units	units	integer	Unidades de inventario al cierre del período
inventory_units_sold	units	integer	Unidades vendidas en el período
inventory_units_sold_per_day	number	decimal	Promedio de unidades vendidas por día con stock. Cuenta ventas desde el inicio del historial de stock. Es null si el período no tiene historial de stock
days_of_inventory_remaining	number	decimal	Días estimados de inventario restante al ritmo de ventas. Es null si el artículo no vendió unidades en el período o si el período no tiene historial de stock

Si el historial de stock de la organización empieza después del inicio del período, inventory_units_sold_per_day y days_of_inventory_remaining cuentan las ventas desde ese día. metadata.sales_rate_window informa el período usado (period, o null sin historial de stock) y una description. inventory_units_sold siempre cuenta todas las ventas del período.

Las métricas snapshot no pueden mezclarse con métricas derivadas en la misma solicitud.

Cuando se usan métricas derivadas, solo son compatibles las dimensiones product, variant, category, product_type, warehouse y abc_grade.

Dimensiones disponibles (inventory)

Dimensión	Descripción
product	Producto
variant	Variante del producto
category	Categoría del producto
product_type	Tipo de producto
warehouse	Depósito
currency	Moneda del stock
abc_grade	Clasificación ABC de la variante (A, B o C). Requiere period

Dimensiones filtrables (inventory)

product, product_status, category, product_type, warehouse, warehouse_status, currency, abc_grade.

Clasificación ABC (abc_grade)

Ordena las variantes por ventas netas del período (sin IVA, las notas de crédito restan). Una variante es A mientras las anteriores acumulan menos del 80% de las ventas netas, B por debajo del 95% y C en adelante. Las variantes sin ventas o con ventas netas negativas son C.

La clasificación es de toda la organización: los filtros de la solicitud (proveedor, categoría, depósito) y los permisos de quien consulta no cambian el grado de una variante. Requiere period y acepta date_basis. No está disponible en la fuente sales.

---

dimension_filters

Filtra datos antes de agrupar. Cada clave es una dimensión filtrable para la fuente. El valor es un array de IDs a incluir. La lógica es OR dentro de un filtro y AND entre filtros.

{
  "source": "sales",
  "period": { "start_date": "2026-01-01", "end_date": "2026-03-31" },
  "dimensions": ["product"],
  "measures": ["total", "units"],
  "dimension_filters": {
    "category": ["uuid-category-apparel", "uuid-category-footwear"],
    "warehouse": ["uuid-main-warehouse"]
  }
}

Los filtros de estado aceptan valores literales:

{
  "source": "sales",
  "period": { "start_date": "2025-01-01", "end_date": "2025-12-31" },
  "dimensions": ["product"],
  "measures": ["count"],
  "dimension_filters": {
    "product_status": ["archived"]
  }
}

---

Ejemplos

Ventas por producto en Q1 2026

curl -X POST "https://api.lapyme.com.ar/api/v1/reports/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "sales",
    "period": { "start_date": "2026-01-01", "end_date": "2026-03-31" },
    "dimensions": ["product"],
    "measures": ["total", "units", "count", "margin"],
    "include_totals": true
  }'

Ventas por mes y categoría (fiscal)

curl -X POST "https://api.lapyme.com.ar/api/v1/reports/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "sales",
    "period": { "start_date": "2026-01-01", "end_date": "2026-03-31" },
    "dimensions": ["month", "category"],
    "measures": ["total", "subtotal", "tax_amount"],
    "date_basis": "fiscal"
  }'

Compras por proveedor en marzo de 2026

curl -X POST "https://api.lapyme.com.ar/api/v1/reports/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "purchases",
    "period": { "start_date": "2026-03-01", "end_date": "2026-03-31" },
    "dimensions": ["supplier"],
    "measures": ["purchase_total", "purchase_count", "purchase_units"],
    "include_totals": true
  }'

Cobranzas y pagos por método en marzo de 2026

curl -X POST "https://api.lapyme.com.ar/api/v1/reports/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "payments",
    "period": { "start_date": "2026-03-01", "end_date": "2026-03-31" },
    "dimensions": ["payment_method"],
    "measures": ["payment_net_cashflow", "payment_collected_total", "payment_paid_total"],
    "include_totals": true
  }'

Stock disponible por producto y depósito

curl -X POST "https://api.lapyme.com.ar/api/v1/reports/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "inventory",
    "dimensions": ["product", "warehouse"],
    "measures": ["stock_on_hand", "stock_available", "stock_reserved"]
  }'

Stock parado (variantes clase C)

curl -X POST "https://api.lapyme.com.ar/api/v1/reports/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "inventory",
    "period": { "start_date": "2026-07-01", "end_date": "2026-09-28" },
    "dimensions": ["variant"],
    "measures": ["stock_on_hand", "stock_value_retail"],
    "dimension_filters": { "abc_grade": ["C"] }
  }'

Días de inventario restante por categoría

curl -X POST "https://api.lapyme.com.ar/api/v1/reports/query" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "source": "inventory",
    "period": { "start_date": "2026-01-01", "end_date": "2026-03-31" },
    "dimensions": ["product"],
    "measures": ["stock_on_hand", "inventory_units_sold", "days_of_inventory_remaining"]
  }'

---

Scope requerido

reports:read

Fuente: marketplace_listings

Consultá publicaciones activas de Mercado Libre sin necesitar una venta. Esta fuente usa una instantánea en ARS, sin period, comparación ni conversión a USD. Cada fila es una publicación. Todos los importes son centavos; los datos faltantes conservan null.

Incluí marketplace_item_id (el MLA) o marketplace_listing (el título) entre las dimensiones. Sin response_mode, la respuesta devuelve todas las publicaciones activas en data.rows. Para ordenar y paginar, usá response_mode: "assistant":

{
  "response_mode": "assistant",
  "source": "marketplace_listings",
  "dimensions": ["marketplace_item_id", "marketplace_listing"],
  "measures": ["listing_price", "estimated_contribution", "estimated_contribution_percent", "recent_units"],
  "sort_by": "estimated_contribution_percent",
  "sort_direction": "asc",
  "limit": 50
}

En ese modo la respuesta usa data.report.rows y data.report.metadata. Pasá data.report.metadata.next_cursor como cursor en la consulta siguiente. Los filtros y el orden se aplican sobre todas las publicaciones antes de paginar. Una dimensión se ordena por su nombre visible. Los valores null van al final en ambas direcciones. Una página no incluye un total de todas las publicaciones de la cuenta.

Métrica	Significado
listing_price	Precio vigente con IVA
reference_cost	Costo neto de referencia actual del catálogo
listing_fee	Cargo total estimado de venta con IVA, incluidos el cargo fijo y la financiación
listing_commission	Comisión por venta con IVA
listing_fixed_fee	Costo fijo por vender con IVA
listing_financing	Costo de financiación con IVA
listing_shipping	Envío estimado a cargo del vendedor con IVA
listing_channel_share_percent	Cargo de venta más envío dividido por el precio, todo con IVA, en puntos porcentuales. No depende del costo ni del vínculo con un producto
listing_additional_costs	Costos adicionales estimados sobre el precio neto
estimated_contribution	Resultado neto estimado por una unidad
estimated_contribution_percent	Resultado dividido por el precio neto, en puntos porcentuales
recent_units	Unidades netas de los últimos 30 días del calendario argentino

Los cargos de Mercado Libre y el resultado solo se informan con una cotización vigente. Si la cotización está pendiente, tiene más de 8 días, fue invalidada, la promoción terminó o la cuenta necesita reconexión, esas métricas son null. listing_price se conserva.

El desglose usa la misma cotización de Mercado Libre, sin consultas adicionales. La comisión y la financiación se calculan sobre el precio con IVA. Si falta algún dato o la suma de los tres cargos difiere del total por más de un centavo, las tres métricas del desglose son null. Cero confirmado sigue siendo cero. El resultado descuenta listing_fee una sola vez, aunque consultes también el desglose.

recent_units resta las notas de crédito de los últimos 30 días. Si una venta tenía varias publicaciones del mismo producto, la devolución se reparte en proporción a sus unidades, así que puede tener decimales.

Para filtrar una publicación, usá marketplace_item_id. Los filtros sobre marketplace_listing buscan en el título. marketplace_listing_type y marketplace_logistic_type filtran por código (gold_special, gold_pro, free; fulfillment, cross_docking, xd_drop_off, drop_off, self_service, turbo). Las filas conservan los códigos en ids y muestran nombres en labels, como Clásica, Premium, Colecta y Full. Los valores sin nombre conocido se indican como sin identificar. La categoría de Mercado Libre todavía no está disponible como dimensión.

metadata.snapshot informa la hora de lectura y la ventana de unidades.

El acceso a esta fuente requiere permiso de reportes de ventas. Los datos financieros, incluidos filtros y orden por costo o margen, requieren permiso vigente para ver costos. La consulta requiere visibilidad de toda la organización. MCP run_report usa la misma fuente y el mismo cursor.

El resultado excluye publicidad, almacenamiento e ingreso a Full, devoluciones e impuestos retenidos. Leé cómo usar la estimación antes de tomar una decisión de precio.