NewThree filters returned the wrong rows
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Invoices

Export invoices to a spreadsheet

Scopeinvoices:read

Exports invoices to an XLSX file.

  • Deprecated: use POST /v1/companies/{company_id}/invoices/exports, which produces the same file.
  • Difference: the selection criteria are grouped there under filters instead of being top-level fields.
  • Selection: the invoices named in invoice_ids, or, when that list is absent, the ones matching the filters.
  • Format: SUMMARY gives one row per invoice with aggregated totals, ITEMS one row per invoice line.
POST
/v1/invoices/export/excel

Authorization

AuthorizationBearer <token>

Keys are prefixed beel_sk_, and each one carries the scopes it was created with: a key short of the scope an operation needs is answered 403. The scope an operation requires is shown next to its title, and the full catalogue lives in the Scopes reference.

Keys are created from the BeeL dashboard. They are secret credentials: do not share them or commit them to source control.

In: header

Request Body

invoice_ids?array<UUID>

List of specific invoice IDs to export. If provided, filters are ignored.

format?string

Export format.

  • SUMMARY: One row per invoice with totals (default)
  • ITEMS: One row per invoice line item
Default"SUMMARY"
Value in"SUMMARY" | "ITEMS"
status?string
  • SCHEDULED: Scheduled invoice to be issued automatically on a future date
  • DRAFT: Draft invoice not sent yet (modifiable)
  • ISSUED: Finalized invoice with definitive number but not sent
  • SENT: Invoice sent to customer
  • PAID: Invoice paid
  • OVERDUE: Overdue invoice (not paid after due date)
  • RECTIFIED: Partially corrected invoice (one or more PARTIAL corrective invoices)
  • VOIDED: Cancelled invoice. Reached either through a direct void request or through a TOTAL corrective invoice; void_cause tells the two apart.
  • CONVERTED: Proforma converted into an invoice (terminal; the proforma survives as the record of the accepted quote, linked to the created invoice)
  • ACTIVE: Active proforma. The single working state of a proforma (non-fiscal document): born numbered (PRO-...) and editable, never reaching the fiscal statuses. It transitions to CONVERTED when turned into an invoice, or to VOIDED when the offer is rejected/withdrawn (POST /v1/invoices/{invoice_id}/void).
  • EXPIRED: Proforma whose offer validity (valid_until) has passed. Derived on read and never stored; the proforma stays convertible and editable.
Value in"SCHEDULED" | "DRAFT" | "ISSUED" | "SENT" | "PAID" | "OVERDUE" | "RECTIFIED" | "VOIDED" | "CONVERTED" | "ACTIVE" | "EXPIRED"
type?string
  • STANDARD: Standard invoice
  • CORRECTIVE: Corrects or cancels a previous invoice
  • SIMPLIFIED: Simplified invoice without all recipient requirements (up to 3,000€ VAT included)
  • PROFORMA: Commercial document (formal quote) with no fiscal validity. Never enters VeriFactu (no QR, no AEAT submission) and verifactu_enabled is always forced to false. Requires full recipient data, like STANDARD. Cannot be corrective nor reference a rectified invoice.
Value in"STANDARD" | "CORRECTIVE" | "SIMPLIFIED" | "PROFORMA"
date_from?string

Issue date from (YYYY-MM-DD)

Formatdate
date_to?string

Issue date to (YYYY-MM-DD)

Formatdate
customer_id?string

Universally Unique Identifier (UUID v4)

Formatuuid
recipient_name?string

Filter by recipient name (partial match)

recipient_nif?string

Filter by recipient NIF (partial match)

series_code?string

Filter by series code

Response Body

application/vnd.openxmlformats-officedocument.spreadsheetml.sheet

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://app.beel.es/api/v1/invoices/export/excel" \  -H "Content-Type: application/json" \  -d '{    "invoice_ids": [      "550e8400-e29b-41d4-a716-446655440001",      "550e8400-e29b-41d4-a716-446655440002",      "550e8400-e29b-41d4-a716-446655440003"    ]  }'
"string"
{
  "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": "UNAUTHORIZED",
    "message": "Authentication is required to access this resource"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to access this resource"
  },
  "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"
  }
}
{
  "success": false,
  "error": {
    "code": "UNSUPPORTED_MEDIA_TYPE",
    "message": "Unsupported media type: text/plain. Supported: application/json"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}

Download multiple invoice PDFs as ZIP POST

Returns a single ZIP with the PDFs of the requested invoices. - **Deprecated:** use `POST /v1/companies/{company_id}/invoices/pdf-archive`, which behaves identically. - **Limits:** up to 500 invoices per call, and the ZIP is capped at 50MB. - **Missing PDFs:** invoices whose PDF is not available are left out; if none is available the call fails.

Send an invoice by email POST

Sends the invoice by email with its PDF attached. - **Deprecated:** use `POST /v1/companies/{company_id}/invoices/{invoice_id}/send`, which behaves identically. - **Recipients:** the addresses configured for the customer are used unless the body overrides them with `recipients`.