Download the PDFs of several invoices as a ZIP
Scopeinvoices:readReturns a single ZIP with the PDFs of the invoices of this company named in
invoice_ids.
- Limit: up to 500 invoices per request.
- Missing PDFs: invoices whose PDF is not available are left out of the archive. If
no PDF at all is available the call fails with
400. - Counts:
X-Bulk-Total,X-Bulk-SuccessfulandX-Bulk-Failedresponse headers report how many PDFs were requested and how many made it into the ZIP.
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
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.
uuidInvoices whose PDFs go into the archive.
1 <= items <= 500Response Body
application/zip
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/pdf-archive" \ -H "Content-Type: application/json" \ -d '{ "invoice_ids": [ "550e8400-e29b-41d4-a716-446655440001", "550e8400-e29b-41d4-a716-446655440002", "550e8400-e29b-41d4-a716-446655440003", "550e8400-e29b-41d4-a716-446655440004", "550e8400-e29b-41d4-a716-446655440005" ] }'"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": "VALIDATION_ERROR",
"message": "The provided data is not valid.",
"details": {
"legal_name": "The field 'legal_name' cannot be empty",
"recipient.address.postal_code": "Contains invalid characters."
}
},
"meta": {
"timestamp": "2025-01-15T10: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"
}
}Get the preview image URL of an invoice GET
Returns a temporary pre-signed URL to a preview image (WebP) of the invoice, suitable for inline rendering. The image is generated and cached on first request, so a later call returns the cached image. The URL expires in five minutes and only allows `GET`. The image of an issued invoice is taken from its stored PDF, the one delivered. While that PDF does not exist yet — right after issuing (whether or not the invoice goes through VeriFactu, since the PDF is generated asynchronously) or, for a VeriFactu invoice specifically, while it waits for the QR of its registration — the answer is `202`, as for the PDF download. When BeeL. cannot produce that PDF, the answer is `409 INVOICE_PDF_UNAVAILABLE`, also as for the PDF download.
Export invoices POST
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.