Skip to content

Print Configuration

Applies to: e-Invoice · e-Way Bill · Which modules do I have?

Purpose

Configure how Complifly renders compliant documents: which template, whose branding, and how the statutory elements appear. Also covers the rendering dependency whose absence produces a system that works perfectly until someone prints.

Audience

System administrators and implementation consultants, with the customer's tax lead for statutory content.

Prerequisites

  • Installation Guide complete, including the rendering dependencies
  • Branding assets collected — see Information Checklist
  • Statutory declarations supplied by the customer's tax lead
  • Administrator access

Steps

1. Understand what printing does and does not do

There are two print formats, and the difference between them is the single most important thing on this page.

Format Rendered by Available
NIC format The government, fetched through the provider Only for 2 days after generation
Branded Print Complifly, from the signed invoice and signed QR captured at generation Always

Branded Print is the one that always works. It renders from data captured at generation time and held locally, which is what makes an e-invoice print valid. It needs no provider call and is unaffected by a provider outage.

The NIC format has a hard two-day window. The government stops serving the official copy two days after generation. Complifly caches that copy at generation time precisely so it remains available afterwards — but if the copy was never cached and two days pass, it is permanently unobtainable. No retry, escalation or support action reopens the window.

Two further behaviours follow from this:

  • A cached NIC copy prints with no provider call — fast, free, and available during an outage.
  • The cache is deliberately bypassed when the e-Way Bill was updated after the copy was cached, so the reprint reflects current bill details. That forces a fresh provider call, and therefore can fail if the window has since closed.

Diagnose accordingly: a print failure is not always local. Branded Print failing is a rendering or configuration problem. NIC format failing may be the closed two-day window — which is a statutory-style constraint, not a fault, and whose answer is Branded Print.

2. Confirm the rendering dependencies

Rendering runs a headless browser on the application host. On minimal server images the system libraries it needs are frequently absent, and their absence produces a system where everything works until someone prints.

Verify with a real render, not by reading a package list.

3. Choose the template

Templates control layout and which fields appear where. Select per company, and per GSTIN where they differ.

Consideration Guidance
Statutory elements must be present and legible The signed QR code, IRN, acknowledgement number and date
Customer branding Logo, colours, footer
Language and formatting Number and date formats consistent with the customer's convention
Paper size and margins Confirm against the customer's actual stationery and printers

The print framework (optional, off by default). The CORPORATE_PRINT_FRAMEWORK control (Super Admin, per company or GSTIN, see Feature Flags) makes a registration's documents print through a versioned template engine. The printed page does not change when you switch it on. What changes is that every print is recorded with the template version it used and a fingerprint of the document, so you can later tell which layout a PDF came from and whether the invoice changed between two prints. If a template name in a registration's configuration no longer exists, the document still prints with the standard template; with the framework on, the fallback is recorded. This needs database access to read: there is no screen for the record yet.

4. Load branding

Asset Requirement
Logo Legible at print size. A high-resolution logo scaled down often is not. Test on paper
Footer text Supplied by the tax lead, not drafted by the implementer
Declarations Statutory wording, supplied by the customer

5. Get the signed QR code right

The signed QR code is the evidence of registration and the element most likely to be got wrong in a way nobody notices until an inspection.

Requirement Why
Present on every registered document Statutory
Large enough to scan reliably A QR that scans on screen may not scan when printed at a smaller size
Not overlapped or cropped Template changes are the usual cause
Sufficient quiet space around it Scanners need the margin
Verified by scanning a printed copy Not a screen preview. Print it and scan it with a phone

The last row is the check that matters. A QR code that renders on screen and fails on paper is a compliance failure discovered by an inspector.

6. Configure per GSTIN where needed

Different registrations may need different templates, logos or declarations — a group with distinct trading names, for instance. Configure per GSTIN rather than forcing one template on all.

Corporate fields (per GSTIN). For a registration whose invoices carry a Udyam number, named signatories or reference contacts, the print configuration for that GSTIN holds seven optional values. They are saved with the registration's other print settings (on the Corporate details card of Print Settings, or through POST /api/print-config/save) and are printed by the Corporate template only: the other templates do not print them.

Setting Rule
Udyam_No The registration number, in its registered form, for example UDYAM-UP-28-0039696. Anything else is refused
Prepared_By, Checked_By, Authorised_By The name or role printed under each signature caption. At most 60 characters
Reference_Partner, Reference_Manager Free text. At most 100 characters
Code_Value Free text, at most 40 characters, printed as "Code:". Its meaning is not defined yet and it is not tied to any document field; leave it blank to hide it

An empty value removes the setting. Saving a value that does not meet its rule is refused with 400 PRINT_CONFIG_INVALID, the message names each field and what it should look like, and nothing is saved. You need the template.update permission and the registration must be one you can administer.

The corporate invoice template (TEMPLATE_CORPORATE). A currency-driven layout for export and services invoices, modelled on a customer's export services invoice. One layout serves rupee, US dollar, euro and any other currency: the column headings, the figures and the amount in words all follow the invoice's own currency ("Unit Price (USD)", "US Dollars Two Thousand Only"). It prints the From and To blocks, reference partner and manager, period, project, PO, the IRN and acknowledgement, the bank account with SWIFT, the certification line and the Prepared, Checked and Authorised By captions. Tax lines appear only when the invoice has tax. It has no digital signature stamp. To use it: a Complifly Super Admin switches on CORPORATE_PRINT_FRAMEWORK for the registration; the template then appears in the Template Gallery of Print Settings with the Corporate details and Bank accounts cards. With the control off it is not offered, and a registration that names it anyway prints with the standard template. The database must carry the template's catalogue row first (migration 20261018a_print_template_corporate.sql): without it, saving the choice fails with a database error (HTTP 500, a foreign key on default_template_code). A foreign currency is honoured only on export and SEZ supply types (EXPWP, EXPWOP, SEZWP, SEZWOP); on any other supply type a stray currency code is ignored and the document prints in rupees.

Bank accounts for print. The corporate template prints the registration's bank account from the structured bank account master, not from free text in the notes. Accounts are maintained on the Bank accounts card of Print Settings (there is no separate bank administration screen), against the registration you are working under (the active GSTIN). Rules to know before you rely on it:

Rule Detail
Which account prints The default active account; for an export invoice an Export collection account is preferred, then the default, then the oldest
Default At most one per registration. The first account added becomes the default; making another the default clears the first; deactivating the default hands it to the oldest remaining active account
Deactivate, never delete A deactivated account keeps its record (IGM drafts may refer to it) and stops printing; its number can be added again
Duplicates A second active account with the same number is refused (409 BANK_ACCOUNT_EXISTS)
Validation Account number 5 to 30 letters, digits, hyphens or slashes; IFSC 11 characters (UBIN0551325); SWIFT 8 or 11 letters and digits (UBININBBNOS). A bad value is refused with 400 PRINT_BANK_INVALID and nothing is saved
Approval Accounts added here are not marked approved; the IGM masters' approval step is not bypassed
Show bank details Turning Show bank details off removes the account from the printed document's data entirely

The API is GET, POST, PUT /:id and DELETE /:id (which deactivates) on /api/print-config/bank-accounts, working on the registration in the X-GSTIN header (all is refused with GSTIN_REQUIRED); reading needs template.view, changing needs template.update.

7. Test a real print

Print a real document, on the customer's own printer and stationery, and check it as a physical artefact:

Check Why it fails on paper but not on screen
QR scans Scaling and print quality
Logo legible Downscaling
Nothing cropped Margins and paper size
Text readable Font size at actual scale
Fits the page count expected Multi-line documents overflow unexpectedly

Validation

Check Method Pass condition
Rendering works at all Render one document A PDF is produced
Signed QR present Inspect the output Present on every registered document
QR scans from paper Print it and scan with a phone Scans reliably. Do not accept a screen scan as evidence
Statutory fields present Compare against the customer's compliance checklist IRN, acknowledgement number and date all present
Branding correct Print and inspect Logo legible, footer correct
Per-GSTIN templates apply Print one document per registration Each carries its own branding
Multi-line documents render Print a document with many lines Paginates correctly; nothing cropped or lost
Bulk print works at real volume Print a realistic batch Completes without exhausting memory
Download works Download a rendered document Downloads successfully. Failure here is usually the content-security policy, not printing
Cached documents remain valid Reprint a document printed earlier Identical output

Troubleshooting

Symptom Cause Action
Printing fails, everything else works Rendering system libraries absent on the host Install them. This is an operating-system dependency, not a setting
Bulk print fails while single prints succeed Memory exhausted by concurrent rendering Reduce batch size, or raise memory. See Sizing and Capacity
QR scans on screen, not on paper Rendered too small, cropped, or without quiet space Adjust the template and re-test on paper
QR absent Document not registered, or the template omits it Check the document's status first. An unregistered document has no QR to print
Logo illegible High-resolution image downscaled, or wrong aspect ratio Supply an asset sized for print
Choosing the Corporate template and pressing Finalize & Sync fails with a database error (500) The template's catalogue row is missing: migration 20261018a_print_template_corporate.sql has not been applied to this database A database administrator applies the migration. Nothing is saved until then
Saving print settings is refused with PRINT_CONFIG_INVALID A corporate field does not meet its rule (most often the Udyam number written with a different spelling or without its hyphens) Correct the field named in the message and save again
Wrong branding on some documents Configuration set per company where it should be per GSTIN Configure per registration
Content cropped at the margins Paper size or margins mismatched to the customer's stationery Correct the template and print again
Download link fails Download origin blocked by proxy or content-security policy Downloads use a separate origin by design. See Domains and URLs
Print looks different after an upgrade Template changed in the release Check the release notes and re-verify the QR on paper
A document cannot be printed at all Outside the retrievable print horizon Check the configured horizon. See Environment Variables