Skip to content

Latest commit

 

History

History
134 lines (100 loc) · 5.48 KB

PDFGENERATION.md

File metadata and controls

134 lines (100 loc) · 5.48 KB

PDF Generation

The backend generates downloadable PDFs using WeasyPrint. HTML template construction is centralized in the pdf_templates service package.

Architecture

  • PDF engine: weasyprint.HTML(string=html).write_pdf()
  • HTML template builders live in:
    • backend/src/services/pdf_templates/invoice_template.py
    • backend/src/services/pdf_templates/purchase_template.py
    • backend/src/services/pdf_templates/ledger_template.py
    • shared helpers: backend/src/services/pdf_templates/builders.py
  • Route handlers call these template builders, then stream the generated bytes as application/pdf.

Current PDF Endpoints

  • GET /api/invoices/{invoice_id}/pdf

    • route: backend/src/api/routes/invoices.py
    • template builder: _build_invoice_html / _build_multi_copy_invoice_html
  • GET /api/ledgers/day-book/pdf

    • route: backend/src/api/routes/ledgers.py
    • template builder: _build_day_book_html
  • GET /api/ledgers/{ledger_id}/statement/pdf

    • route: backend/src/api/routes/ledgers.py
    • template builder: _build_statement_html
  • GET /api/payments/{payment_id}/pdf

    • route: backend/src/api/routes/payments.py
    • currently uses route-local _build_receipt_html

Request-to-PDF Flow

  1. API route validates request and loads domain objects from DB.
  2. Route calls a template builder to produce a full HTML document.
  3. WeasyPrint renders HTML/CSS to bytes on A4 pages.
  4. Route returns StreamingResponse with attachment filename.

Why pdf_templates Exists

  • Keeps route files focused on request/response and validation.
  • Keeps HTML/CSS template code reusable and testable.
  • Reduces duplication between sales, purchase, and ledger PDF rendering logic.

Dependencies

Python package in backend/requirements.txt:

weasyprint==63.1

System libraries are required for text layout and font rendering.

macOS:

brew install pango

Debian/Ubuntu (already handled by backend Dockerfile):

apt-get install -y --no-install-recommends \
    libpango-1.0-0 \
    libpangocairo-1.0-0 \
    libpangoft2-1.0-0 \
    libgdk-pixbuf2.0-0 \
    libffi-dev

Alpine:

apk add --no-cache pango fontconfig ttf-freefont

Troubleshooting

  • OSError: cannot load library 'libgobject-2.0-0':
    • Install system dependencies (brew install pango on macOS).
  • Missing currency symbols or glyph fallback:
    • Install Unicode-capable fonts on host/container.
  • Blank PDF output:
    • Validate generated HTML and inline CSS; run backend with debug logging.

Pay-online QR

When a company turns on Show pay-online QR on invoice PDFs (Company settings), invoice and statement PDFs carry a QR in their payment details block. The QR encodes that document's own public share URL, not a upi:// payment intent.

That distinction is the whole design:

  • A printed UPI QR is a snapshot. It carries whatever was outstanding on the day it was printed, never expires (there is no expiry parameter in the UPI spec), and stays payable a month after the invoice was settled.
  • A printed URL is live. The share page reprices itself from the outstanding balance on every open, and a settled invoice simply shows no pay button.
  • NPCI also caps a forwarded QR image at Rs 2,000, and invoices get forwarded constantly. A URL QR is unaffected, because the recipient ends up scanning the UPI QR off the page.

The pay-by-UPI offer itself lives on the share page, built by backend/src/services/upi.py. By default it is scan-only: the page shows a UPI QR and the payee address as text, and no tappable upi:// button. A hand-off button does work on Android, but for an ordinary personal UPI ID Paytm meets it with "this payment may fail as per UPI Risk Policy" and steers the payer to scan a QR instead -- the cost of an unsigned intent, which cannot be fixed without an RSA key registered through an acquiring bank.

A company whose UPI ID is registered as a merchant with its UPI provider can turn on Show "Pay by UPI" button on shared invoices (company_profiles.show_upi_pay_button, off by default). The share page then adds a Pay by UPI button -- a plain upi://pay link -- and Google Pay, PhonePe and Paytm shortcuts carrying the same payment under each app's own scheme. The QR stays underneath, because scanning works for everyone.

How it is wired

  • The QR image is rendered at the DB-aware call site and passed down as a pre-rendered HTML string (pay_qr_html). pdf_templates has no database or request access and must keep it.
  • Passing a string is also the memoisation. _build_multi_copy_invoice_html re-renders the body once per copy, so a QR built inside it would be encoded three times for a triplicate print.
  • share_documents.document_share_url() is the single gate. It returns None -- print nothing -- when share links are disabled, the company has not opted in, or the document is cancelled; otherwise it mints the document's share link (idempotently) and returns its URL with ?src=qr appended so a scan is distinguishable from a forwarded link in analytics.
  • segno renders the PNG as a data: URI, matching the existing company-logo embed pattern. Error correction M, printed at 124px (~33mm on A4) -- above the ~25-30mm floor a printed QR needs.

Conventions For New PDFs

  • Put new HTML builders in backend/src/services/pdf_templates/.
  • Re-export new builders from backend/src/services/pdf_templates/__init__.py when they are shared.
  • Keep routes responsible only for orchestration, not template HTML/CSS.