Download invoice as PDF

Generate and download an invoice as a PDF file. This is a multi-step operation:

1. Validate the prefixed invoice ID (inv_*)
2. Fetch invoice with contact details (name, email, phone, VAT number, full address) filtered by organisation_id
3. Fetch invoice line items ordered by sort_order
4. Fetch organisation details (name, email, phone, website, VAT number, company number, full address)
5. Assemble data structures for the PDF service — all monetary values are passed as strings for precise rendering
6. Generate PDF via generateInvoicePDF() service
7. Write INVOICE_PDF_DOWNLOADED audit log entry
8. Return binary PDF with appropriate headers

Authentication

Requires a valid JWT. The authenticated user must belong to the organisation that owns the invoice. Multi-tenancy is enforced via organisation_id filtering on the query.

Response Format

Unlike other SpeyBooks endpoints, this returns a binary PDF rather than a JSON envelope:

• Content-Type: application/pdf
• Content-Disposition: attachment; filename="ST-2026-0001.pdf"
• Content-Length header set to buffer size

The filename is derived from the invoice number with non-alphanumeric characters (except hyphens) replaced by underscores.

PDF Content

The rendered PDF includes:

• Organisation header (name, address, VAT/company number)
• Contact details (name, address, VAT number)
• Invoice metadata (number, issue date, due date, status)
• Line item table (description, quantity, unit price, VAT rate, VAT amount, line total)
• Financial summary (subtotal, VAT amount, total, amount paid)
• Notes and terms sections (if populated)

Side Effects

• Audit log — INVOICE_PDF_DOWNLOADED entry with invoiceNumber in details, includes IP address and user agent
• No state mutation — downloading a PDF does not change invoice status

Caching

PDFs are generated on every request — there is no server-side caching. Each download triggers a fresh render from current database state, ensuring the PDF always reflects the latest invoice data.