---
title: "Totalizar ventas por periodo"
method: POST
path: "/tools/reports_get_general_sales_totals"
tags: ["Reports"]
---

# Totalizar ventas por periodo

`POST /tools/reports_get_general_sales_totals`

## Request

- Base URL: `https://mcp.alegra.com`
- URL: `https://mcp.alegra.com/tools/reports_get_general_sales_totals`
- Auth: HTTP bearer

Herramienta MCP: `reports_get_general_sales_totals`.

Devuelve los totales de ventas agregados y AGRUPADOS POR PERIODO DE TIEMPO (día, mes o año): para cada periodo muestra los montos de ventas (`beforeTaxes`, `tax`, `total`, `discount`, `creditNote`).

Ejemplo de llamada JSON-RPC:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "reports_get_general_sales_totals",
    "arguments": { "from": "2026-09-01", "to": "2026-09-30", "groupBy": "month" }
  }
}
```

Úsala cuando el usuario pregunte por cuánto se vendió en un periodo, por dia, mes o año: "¿cuántas ventas hubo en septiembre?", "¿cuál fue el total facturado por mes este año?". Para el detalle documento por documento usa `reports_get_general_sales_documents` en su lugar.

Las fechas `from` y `to` son obligatorias y van en formato YYYY-MM-DD. Elige la granularidad de `groupBy` según el nivel de detalle de la consulta del usuario. Los filtros adicionales van dentro de `optionalParams`, que debe enviarse como objeto JSON, nunca como cadena de texto.

Solo lectura.

## Request body

- object
  - `from` string, required: Fecha inicial del rango, en formato YYYY-MM-DD. Calcúlala a partir de la consulta del usuario (por ejemplo, "enero de 2024" → "2024-01-01").
  - `to` string, required: Fecha final del rango, en formato YYYY-MM-DD. Calcúlala a partir de la consulta del usuario (por ejemplo, "enero de 2024" → "2024-01-31").
  - `groupBy` 'day' | 'month' | 'year': Agrupación por periodo de tiempo: day para diario, month para mensual, year para anual. Por defecto day. Elígela según el nivel de detalle de la consulta del usuario.
  - `optionalParams` object: Filtros opcionales. CRÍTICO: este parámetro debe ser un objeto JSON, NUNCA una cadena de texto; no lo envíes como texto. Envíalo como objeto: {"documentStatus": "open"}. Ejemplos: {"documentTypes": "invoice"} para "facturas"; {"documentStatus": "open"} para documentos abiertos o cerrados.
    - `warehouseId` string: Filtra por ID de bodega. Úsalo cuando el usuario pida las ventas de una bodega o punto de despacho específico.
    - `customerId` string: Filtra por ID de cliente. Úsalo cuando el usuario pida documentos o totales de un cliente específico.
    - `documentName` string: Filtra por nombre o descripción del documento. IMPORTANTE: aplica solo a nombres o descripciones de documentos, no a nombres de vendedores, productos ni clientes.
    - `date` string: Filtra por una sola fecha (YYYY-MM-DD). Úsalo solo cuando el usuario pida una fecha puntual; para rangos usa `from` y `to`.
    - `documentStatus` 'closed' | 'open' | 'applied': Filtra por estado. CRÍTICO: si el usuario dice "documentos abiertos", "facturas abiertas" o solo "abiertas", usa "open"; si dice "cerradas", usa "closed". Valores: open, closed, applied.
    - `documentNumber` string: Filtra por número de documento. Úsalo cuando el usuario pida los totales de un número de documento específico.
    - `documentTypes` string: Filtra por tipo de documento. Si el usuario dice "facturas", usa "invoice"; si dice "facturas y notas crédito", usa "invoice,creditNote". Valores válidos: invoice, creditNote, incomeDebitNote.

## Response `200`

Totales de ventas agregados por periodo de tiempo

## Other responses

- `401`: No autorizado (token de Alegra inválido o expirado).

---

[API](https://skmtc.dev/alegra/apis/mcp-alegra.md) - [All operations](https://skmtc.dev/alegra/apis/mcp-alegra/llms.txt) - [OpenAPI document](https://skmtc.dev/alegra/apis/mcp-alegra/revisions/528447af020b?raw)