NewThe SII in Live, under contract
BeeL
Get startedMulti-NIFVeriFactuSIIRulesStripeAPI referenceChangelog
Invoices

List invoices

Scopeinvoices:read

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.


GET
/v1/companies/{company_id}/invoices
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

Path Parameters

company_idstring

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.

Formatuuid

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. An empty value (status=) is the same as omitting the parameter.

payment_method?array<PaymentMethod>

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.

type?string

Filter by invoice type

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

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.

Defaulttrue
pending_collection_only?boolean

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.

Defaultfalse
customer_id?string

Filter by customer UUID

Formatuuid
date_from?string

Date from, inclusive (YYYY-MM-DD). It applies to the operation date when set, and to the issue date otherwise.

Formatdate
date_to?string

Date to, inclusive (YYYY-MM-DD). Applies to the same date as date_from.

Formatdate
due_date_from?string

Due date from, inclusive (YYYY-MM-DD). Invoices without a due date are excluded.

Formatdate
due_date_to?string

Due date to, inclusive (YYYY-MM-DD). Invoices without a due date are excluded.

Formatdate
payment_date_from?string

Payment date from, inclusive (YYYY-MM-DD). Invoices without a payment date are excluded.

Formatdate
payment_date_to?string

Payment date to, inclusive (YYYY-MM-DD). Invoices without a payment date are excluded.

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

rectified_invoice_id?string

Return the corrective invoices that correct this invoice. Accepts the id of an issued invoice; a single invoice can have several partial correctives.

Formatuuid
replaced_by_invoice_id?string

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

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

Value in"PENDING" | "ACCEPTED" | "ACCEPTED_WITH_ERRORS" | "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 To filter by a custom field, use custom_fields[<key>].

Propertiesproperties <= 50
custom_fields?

Filter 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

Propertiesproperties <= 20
sort_by?string

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.

sort_order?string
Value in"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.