beel_list_invoices
Retrieve a paginated list of a company's invoices and filter by status, type, series, customer, date range, or free text.
Instructions
Returns a paginated list of the invoices of this company, filterable by status, type, series, customer, date range and free text. Only the documents of the company in the path are returned.
BeeL API endpoint: GET /v1/companies/{company_id}/invoices (reference: https://docs.beel.es)
⚠️ Read before calling:
Fiscal rules, domains lifecycle: beel_rules_list with domain, or resource beel://guardrails/.
The status names, the proforma lifecycle, and which tool performs each operation. (resource: beel://guardrails/invoice-state-machine)
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"company_id": "<company_id>"
},
"name": "beel_list_invoices"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number, starting at 1. The response echoes it back as `pagination.current_page`. | |
| type | No | Filter by invoice type | |
| limit | No | How many items to return per page. The response echoes it back as `pagination.items_per_page`. | |
| search | No | Global search across invoice number, recipient name, recipient NIF, and series code (partial, case-insensitive) | |
| status | No | Filter by invoice status. Accepts a comma-separated list to match any of several statuses, for example `status=DRAFT,ISSUED`. A single value is also valid. An empty value (`status=`) is the same as omitting the parameter. | |
| date_to | No | Date to, inclusive (YYYY-MM-DD). Applies to the same date as `date_from`. | |
| sort_by | No | Field to sort by: `issue_date` (default), `operation_date`, `due_date`, `invoice_number`, `series_code`, `status`, `invoice_total`, `taxable_base`, `total_vat`, `total_equivalence_surcharge`, `total_discounts`, `recipient_name`, `recipient_nif`, `created_at` or `updated_at`. Any other value is rejected with `400` `VALIDATION_ERROR`, whose `details` name `sort_by` and the accepted values. `invoice_number` sorts by series code and then by the number within the series, compared numerically (`F-9` before `F-10`). Ties on any field are broken by series code, then by the number within the series and then by id, in the requested direction. | |
| metadata | No | Filter by metadata key/value pairs (exact match, AND between keys). Repeat the bracket-style param to filter on multiple keys. Max 50 pairs per request. Keys must match `^[A-Za-z0-9_\-.]{1,64}$`. Example: `?metadata[external_order_id]=ORD-42&metadata[tenant]=acme` | |
| date_from | No | Date from, inclusive (YYYY-MM-DD). It applies to the operation date when set, and to the issue date otherwise. | |
| total_max | No | Maximum invoice total | |
| total_min | No | Minimum invoice total | |
| company_id | Yes | Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the `BeeL-Active-Company` header plays no part. A company you do not reach answers `403`, and so does a company that does not exist, so the existence of a company in another account is never disclosed. | |
| sort_order | No | Sort direction | desc |
| customer_id | No | Filter by customer UUID | |
| fiscal_only | No | When `true` (the default), returns only fiscal documents (STANDARD, CORRECTIVE, SIMPLIFIED), excluding proformas and any other non-fiscal document. Set it to `false` to list every document type. Ignored when an explicit `type` is given: use `type=PROFORMA` to list proformas. | |
| series_code | No | Filter by series code (exact match, case-insensitive). Use `search` for partial matching across the invoice number, recipient and series code. | |
| external_ref | No | Filter by exact external reference (client-supplied order/cart/contract id). | |
| recipient_nif | No | Filter by recipient's NIF (partial search) | |
| invoice_number | No | Search by invoice number (e.g., 2025/0001) | |
| payment_method | No | Filter by payment method. Accepts a comma-separated list to match any of several methods, for example `payment_method=DIRECT_DEBIT,CARD`. A single value is also valid. `NONE` also matches invoices that have no payment method stored. Combine it with `date_from`/`date_to` to list, for example, the direct debits of a month. An empty value (`payment_method=`) is the same as omitting the parameter. | |
| recipient_name | No | Filter by recipient's fiscal name (partial, case-insensitive search) | |
| taxable_base_max | No | Maximum taxable base | |
| taxable_base_min | No | Minimum taxable base | |
| verifactu_status | No | Filter by the VeriFactu submission status of the invoice, using the very same vocabulary that `verifactu.submission_status` publishes on each invoice. `NOT_SUBMITTED` selects issued invoices with VeriFactu enabled whose registration never happened (no live record). | |
| verifactu_enabled | No | Filter by whether VeriFactu is enabled for the invoice — the same flag published as `verifactu.enabled`. `false` returns the invoices that never reach AEAT. | |
| rectified_invoice_id | No | Return the corrective invoices that correct this invoice. Accepts the id of an issued invoice; a single invoice can have several partial correctives. | |
| pending_collection_only | No | When `true`, returns only the invoices pending collection: STANDARD, SIMPLIFIED or CORRECTIVE invoices in status ISSUED, SENT, OVERDUE or RECTIFIED with no payment recorded (no `payment_date`). A CORRECTIVE invoice whose original invoice is `VOIDED` with no `payment_date` is left out: nothing is owed and nothing has to be refunded for that pair. One whose original has a `payment_date` is included. It combines with the other filters, so a `status` or `type` outside that set returns an empty list. `false`, the default, does not filter. |