NewThe street number is no longer required in an address
BeeL
Get StartedMulti-NIFVeriFactuStripeAPI ReferenceChangelog
Invoices

Get invoice PDF download URL

Scopeinvoices:read

Returns a temporary pre-signed URL to download the invoice PDF.

  • Deprecated: use GET /v1/companies/{company_id}/invoices/{invoice_id}/pdf, which behaves identically.
  • URL: it expires in five minutes and only allows GET.
  • Waiting: a PDF is produced asynchronously, so this request waits for it (up to ten seconds) instead of handing you a polling loop to write. Bound the wait with Prefer: wait=N, or opt out with Prefer: wait=0.

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

GET
/v1/invoices/{invoice_id}/pdf

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

invoice_idstring

Invoice ID

Formatuuid

Header Parameters

Prefer?string

RFC 7240 preference bounding how long this request may wait for a PDF that is still being generated: Prefer: wait=N, with N in seconds.

By default the request waits (up to the server cap) and answers 200 with the URL, so the 202 is the exception rather than the normal path. Use Prefer: wait=0 to opt out and get the old poll-only behaviour: an immediate 202 while the PDF is in flight.

A value above the cap is lowered to it, and the 202 then echoes what was actually applied in Preference-Applied: wait=<seconds> — so you never have to discover the cap by trial and error. A value that is not a non-negative integer is ignored altogether (RFC 7240: a preference that is not understood is not an error), and the request falls back to the default wait with no Preference-Applied header.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X GET "https://app.beel.es/api/v1/invoices/550e8400-e29b-41d4-a716-446655440000/pdf"
{
  "success": true,
  "data": {
    "download_url": "https://storage.example.com/beel-invoices/invoices/user-uuid/factura-uuid.pdf?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=...",
    "expires_in_seconds": 300,
    "file_name": "factura_2025-001.pdf"
  },
  "meta": {
    "timestamp": "2025-01-15T10:30:00Z",
    "request_id": "4bf92f3577b34da6a3ce929d0e0e4736"
  }
}
Empty
{
  "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": "NOT_FOUND",
    "message": "Resource not found"
  },
  "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"
  }
}

List invoices GET

Returns a paginated list of invoices, with filters, sorting and pagination. - **Deprecated:** use `GET /v1/companies/{company_id}/invoices`, which returns the same list with the same filters. - **Difference:** the legacy alias `external_reference` is not carried over there. Use `external_ref`, which this route also accepts. **Retires on 10 September 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch.

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. **Retires on 10 September 2026.** See the [migration guide](https://docs.beel.es/changelog/resources-under-the-nif) for what moved where and what changes when you switch.