---
title: "bills__list_bills"
method: POST
path: "/tools/bills__list_bills"
tags: ["Gastos"]
---

# bills__list_bills

`POST /tools/bills__list_bills`

### MCP
Herramienta lógica `list_bills`. Nombre típico: `bills__list_bills` (p. ej. `expenses__list_bills` según el servidor).

### HTTP
`GET /v1/bills` — Query: todos los parámetros opcionales van en `arguments` como claves planas (equivalente a query string).

### Respuesta exitosa
HTTP **200**: arreglo de bills, o `{ metadata: { total }, data: [...] }` si `metadata=true`.

### Errores frecuentes
| Código | Significado | Acción |
|--------|-------------|--------|
| 903 | Paginación inválida (start/limit) | start≥0; limit dentro del máximo del API |
| 400 | Validación | Revisar `message` y `code` en el cuerpo |

### Filtros proveedor
`client_id` exacto: si no existe ese proveedor, **cero resultados** (no es error). No combinar lógica de intersección con `client_name`/`provider_name`; usar id **o** nombre (ver guía `list_filter_semantics` en la fuente).

### Campos expandidos
Usar `fields` como lista separada por comas; ver `fields_query_param` y `fields_guidance` en la guía pública (stamp, xml, retentions, journal, etc.).

## Request body

- object — Parámetros de query GET /v1/bills (todos opcionales salvo uso de filtros).
  - `start` integer — Offset ≥0
  - `limit` integer — Tamaño de página (máx. típico 200)
  - `fields` string — Campos extra separados por comas
  - `decimalMode` 'calculation' | 'display'
  - `simple` boolean
  - `metadata` string — 'true' para envoltorio metadata+data
  - `order_field` 'billNumber' | 'name' | 'date' | 'dueDate' | 'id'
  - `order_direction` 'ASC' | 'DESC'
  - `uuid` string
  - `uuids` string
  - `ids` string
  - `idGlobal` string
  - `exclude_id` string
  - `fullNumber` string
  - `billNumber_equals` string
  - `status` string — draft,open,paid,void (separados por coma)
  - `type` 'bill' | 'supportDocument' | 'all' — Colombia suele default bill
  - `client_id` integer
  - `client_name` string
  - `provider_name` string
  - `date` string, date
  - `date_afterOrNow` string
  - `date_beforeOrNow` string
  - `dueDate` string
  - `dueDate_earlierThanOrEqualTo` string
  - `dueDate_laterThanOrEqualTo` string
  - `dueDate_between` string — start,end
  - `createdAt_laterThanOrEqualTo` string, date-time
  - `createdAt_earlierThanOrEqualTo` string, date-time
  - `createdBy` string
  - `item_id` integer
  - `purchaseOrder_id` integer
  - `currency` string
  - `warehouse_id` integer
  - `costCenter_id` string
  - `emissionStatus` string
  - `areElectronic` boolean
  - `excludePaidBills` boolean
  - `excludePrefix` string
  - `includeVoidPayments` 'yes' | 'no'

## Response `200`

Lista de bills o metadata+data

---

[API](https://skmtc.net/alegra/apis/ingresos.md) · [All operations](https://skmtc.net/alegra/apis/ingresos/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/alegra/ingresos/versions/cd52d3f68f1b/schema)