Invoices

List invoices

Returns a paginated list of invoices with optional filters

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"
type?string

Filter by invoice type

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

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.