---
title: "Consultar detalle de retenciones"
method: POST
path: "/tools/reports_get_retentions_detail"
tags: ["Reports"]
---

# Consultar detalle de retenciones

`POST /tools/reports_get_retentions_detail`

## Request

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

Herramienta MCP: `reports_get_retentions_detail`.

Devuelve el detalle de los documentos que componen las retenciones (practicadas o recibidas) de la compañía en un periodo. El parámetro `type` define la ruta interna y sus valores dependen del país.

Notas por país: para empresas de México usa únicamente `retentions-in` o `retentions-out`, que consultan retrieve-all-transactions-with-retentions y devuelven `{ success, transactions }` sin paginación. Para todos los demás países usa `sales` (retenciones en ventas) o `bills` (retenciones en compras), que consultan taxes-retentions v2 con paginación por `page` y `limit`. Los filtros distintos de las fechas y de `type` solo aplican fuera de México.

Úsala cuando el usuario pida el detalle documento por documento de las retenciones: qué documentos las generaron, con qué base, porcentaje y valor. Para el reporte agregado del periodo usa `reports_get_retentions_report` en su lugar.

Ejemplo de llamada JSON-RPC:

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "reports_get_retentions_detail",
    "arguments": { "dateFrom": "2026-09-01", "dateTo": "2026-09-30", "type": "bills" }
  }
}
```

Los parámetros `dateFrom`, `dateTo` y `type` son obligatorios; las fechas van en formato YYYY-MM-DD y `type` se envía exactamente con los valores indicados, sin traducirlo.

Solo lectura.

## Request body

- object
  - `dateFrom` string, required: Fecha inicial del periodo, en formato YYYY-MM-DD.
  - `dateTo` string, required: Fecha final del periodo, en formato YYYY-MM-DD.
  - `type` 'sales' | 'bills' | 'retentions-in' | 'retentions-out', required: Tipo de retención, exactamente como lo espera cada endpoint: `sales` (ventas) o `bills` (compras) en todos los países excepto México; `retentions-in` o `retentions-out` solo en México. No traducir.
  - `retentionId` string: Filtra por una retención específica (idRetention). Solo aplica fuera de México.
  - `customerId` string: Filtra por tercero/cliente (idClient). Solo aplica fuera de México.
  - `documentNumber` string: Filtra por número de documento. Solo aplica fuera de México.
  - `documentType` string: Filtra por tipo de documento. Solo aplica fuera de México.
  - `date` string: Filtra por un solo día, en formato YYYY-MM-DD. Solo aplica fuera de México.
  - `economicActivityId` string: Filtra por actividad económica. Solo aplica fuera de México.
  - `page` integer: Número de página (base 1). Por defecto 1. Solo aplica fuera de México.
  - `limit` integer: Máximo de resultados por página. Por defecto 10. Solo aplica fuera de México.

## Response `200`

Detalle de los documentos que componen las retenciones del periodo

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