NewThree filters returned the wrong rows
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Invoices

List invoices

Scopeinvoices:read

Returns a paginated list of invoices, with filters, sorting and pagination.

  • Deprecated: use GET /v1/companies/{company_id}/invoices, which returns the same list with the same filters.
  • Difference: the legacy alias external_reference is not carried over there. Use external_ref, which this route also accepts.
GET
/v1/invoices

Authorization

AuthorizationBearer <token>

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

Query Parameters

page?integer

Page number, starting at 1. The response echoes it back as pagination.current_page.

Default1
Range1 <= value
limit?integer

How many items to return per page. The response echoes it back as pagination.items_per_page.

Default20
Range1 <= value <= 100
search?string

Global search across invoice number, recipient name, recipient NIF, and series code (partial, case-insensitive)

status?array<InvoiceStatus>

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.

Items1 <= items
type?string

Filter by invoice type

Value in"STANDARD" | "CORRECTIVE" | "SIMPLIFIED" | "PROFORMA"
fiscal_only?boolean

When true, returns only fiscal documents (STANDARD, CORRECTIVE, SIMPLIFIED), excluding proformas and any other non-fiscal document. Defaults to false (the list returns every document type). Ignored when an explicit type is given.

Defaultfalse
customer_id?string

Filter by customer UUID

Formatuuid
date_from?string

Issue date from (YYYY-MM-DD)

Formatdate
date_to?string

Issue date to (YYYY-MM-DD)

Formatdate
invoice_number?string

Search by invoice number (e.g., 2025/0001)

recipient_name?string

Filter by recipient's fiscal name (partial, case-insensitive search)

recipient_nif?string

Filter by recipient's NIF (partial search)

series_code?string

Filter by series code (exact match, case-insensitive). Use search for partial matching across the invoice number, recipient and series code.

external_ref?string

Filter by exact external reference (client-supplied order/cart/contract id).

This parameter was previously named external_reference. The old name is still accepted for backwards compatibility (see external_reference below) and will be withdrawn in a future major version — send external_ref.

external_reference?stringDeprecated

Deprecated — former name of external_ref, still honoured so existing integrations keep working. Ignored when external_ref is also present. Use external_ref.

taxable_base_min?number

Minimum taxable base

Formatdouble
taxable_base_max?number

Maximum taxable base

Formatdouble
total_min?number

Minimum invoice total

Formatdouble
total_max?number

Maximum invoice total

Formatdouble
verifactu_status?string

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

Only invoices with VeriFactu enabled can match. To select the ones outside the axis (VeriFactu disabled), use verifactu_enabled=false instead.

Value in"PENDING" | "ACCEPTED" | "VOIDED" | "REJECTED" | "NOT_SUBMITTED"
verifactu_enabled?boolean

Filter by whether VeriFactu is enabled for the invoice — the same flag published as verifactu.enabled. false returns the invoices that never reach AEAT.

metadata?

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

Propertiesproperties <= 50
sort_by?string

Field to sort by (e.g., issue_date, invoice_number, invoice_total)

sort_order?string
Value in"asc" | "desc"

Header Parameters

BeeL-Active-Company?string

Which company (tax ID) the request operates on.

An API key belongs to an account, and an account may hold several companies. Endpoints that read or write company-owned data — invoices, customers, products, series, tax and VeriFactu settings — resolve their target company from this header when the path does not already name one.

On a path that names the company, such as /v1/companies/{company_id}/invoices, the path is the target and this header is not read at all: it neither switches the target nor makes the request fail, so sending one that disagrees with the path is silently ignored rather than rejected. Prefer those paths whenever you need to be explicit about which tax ID you are operating on.

On an account holding a single company the header may be omitted — that company is used. On an account holding several it is required: the request fails with 403 ACTIVE_COMPANY_REQUIRED otherwise. A company-owned record always belongs to one tax ID, so operating on it without saying which one has no meaning.

The company does not have to belong to the API key's own account: one you manage works too, which is what makes the company_id returned by POST /v1/accounts usable here to invoice on a provisioned account's behalf. What you may do with it is then decided by your access level over that account, and issuing also requires a signed fiscal representation.

This header is how you operate on a company, never how you find one: a value you do not reach answers 403, the same as one that does not exist, so guessing reveals nothing. Get the company_id from the response that created the company.

Requires the companies:read scope. Returns 403 if the company is neither yours nor one you manage.

Formatuuid

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/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"
      },
      {
        "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"
      },
      {
        "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"
      }
    ],
    "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": "FORBIDDEN",
    "message": "You do not have permission to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "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. - **Deprecated:** use `GET /v1/companies/{company_id}/invoices/{invoice_id}`, which behaves identically.

Get invoice PDF download URL GET

Returns a temporary pre-signed URL to download the invoice PDF. - **Deprecated:** use `GET /v1/companies/{company_id}/invoices/{invoice_id}/pdf`, which behaves identically. - **URL:** it expires in five minutes and only allows `GET`.