NewProvince is only required for addresses in Spain
BeeL
Get startedMulti-NIFVeriFactuRulesStripeAPI referenceChangelog
Invoices

Download the PDFs of several invoices as a ZIP

Scopeinvoices:read

Returns 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-Successful and X-Bulk-Failed response headers report how many PDFs were requested and how many made it into the ZIP.
POST
/v1/companies/{company_id}/invoices/pdf-archive

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

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

Request Body

invoice_idsarray<UUID>

Invoices whose PDFs go into the archive.

Items1 <= items <= 500

Response 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.

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. - **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`. - **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.