---
title: "Listar facturas de compra"
method: POST
path: "/tools/expenses_list-bills"
tags: ["Gastos"]
---

# Listar facturas de compra

`POST /tools/expenses_list-bills`

## Request

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

Herramienta MCP: `expenses_list-bills`.

Lista facturas de compra (gastos) con filtros opcionales de estado, rango de fechas, proveedor, moneda, centro de costos y más. Soporta paginación con `start` y `limit` (hasta 200 por página).

Por defecto devuelve una versión ligera de cada documento; usa `fields` para incluir campos adicionales (por ejemplo `totalTaxes`, `retentions`, `payments`) y `simple: true` para objetos aún más reducidos.

Úsala para descubrir los `id` numéricos que necesita `expenses_get-bill`, auditar gastos por proveedor o período, o revisar documentos pendientes de pago. Para ver el detalle completo de un documento, usa `expenses_get-bill`.

Notas por país: en México las facturas de compra son CFDI; en República Dominicana usan NCF/ECF. En Colombia el tipo por defecto es `bill` (también acepta `supportDocument`); en Panamá, Perú, España y Venezuela `type` acepta `all` para ambas clases de documento. El filtro `currency` usa el código de la moneda local de cada país (por ejemplo MXN, DOP, COP).

Solo lectura.

## Request body

- object
  - `billNumber_equals` string: Coincidencia exacta del número de la factura de compra.
  - `client_id` integer: ID numérico local del proveedor. Filtra los documentos de ese proveedor.
  - `costCenter_id` string: ID del centro de costos. Usa "null", "none" o "0" para filtrar documentos sin centro de costos.
  - `createdAt_earlierThanOrEqualTo` string: Filtro: fecha de creación <= valor (ISO 8601).
  - `createdAt_laterThanOrEqualTo` string: Filtro: fecha de creación >= valor (ISO 8601).
  - `createdBy` string: Filtra por identificador del usuario que creó el documento.
  - `currency` string: Filtra por código de moneda (por ejemplo USD).
  - `date` string: Fecha de emisión exacta (YYYY-MM-DD).
  - `date_afterOrNow` string: Filtro: fecha de emisión >= valor (YYYY-MM-DD).
  - `date_beforeOrNow` string: Filtro: fecha de emisión <= valor (YYYY-MM-DD).
  - `decimalMode` 'calculation' | 'display': Modo de redondeo de los totales: 'calculation' usa la escala de la empresa, 'display' usa la precisión de visualización.
  - `dueDate` string: Fecha de vencimiento exacta (YYYY-MM-DD).
  - `dueDate_between` string: Rango de vencimiento: "YYYY-MM-DD,YYYY-MM-DD".
  - `dueDate_earlierThanOrEqualTo` string: Filtro: fecha de vencimiento <= valor (YYYY-MM-DD).
  - `dueDate_laterThanOrEqualTo` string: Filtro: fecha de vencimiento >= valor (YYYY-MM-DD).
  - `emissionStatus` string: Filtro de estado de emisión electrónica, separado por comas.
  - `excludePaidBills` boolean: Excluye de los resultados las facturas totalmente pagadas.
  - `fields` string: Campos adicionales separados por comas: editable, deletable, comments, journal, url, purchaseOrders, totalTaxes, subTotal, advances, retentions, createdAt, updatedAt, idGlobal, uid, stamp, etc.
  - `fullNumber` string: Coincidencia parcial del número completo del documento.
  - `ids` string: Lista separada por comas de IDs locales a recuperar, por ejemplo '1,2,3' (máximo 30).
  - `item_id` integer: Filtra documentos que contengan un ítem con este ID local.
  - `limit` integer: Registros por página (0–200). Por defecto 30.
  - `order_direction` 'ASC' | 'DESC': Dirección del orden: ASC (ascendente) o DESC (descendente).
  - `order_field` 'billNumber' | 'name' | 'date' | 'dueDate' | 'id': Campo por el que se ordenan los resultados.
  - `provider_name` string: Filtra por nombre del proveedor (coincidencia parcial).
  - `purchaseOrder_id` integer: Filtra facturas asociadas a un ID de orden de compra.
  - `simple` boolean: Devuelve objetos simplificados con menos campos.
  - `start` integer: Desplazamiento inicial de la paginación (0 para la primera página).
  - `status` string: Filtro de estado separado por comas, por ejemplo 'open,draft'. Valores: draft, open, paid, void.
  - `type` 'bill' | 'supportDocument' | 'all': Filtro por tipo de documento: 'bill' para facturas estándar, 'supportDocument' para documentos soporte de compra. En Colombia el valor por defecto es 'bill'; en Panamá, Perú, España y Venezuela 'all' incluye ambas clases.
  - `uuid` string: Busca un único documento por su UUID.
  - `uuids` string: Lista separada por comas de UUIDs a recuperar.
  - `warehouse_id` integer: Filtra por ID local de la bodega.

## Response `200`

Lista de facturas de compra

## Other responses

- `401`: No autorizado

---

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