NewThe SII in Live, under contract
BeeL
Get startedMulti-NIFVeriFactuSIIRulesStripeAPI referenceChangelog
Invoices

Export invoices

Scopeinvoices:read

Produces a spreadsheet with the invoices of this company and returns the file in the response.

  • Selection: the invoices named in invoice_ids, or, when that is absent, the ones matching filters. A request with neither is rejected with 400 EXPORT_SELECTION_REQUIRED.
  • Format: SUMMARY writes one row per invoice with aggregated totals, ITEMS one row per invoice line. To get both, send formats: [SUMMARY, ITEMS]: a single file with one sheet per format, rather than two requests.
  • Disbursements sheet: when any exported invoice has SUPLIDO lines, the workbook gets one more sheet at the end, named Suplidos, with one row per source invoice. Columns: «Número factura», «Fecha expedición», «Cliente», «NIF cliente», «Factura origen», «NIF emisor origen» and «Importe factura origen». The amount is the total_to_pay of the source invoice; for a manual disbursement with no linked invoices it is the line total. When the source invoice is not visible to you, the row carries only its number, when known, and the issuer NIF and the amount are empty. The sheet is added whatever formats you send, and it is not a format: you cannot request it or opt out of it.
  • Values: the status, payment method, tax type and line type columns carry the same values the API returns (ISSUED, BANK_TRANSFER, IVA, SUPLIDO…). A proforma past its validity is exported as ACTIVE, not EXPIRED.
  • Custom fields: the SUMMARY and ITEMS sheets get one extra column per custom field key carried by at least one exported invoice, after the fixed columns and ordered by key, so the position of the fixed columns never changes. The header is the label saved on the invoices; when the same key was saved under different labels (the field was renamed between invoices), the label of the most recently created of them is used. A cell is empty when its invoice does not carry that field, and every line of an invoice repeats the invoice's values in ITEMS. The Suplidos sheet has no custom field columns. With no custom fields on any exported invoice the workbook is the same as without them.
  • Limit: up to 50000 invoices per export. Going over it is rejected with 422 EXPORT_LIMIT_EXCEEDED — narrow the date range or split the selection. The export is never silently truncated.

POST
/v1/companies/{company_id}/invoices/exports
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

Path Parameters

company_idstring

Unique identifier (UUID) of the company the operation acts on — its identifier, not its NIF. It is the only source of context: the account that owns it is derived from it, and the BeeL-Active-Company header plays no part. A company you do not reach answers 403, and so does a company that does not exist, so the existence of a company in another account is never disclosed.

Formatuuid
format?string
  • SUMMARY: one row per invoice with aggregated totals.
  • ITEMS: one row per invoice line.

Ignored when formats is present.

Default"SUMMARY"
Value in"SUMMARY" | "ITEMS"
formats?array<InvoiceExportFormat>

Several formats in ONE file: the workbook carries one sheet per format, in the order given (a repeated format yields a single sheet), followed at the end by a disbursements sheet (named Suplidos, described in the operation) whenever any exported invoice carries disbursement lines. Takes precedence over format; empty or absent, format applies.

invoice_ids?array<UUID>

Specific invoices to export. When present, filters is ignored.

filters?

Selection criteria used when invoice_ids is not supplied. Max 50000 invoices: a wider match is rejected with 422 EXPORT_LIMIT_EXCEEDED, never truncated.

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/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/invoices/exports" \  -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": "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": "CUSTOM_FIELD_FILTER_TOO_MANY_KEYS",
    "message": "The custom fields filter accepts at most 20 keys per request"
  },
  "meta": {
    "timestamp": "2026-10-18T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
{
  "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"
  }
}