NewTell a voided invoice from a totally rectified one, without a second call
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Invoices

List the invoices of a company

Scopeinvoices:read

Returns a paginated list of the invoices issued under this company (NIF), with the same filters as the flat route. Only the documents of the company in the path are returned.

GET
/v1/companies/{company_id}/invoices

Authorization

AuthorizationBearer <token>

API Key authentication.

Format: Authorization: Bearer beel_sk_<key>

Scopes: API Keys use the same scopes as OAuth2 tokens. Each key is created with specific scopes that limit which endpoints it can access. The required scope for each endpoint is documented in the operation's security section under OAuth2.

Obtaining Keys: API Keys are managed from the BeeL dashboard

Security: API Keys are secret credentials. Do not share them or store them in source code

In: header

Path Parameters

company_idstring

NIF (company) the operation acts on. 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 NIF you do not reach answers 403, and so does a NIF that does not exist, so the existence of a NIF 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.

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

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
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" | "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"

Response Body

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"
{
  "success": true,
  "data": {
    "invoices": [
      {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "company_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
        "invoice_number": "2025/0001",
        "series": {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "code": "FAC"
        },
        "number": 1,
        "type": "STANDARD",
        "status": "SCHEDULED",
        "issue_date": "2025-01-15",
        "operation_date": "2025-01-10",
        "due_date": "2025-02-14",
        "valid_until": "2025-02-28",
        "payment_date": "2025-01-20",
        "sent_at": "2025-01-29T18:45:00Z",
        "paid_at": "2025-02-05T10:30:00Z",
        "auto_emit_after": "2025-03-20",
        "scheduled_for": "2025-02-15",
        "scheduled_action": "DRAFT",
        "issuer": {
          "legal_name": "Juan Pérez García",
          "trade_name": "JP Web Development",
          "nif": "12345678A",
          "address": {
            "street": "Calle Mayor, 123",
            "number": "123",
            "floor": "2º A",
            "door": "A",
            "postal_code": "28001",
            "city": "Madrid",
            "province": "Madrid",
            "country": "España",
            "country_code": "ES"
          },
          "phone": "+34 612 345 678",
          "email": "user@example.com",
          "website": "https://beel.es",
          "logo_url": "string",
          "additional_info": "Nº Colegiado: 12345"
        },
        "recipient": {
          "customer_id": "160c0c4b-9966-4dc1-a916-8407eb10d74e",
          "legal_name": "Empresa SL",
          "trade_name": "Empresa",
          "nif": "12345678A",
          "alternative_id": {
            "type": "NIF_IVA",
            "number": "string",
            "country_code": "st"
          },
          "address": {
            "street": "Calle Mayor, 123",
            "number": "123",
            "floor": "2º A",
            "door": "A",
            "postal_code": "28001",
            "city": "Madrid",
            "province": "Madrid",
            "country": "España",
            "country_code": "ES"
          },
          "phone": "+34 612 345 678",
          "email": "user@example.com"
        },
        "lines": [
          {
            "description": "Web application development",
            "quantity": 40,
            "unit": "hours",
            "unit_price": 50,
            "discount_percentage": 10,
            "main_tax": {
              "type": "IVA",
              "percentage": 21,
              "regime_key": "01"
            },
            "equivalence_surcharge_rate": 5.2,
            "irpf_rate": 15,
            "exemption_reason": "EXENTA_ART_20",
            "exemption_reason_text": "string",
            "taxable_base": 1800,
            "line_total": 2178,
            "pricing_mode": "UNIT_PRICE",
            "total_excluding_tax": 1,
            "total_including_tax": 100,
            "line_type": "NORMAL",
            "source_invoice_reference": "string",
            "source_invoice_ids": [
              "497f6eca-6276-4993-bfeb-53cbbbba6f08"
            ]
          }
        ],
        "totals": {
          "taxable_base": 2000,
          "total_discounts": 0,
          "vat_breakdown": [
            {
              "type": 21,
              "base": 2000,
              "amount": 420
            }
          ],
          "total_vat": 420,
          "surcharge_breakdown": [
            {
              "type": 0,
              "base": 0,
              "amount": 0
            }
          ],
          "total_equivalence_surcharge": 0,
          "irpf_breakdown": [
            {
              "type": 0,
              "base": 0,
              "amount": 0
            }
          ],
          "total_irpf": 300,
          "invoice_total": 2120,
          "total_disbursements": 0,
          "total_to_pay": 2120
        },
        "payment_info": {
          "method": "BANK_TRANSFER",
          "iban": "ES1234567890123456789012",
          "swift": "ABCDESMMXXX",
          "payment_term_days": 30
        },
        "notes": "string",
        "void_cause": "VOID_REQUEST",
        "void_reason": "string",
        "voided_at": "2025-01-20T09:12:44Z",
        "rectified_invoice_id": "986b41f8-8e28-4058-9e03-5286d0c42999",
        "source_proforma_id": "5f6c4143-c67e-4332-9fbc-f68d1420128f",
        "converted_invoice_id": "c85716fe-5512-4945-9dc8-daa0106a270b",
        "rectification_reason": "string",
        "recurring_invoice_id": "e6018980-fb8b-475b-a83d-b7bb0aa7423a",
        "recurring_invoice_name": "string",
        "rectification_type": "TOTAL",
        "rectification_code": "R1",
        "external_ref": "ORD-2025-0042",
        "metadata": {
          "external_customer_id": "cus_ULGk8bzIr88aag",
          "external_payment_id": "pi_3NqFGb2eZvKYlo2C0z1234AB",
          "payment_intent_id": "pi_3NqFGb2eZvKYlo2C0z1234AB",
          "charge_id": "ch_3NqFGb2eZvKYlo2C1234CDEF",
          "payment_provider": "STRIPE_CONNECT",
          "external_order_id": "ORD-2025-0042"
        },
        "send_automatically": true,
        "email_config": {
          "recipients": [
            "client@example.com"
          ],
          "cc": [
            "accounting@example.com"
          ],
          "subject": "Invoice 2025/0001 - Development services",
          "message": "Please find attached the requested invoice. We remain at your disposal for any clarification."
        },
        "pdf_download_url": "/v1/companies/7c9e6679-7425-40de-944b-e07fc1f90ae7/invoices/550e8400-e29b-41d4-a716-446655440000/pdf",
        "verifactu": {
          "enabled": false,
          "invoice_hash": "3A5B7C9D1E2F3A4B5C6D7E8F9A0B1C2D3E4F5A6B7C8D9E0F1A2B3C4D5E6F7A8B",
          "chaining_hash": "7F8E9D0C1B2A3F4E5D6C7B8A9F0E1D2C3B4A5F6E7D8C9B0A1F2E3D4C5B6A7F8",
          "registration_number": "VERIFACTU2025000001",
          "qr_url": "https://verifactu.agenciatributaria.gob.es/v?id=ABC123XYZ",
          "qr_base64": "iVBORw0KGgoAAAANSUhEUgAAAMgAAADI...",
          "registered_at": "2019-08-24T14:15:22Z",
          "submission_status": "ACCEPTED",
          "skip_reason": "CONFIG_DISABLED",
          "error_code": "3000",
          "error_message": "Factura ya existe en el sistema"
        },
        "attachments": [
          {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "name": "string",
            "url": "string",
            "type": "string"
          }
        ],
        "sending_history": [
          {
            "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
            "recipients": [
              "string"
            ],
            "cc": [
              "string"
            ],
            "subject": "string",
            "status": "SENT",
            "sent_at": "2025-01-29T18:45:00Z",
            "external_message_id": "string",
            "error": "string"
          }
        ],
        "created_at": "2019-08-24T14:15:22Z",
        "updated_at": "2019-08-24T14:15:22Z",
        "deleted_at": "2019-08-24T14:15:22Z"
      }
    ],
    "pagination": {
      "current_page": 1,
      "total_pages": 5,
      "total_items": 87,
      "items_per_page": 20,
      "has_next": true,
      "has_previous": true
    }
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Authentication required"
  },
  "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": "La factura debe tener al menos una línea",
  "instance": "/v1/invoices/abc-123"
}
{
  "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"
  }
}

Get an invoice of a company GET

Retrieves the full details of an invoice of this company (NIF).

Get the PDF download URL of an invoice GET

Returns a temporary pre-signed URL to download the invoice PDF. The URL expires in five minutes and only allows `GET`.