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>

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.