BeeL
Get StartedVeriFactuStripeAPI Reference
Invoices

List invoices

Returns a paginated list of invoices with optional filters

Try this endpoint with Claude
Copy the prompt for any assistant, or open it directly in Claude Code (needs it installed).
GET
/v1/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

Query Parameters

page?integer

Page number (starts at 1)

Default1
Range1 <= value
limit?integer

Number of 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?string

Filter by invoice status

Value in"SCHEDULED" | "DRAFT" | "ISSUED" | "SENT" | "PAID" | "OVERDUE" | "RECTIFIED" | "VOIDED" | "CONVERTED"
type?string

Filter by invoice type

Value in"STANDARD" | "CORRECTIVE" | "SIMPLIFIED" | "PROFORMA"
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

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 VeriFactu status. Special values:

  • "NO_VERIFACTU": Invoices where VeriFactu is not enabled
  • "PENDING": Invoices with VeriFactu enabled pending submission
  • "ACCEPTED": Invoices submitted and accepted by AEAT
  • "REJECTED": Invoices submitted and rejected by AEAT
Value in"NO_VERIFACTU" | "PENDING" | "ACCEPTED" | "REJECTED"
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

Sort direction

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

Header Parameters

X-Active-Profile?string

UUID of the business profile (sub-account / company) to operate as for this request.

Use with a master account API key to act on behalf of any owned sub-account without provisioning a separate key per company. Without this header the request operates as the API key owner.

Requirements:

  • The API key must belong to a master account (sub-account keys ignore this header).
  • The API key must have the business_profiles:read scope.
  • The target profile must be a sub-account owned by the key owner.

Returns 403 Forbidden if the profile is not owned by the key owner.

Formatuuid

Response Body

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": "B12345678",
          "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/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": "B12345678",
          "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/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": "B12345678",
          "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/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": "UNAUTHORIZED",
    "message": "Authentication required"
  },
  "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"
  }
}

Issue invoice (DRAFT → ISSUED) POST

Finalizes a draft invoice and marks it as issued. **Status change:** `DRAFT` → `ISSUED` **Actions performed:** - Assigns definitive invoice number according to configured series - Marks invoice as finalized (not modifiable) - Prepares invoice for sending to customer **Validations:** - Invoice must be in DRAFT status - All invoice data must be complete and valid **Note:** After issuing, the invoice can be sent to the customer via the `/invoices/{id}/send` endpoint

Mark invoice as paid POST

Marks an invoice as paid. **Status change:** `SENT` → `PAID` **Note:** Send `Content-Type: application/json` even when body is empty.