List invoices
Scopeinvoices:readReturns 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.
Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key
short of the scope an operation needs is answered 403. The scope an operation requires
is shown next to its title, and the full catalogue lives in the Scopes reference.
Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.
In: header
Path Parameters
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.
uuidQuery Parameters
Page number, starting at 1. The response echoes it back as pagination.current_page.
11 <= valueHow many items to return per page. The response echoes it back as pagination.items_per_page.
201 <= value <= 100Global search across invoice number, recipient name, recipient NIF, and series code (partial, case-insensitive)
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.
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.
Filter by invoice type
"STANDARD" | "CORRECTIVE" | "SIMPLIFIED" | "PROFORMA"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.
trueWhen 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.
falseFilter by customer UUID
uuidDate from, inclusive (YYYY-MM-DD). It applies to the operation date when set, and to the issue date otherwise.
dateDate to, inclusive (YYYY-MM-DD). Applies to the same date as date_from.
dateDue date from, inclusive (YYYY-MM-DD). Invoices without a due date are excluded.
dateDue date to, inclusive (YYYY-MM-DD). Invoices without a due date are excluded.
datePayment date from, inclusive (YYYY-MM-DD). Invoices without a payment date are excluded.
datePayment date to, inclusive (YYYY-MM-DD). Invoices without a payment date are excluded.
dateSearch by invoice number (e.g., 2025/0001)
Filter by recipient's fiscal name (partial, case-insensitive search)
Filter by recipient's NIF (partial search)
Filter by series code (exact match, case-insensitive). Use search for partial matching across the invoice number, recipient and series code.
Filter by exact external reference (client-supplied order/cart/contract id).
Return the corrective invoices that correct this invoice. Accepts the id of an issued invoice; a single invoice can have several partial correctives.
uuidReturn the simplified invoices replaced by this exchange invoice. Accepts the id of an
issued full invoice; it matches the ids in its replaced_invoice_ids.
uuidMinimum taxable base
doubleMaximum taxable base
doubleMinimum invoice total
doubleMaximum invoice total
doubleFilter 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).
"PENDING" | "ACCEPTED" | "ACCEPTED_WITH_ERRORS" | "VOIDED" | "REJECTED" | "NOT_SUBMITTED"Filter by whether VeriFactu is enabled for the invoice — the same flag published as
verifactu.enabled. false returns the invoices that never reach AEAT.
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
To filter by a custom field, use custom_fields[<key>].
properties <= 50Filter by the custom fields saved on the invoice, written as custom_fields[<key>]=<value>.
The value is compared with the text stored on the invoice, exactly (case and accents
included); several keys are combined with AND, and with the other filters. Max 20 keys
per request. A key the company does not have matches no invoice.
Example: ?custom_fields[project]=North&custom_fields[cost_centre]=CC-12
properties <= 20Field 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.
"asc" | "desc"Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://app.beel.es/api/v1/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoices"Invoice list with pagination metadata
{
"success": true,
"data": {
"invoices": [
{
"id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
"invoice_number": "A/2025/0042",
"series": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"code": "A"
},
"number": 42,
"type": "STANDARD",
"status": "ISSUED",
"issue_date": "2025-01-20",
"due_date": "2025-02-20",
"issuer": {
"legal_name": "Mi Empresa SL",
"nif": "B12345674",
"address": {
"street": "Calle Principal",
"number": "10",
"postal_code": "28001",
"city": "Madrid",
"province": "Madrid",
"country": "España"
}
},
"recipient": {
"customer_id": "123e4567-e89b-12d3-a456-426614174000",
"legal_name": "Cliente Ejemplo SL",
"nif": "B87654321",
"address": {
"street": "Calle Secundaria",
"number": "20",
"postal_code": "08001",
"city": "Barcelona",
"province": "Barcelona",
"country": "España"
}
},
"lines": [
{
"description": "Consulting services",
"quantity": 10,
"unit": "hours",
"unit_price": 150,
"taxable_base": 1500,
"main_tax": {
"type": "IVA",
"percentage": 21,
"regime_key": "01"
},
"line_total": 1815
}
],
"totals": {
"taxable_base": 1500,
"total_vat": 315,
"total_irpf": 0,
"total_equivalence_surcharge": 0,
"vat_breakdown": [
{
"type": 21,
"base": 1500,
"amount": 315
}
],
"invoice_total": 1815
},
"pdf_download_url": "/v1/companies/7c9e6679-7425-40de-944b-e07fc1f90ae7/invoices/f47ac10b-58cc-4372-a567-0e02b2c3d479/pdf",
"created_at": "2025-01-20T09:00:00Z",
"updated_at": "2025-01-20T09:30:00Z",
"rendering": {
"invoice_design_id": "7d1c3a52-4b9e-4f0a-9a51-3c2e8f6b1d20",
"invoice_design_version": 3,
"language": "es"
},
"compliance": [],
"custom_fields": [
{
"key": "store",
"label": "Store",
"value": "Gran Vía 12"
}
]
},
{
"id": "550e8400-e29b-41d4-a716-446655440002",
"invoice_number": "A/2025/0041",
"series": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"code": "A"
},
"number": 41,
"type": "STANDARD",
"status": "PAID",
"issue_date": "2025-01-15",
"due_date": "2025-02-15",
"payment_date": "2025-01-18",
"sent_at": "2025-01-16T10:00:00Z",
"paid_at": "2025-01-18T14:00:00Z",
"issuer": {
"legal_name": "Mi Empresa SL",
"nif": "B12345674",
"address": {
"street": "Calle Principal",
"number": "10",
"postal_code": "28001",
"city": "Madrid",
"province": "Madrid",
"country": "España"
}
},
"recipient": {
"customer_id": "456e7890-e12b-34d5-a678-901234567890",
"legal_name": "Otro Cliente SA",
"nif": "A12345678",
"address": {
"street": "Avenida Central",
"number": "100",
"postal_code": "46001",
"city": "Valencia",
"province": "Valencia",
"country": "España"
}
},
"lines": [
{
"description": "Software development",
"quantity": 50,
"unit": "hours",
"unit_price": 50,
"taxable_base": 2500,
"main_tax": {
"type": "IVA",
"percentage": 21,
"regime_key": "01"
},
"line_total": 3025
}
],
"totals": {
"taxable_base": 2500,
"total_vat": 525,
"total_irpf": 0,
"total_equivalence_surcharge": 0,
"vat_breakdown": [
{
"type": 21,
"base": 2500,
"amount": 525
}
],
"invoice_total": 3025
},
"pdf_download_url": "/v1/companies/7c9e6679-7425-40de-944b-e07fc1f90ae7/invoices/550e8400-e29b-41d4-a716-446655440002/pdf",
"created_at": "2025-01-15T10:00:00Z",
"updated_at": "2025-01-18T14:00:00Z",
"rendering": {
"invoice_design_id": "7d1c3a52-4b9e-4f0a-9a51-3c2e8f6b1d20",
"invoice_design_version": 3,
"language": "es"
},
"compliance": [],
"custom_fields": []
},
{
"id": "550e8400-e29b-41d4-a716-446655440003",
"invoice_number": "A/2025/0040",
"series": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"code": "A"
},
"number": 40,
"type": "STANDARD",
"status": "OVERDUE",
"issue_date": "2024-12-10",
"due_date": "2025-01-10",
"issuer": {
"legal_name": "Mi Empresa SL",
"nif": "B12345674",
"address": {
"street": "Calle Principal",
"number": "10",
"postal_code": "28001",
"city": "Madrid",
"province": "Madrid",
"country": "España"
}
},
"recipient": {
"customer_id": "789e0123-e45b-67d8-a901-234567890123",
"legal_name": "Cliente Moroso SL",
"nif": "B98765432",
"address": {
"street": "Plaza Mayor",
"number": "5",
"postal_code": "41001",
"city": "Sevilla",
"province": "Sevilla",
"country": "España"
}
},
"lines": [
{
"description": "Web maintenance",
"quantity": 1,
"unit": "unit",
"unit_price": 800,
"taxable_base": 800,
"main_tax": {
"type": "IVA",
"percentage": 21,
"regime_key": "01"
},
"line_total": 968
}
],
"totals": {
"taxable_base": 800,
"total_vat": 168,
"total_irpf": 0,
"total_equivalence_surcharge": 0,
"vat_breakdown": [
{
"type": 21,
"base": 800,
"amount": 168
}
],
"invoice_total": 968
},
"pdf_download_url": "/v1/companies/7c9e6679-7425-40de-944b-e07fc1f90ae7/invoices/550e8400-e29b-41d4-a716-446655440003/pdf",
"created_at": "2024-12-10T11:00:00Z",
"updated_at": "2024-12-10T11:00:00Z",
"rendering": null,
"compliance": [],
"custom_fields": []
}
],
"pagination": {
"current_page": 1,
"items_per_page": 20,
"total_items": 3,
"total_pages": 1,
"has_next": false,
"has_previous": false
}
},
"meta": {
"timestamp": "2025-01-20T12:00:00Z",
"request_id": "550e8400-e29b-41d4-a716-446655440000"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The parameter 'invoice_id' has an invalid type. Expected: UUID.",
"details": {
"field": "invoice_id",
"invalid_value": "deliveries",
"expected_format": "UUID"
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNAUTHORIZED",
"message": "Authentication is required to access this resource"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "The provided data is not valid",
"details": {
"field": "specific error message"
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
},
"type": "https://docs.beel.es/errors/INVOICE_NO_LINES",
"title": "INVOICE_NO_LINES",
"detail": "The invoice must have at least one line",
"instance": "/v1/invoices/abc-123"
}{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "Validation constraint violation.",
"details": {
"limit": "must be greater than or equal to 1"
}
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "RATE_LIMIT_EXCEEDED",
"message": "Too many requests. Please try again in 60 seconds."
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "INTERNAL_ERROR",
"message": "Internal server error"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}{
"success": false,
"error": {
"code": "UNSUPPORTED_MEDIA_TYPE",
"message": "Unsupported media type: text/plain. Supported: application/json"
},
"meta": {
"timestamp": "2025-01-15T10:30:00Z",
"request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}
}Get an invoice GET
Retrieves the full details of an invoice of this company.
Get the PDF download URL of an invoice GET
Returns a temporary pre-signed URL to download the invoice PDF. - **URL:** expires in five minutes and only allows `GET`. - **Waiting:** a PDF is produced asynchronously, so this request **waits** for it (up to ten seconds) instead of handing you a polling loop to write. Bound the wait with `Prefer: wait=N`, or opt out with `Prefer: wait=0`. - **`202`:** only when the wait elapsed with the PDF still in flight. No body is returned; ask again after `Retry-After`. - **Drafts:** a draft has no fiscal PDF and answers `400 INVOICE_NOT_ISSUED_NO_PDF` immediately — that one never waits. Issue it, or render it with `GET …/{invoice_id}/pdf/preview`. - **Not registered with the AEAT:** under VeriFactu the PDF carries the QR code of the invoice's registration. An invoice whose registration was rejected before reaching the AEAT, or that was voided without ever being registered, has no PDF and answers `400 INVOICE_NOT_REGISTERED_NO_PDF` immediately. Its `verifactu.error_message` says why. - **Unavailable on our side:** when the invoice needs its VeriFactu QR and BeeL. cannot produce the PDF, the answer is `409 INVOICE_PDF_UNAVAILABLE` immediately instead of a `202` that would never end. Asking again does not help: contact support with the `meta.request_id`. Once it is solved, the same request returns the PDF. - **Never modified:** the PDF of an issued invoice is generated once — with its VeriFactu QR when it applies — and stays the document you delivered. Voiding the invoice or issuing a corrective against it does not change the PDF: read the invoice's `status` to know it.