> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lapyme.com.ar/llms.txt
> Use this file to discover all available pages before exploring further.

# 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`, `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

```json theme={null}
{
  "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.                                                            |

<Info>
  Las métricas `currency` son centavos enteros. Dividí por 100 para obtener pesos o dólares.
</Info>

***

## 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 |

<Warning>
  Las métricas snapshot no pueden mezclarse con métricas derivadas en la misma solicitud.
</Warning>

<Info>
  Cuando se usan métricas derivadas, solo son compatibles las dimensiones `product`, `variant`, `category`, `product_type` y `warehouse`.
</Info>

### 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.

```json theme={null}
{
  "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:

```json theme={null}
{
  "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

```bash theme={null}
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)

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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

```bash theme={null}
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`