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

Get the PDF download URL of an invoice

Scopeinvoices:read

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

  • URL: 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.
  • 202: only when the wait elapsed with the PDF still in flight. No body is returned; ask again after Retry-After.
  • Drafts: a draft has no fiscal PDF and answers 400 INVOICE_NOT_ISSUED_NO_PDF immediately — that one never waits. Issue it, or render it with GET …/{invoice_id}/pdf/preview.
  • Not registered with the AEAT: under VeriFactu the PDF carries the QR code of the invoice's registration. An invoice whose registration was rejected before reaching the AEAT, or that was voided without ever being registered, has no PDF and answers 400 INVOICE_NOT_REGISTERED_NO_PDF immediately. Its verifactu.error_message says why.
  • Never modified: the PDF of an issued invoice is generated once — with its VeriFactu QR when it applies — and stays the document you delivered. Voiding the invoice or issuing a corrective against it does not change the PDF: read the invoice's status to know it.
GET
/v1/companies/{company_id}/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

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
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/companies/497f6eca-6276-4993-bfeb-53cbbbba6f08/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": "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": "INVOICE_NOT_FOUND",
    "message": "Invoice 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 the invoices of this company, filterable by status, type, series, customer, date range and free text. Only the documents of the company in the path are returned.

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.