Facturas

List invoices

Returns a paginated list of invoices with optional filters

GET
/facturas

Authorization

X-API-Key<token>

API Key authentication.

Format: X-API-Key: beel_sk_<key>

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

Query Parameters

page?integer

Page number (starts at 1)

Default1
Range1 <= value
limit?integer

Number of items per page

Default20
Range1 <= value <= 100
estado?string

Filter by invoice status

Value in"BORRADOR" | "EMITIDA" | "ENVIADA" | "PAGADA" | "VENCIDA" | "RECTIFICADA" | "ANULADA"
tipo?string

Filter by invoice type

Value in"ORDINARIA" | "RECTIFICATIVA" | "SIMPLIFICADA"
cliente_id?string

Filter by client UUID

Formatuuid
fecha_desde?string

Issue date from (YYYY-MM-DD)

Formatdate
fecha_hasta?string

Issue date to (YYYY-MM-DD)

Formatdate
numero_factura?string

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

receptor_nombre?string

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

receptor_nif?string

Filter by recipient's NIF (partial search)

serie_codigo?string

Filter by series code

base_imponible_min?number

Minimum taxable base

Formatdouble
base_imponible_max?number

Maximum taxable base

Formatdouble
total_min?number

Minimum invoice total

Formatdouble
total_max?number

Maximum invoice total

Formatdouble
verifactu_estado?string

Filter by VeriFactu status. Special values:

  • "null": Invoices where VeriFactu is not enabled
  • "pendiente": Invoices with VeriFactu enabled pending submission
  • "aceptado": Invoices submitted and accepted by AEAT
  • "rechazado": Invoices submitted and rejected by AEAT
Value innull | "pendiente" | "aceptado" | "rechazado"
sort_by?string

Field to sort by (e.g., fecha_emision, numero_factura, total_factura)

sort_order?string

Sort direction

Default"desc"
Value in"asc" | "desc"

Response Body

application/json

application/json

application/json

curl -X GET "https://app.beel.es/api/v1/facturas"

Invoice list with pagination metadata and totals summary (base, total, pending)

{
  "success": true,
  "data": {
    "facturas": [
      {
        "id": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
        "numero_factura": "A/2025/0042",
        "serie": {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "codigo": "A"
        },
        "numero": 42,
        "tipo": "ORDINARIA",
        "estado": "EMITIDA",
        "fecha_emision": "2025-01-20",
        "fecha_vencimiento": "2025-02-20",
        "receptor": {
          "nombre_fiscal": "Cliente Ejemplo SL",
          "nif": "B87654321"
        },
        "totales": {
          "base_imponible": 1500,
          "total_factura": 1815
        },
        "pdf_url": "https://storage.beel.es/facturas/f47ac10b-58cc-4372-a567-0e02b2c3d479.pdf"
      },
      {
        "id": "a12bc34d-56ef-78gh-9012-34ij56kl78mn",
        "numero_factura": "A/2025/0041",
        "serie": {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "codigo": "A"
        },
        "numero": 41,
        "tipo": "ORDINARIA",
        "estado": "PAGADA",
        "fecha_emision": "2025-01-15",
        "fecha_vencimiento": "2025-02-15",
        "fecha_pago": "2025-01-18",
        "receptor": {
          "nombre_fiscal": "Otro Cliente SA",
          "nif": "A12345678"
        },
        "totales": {
          "base_imponible": 2500,
          "total_factura": 3025
        },
        "pdf_url": "https://storage.beel.es/facturas/a12bc34d-56ef-78gh-9012-34ij56kl78mn.pdf"
      },
      {
        "id": "b23cd45e-67fg-89hi-0123-45jk67lm89no",
        "numero_factura": "A/2025/0040",
        "serie": {
          "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
          "codigo": "A"
        },
        "numero": 40,
        "tipo": "ORDINARIA",
        "estado": "VENCIDA",
        "fecha_emision": "2024-12-10",
        "fecha_vencimiento": "2025-01-10",
        "receptor": {
          "nombre_fiscal": "Cliente Moroso SL",
          "nif": "B98765432"
        },
        "totales": {
          "base_imponible": 800,
          "total_factura": 968
        },
        "pdf_url": "https://storage.beel.es/facturas/b23cd45e-67fg-89hi-0123-45jk67lm89no.pdf"
      }
    ],
    "paginacion": {
      "pagina_actual": 1,
      "items_por_pagina": 20,
      "total_items": 3,
      "total_paginas": 1,
      "tiene_siguiente": false,
      "tiene_anterior": false
    },
    "resumen": {
      "total_base_imponible": 4800,
      "total_facturado": 5808,
      "total_pendiente_cobro": 968,
      "total_cobrado": 4840
    }
  },
  "meta": {
    "timestamp": "2025-01-20T12:00:00Z",
    "request_id": "req_list_facturas_001"
  }
}

Missing, invalid, or expired API key in X-API-Key header

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "API key is invalid or has expired",
    "details": {
      "header": "X-API-Key",
      "reason": "Invalid API key format or key not found"
    }
  },
  "meta": {
    "timestamp": "2025-01-20T10:00:00Z",
    "request_id": "req_error_001"
  }
}
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "123e4567-e89b-12d3-a456-426614174000"
  }
}

Get invoice PDF download URL GET

Generates a temporary pre-signed URL to download the invoice PDF. **Security:** - URL expires automatically in 5 minutes - HMAC signature prevents tampering - Only allows download (GET), no modification **Benefits:** - Direct download from storage (bypasses backend) - Better performance and lower server load - Compatible with browser cache and CDN - Ideal for large files **Frontend usage:** ```javascript const response = await fetch('/api/v1/facturas/{id}/pdf'); const { download_url } = await response.json(); window.open(download_url, '_blank'); // Direct download ``` **Format:** PDF is generated according to Spanish tax regulations.

Mark invoice as paid POST

Marks an invoice as paid. **Status change:** `enviada` → `pagada`