Reportes

Cómo funciona

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

source: qué datos consultar (sales, purchases, payments, 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 y payments; condicional para inventory).
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.

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"
    }
  }
}

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. Dividí por 100 para obtener pesos o dólares.

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
`point_of_sale`	Punto de venta
`warehouse`	Depósito
`register`	Caja
`integration_source`	Canal de integración (Mercado Libre, Tiendanube, etc.)
`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
`units`	units	integer	Unidades vendidas
`cost`	currency	cents	Costo de mercadería vendida
`margin`	currency	cents	Margen bruto (total - costo)
`avg_ticket`	currency	cents	Ticket promedio (calculado: total / count)
`margin_percent`	percentage	% (0-100)	Porcentaje de margen (calculado: margin / total 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, point_of_sale, point_of_sale_status, warehouse, warehouse_status, register, register_status, integration_source, 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
`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, 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: `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.

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
`days_of_inventory_remaining`	number	decimal	Días estimados de inventario restante al ritmo de ventas

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 y warehouse.

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

Dimensiones filtrables (`inventory`)

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

`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"]
  }'

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

Documentación

SDK

Referencia API

Cómo funciona

Forma de la respuesta

Fuente: `sales`

Dimensiones disponibles (`sales`)

Métricas disponibles (`sales`)

Dimensiones filtrables (`sales`)

Fuente: `purchases`

Dimensiones disponibles (`purchases`)

Métricas disponibles (`purchases`)

Dimensiones filtrables (`purchases`)

Fuente: `payments`

Dimensiones disponibles (`payments`)

Métricas disponibles (`payments`)

Dimensiones filtrables (`payments`)

Fuente: `inventory`

Métricas snapshot (sin `period`)

Métricas derivadas de ventas (requieren `period`)

Dimensiones disponibles (`inventory`)

Dimensiones filtrables (`inventory`)

`dimension_filters`

Ejemplos

Ventas por producto en Q1 2026

Ventas por mes y categoría (fiscal)

Compras por proveedor en marzo de 2026

Cobranzas y pagos por método en marzo de 2026

Stock disponible por producto y depósito

Días de inventario restante por categoría

Scope requerido

​Cómo funciona

​Forma de la respuesta

​Fuente: sales

​Dimensiones disponibles (sales)

​Métricas disponibles (sales)

​Dimensiones filtrables (sales)

​Fuente: purchases

​Dimensiones disponibles (purchases)

​Métricas disponibles (purchases)

​Dimensiones filtrables (purchases)

​Fuente: payments

​Dimensiones disponibles (payments)

​Métricas disponibles (payments)

​Dimensiones filtrables (payments)

​Fuente: inventory

​Métricas snapshot (sin period)

​Métricas derivadas de ventas (requieren period)

​Dimensiones disponibles (inventory)

​Dimensiones filtrables (inventory)

​dimension_filters

​Ejemplos

​Ventas por producto en Q1 2026

​Ventas por mes y categoría (fiscal)

​Compras por proveedor en marzo de 2026

​Cobranzas y pagos por método en marzo de 2026

​Stock disponible por producto y depósito

​Días de inventario restante por categoría

​Scope requerido

Cómo funciona

Forma de la respuesta

Fuente: `sales`

Dimensiones disponibles (`sales`)

Métricas disponibles (`sales`)

Dimensiones filtrables (`sales`)

Fuente: `purchases`

Dimensiones disponibles (`purchases`)

Métricas disponibles (`purchases`)

Dimensiones filtrables (`purchases`)

Fuente: `payments`

Dimensiones disponibles (`payments`)

Métricas disponibles (`payments`)

Dimensiones filtrables (`payments`)

Fuente: `inventory`

Métricas snapshot (sin `period`)

Métricas derivadas de ventas (requieren `period`)

Dimensiones disponibles (`inventory`)

Dimensiones filtrables (`inventory`)

`dimension_filters`

Ejemplos

Ventas por producto en Q1 2026

Ventas por mes y categoría (fiscal)

Compras por proveedor en marzo de 2026

Cobranzas y pagos por método en marzo de 2026

Stock disponible por producto y depósito

Días de inventario restante por categoría

Scope requerido