NewStripe: a buyer with a NIF always gets a standard invoice, and the simplified threshold is deprecated
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Invoices

Export invoices to a spreadsheet (deprecated)

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.

Retires on 9 December 2026. See the migration guide for what moved where and what changes when you switch.

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: Reserved. No operation sets this status and it is not computed from due_date; an unpaid invoice past its due date keeps its status (ISSUED or SENT). Compare due_date with today to find overdue invoices.
  • 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 (ticket), for a recipient that is not identified. BeeL. requires a STANDARD invoice when the recipient is identified, at any amount: a SIMPLIFIED invoice whose recipient carries an nif or alternative_id is rejected with SIMPLIFIED_INVOICE_FORBIDS_IDENTIFIED_RECIPIENT. The only amount BeeL enforces is a cap of 3,000€ VAT included (SIMPLIFIED_INVOICE_EXCEEDS_LEGAL_LIMIT). The general limit of RD 1619/2012 is 400€ (art. 4.1.a); up to 3,000€ applies only to the activities listed in art. 4.2. BeeL does not check which activity the issuer carries out.
  • PROFORMA: Commercial document (formal quote) with no fiscal validity. Never enters VeriFactu (no QR, no AEAT submission): verifactu.enabled is always false, whatever the company's regime. 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": "The invoice must have at least one line",
  "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": "The invoice must have at least one line",
  "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 (deprecated) 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. **Retires on 9 December 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch.

Send an invoice by email (deprecated) 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`. **Retires on 9 December 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch.