Invoice Processing

This document explains the runtime document flow for sales invoices, purchase
invoices, and POS fiscal flows.

Document Events

The app hooks into:

• Sales Invoice.before_submit
• Purchase Invoice.before_submit
• Item.before_save
• Company.before_save

Company Before Save

The app prevents duplicate sale types in the company configuration.

Item Before Save

If an item has an HS Code but no HS UOM, the app auto-fetches the linked UOM.

Sales Invoice Flow

The sales invoice flow has two branches.

Standard DI Sales Invoice

This path is used when the invoice is not POS.

1. Check whether DI is enabled for the company
2. Check whether the customer has digital invoicing enabled
3. Validate per-item DI fields
4. Validate SRO requirements for sale types that need them
5. Build the FBR DI payload
6. Post automatically if Auto Post on Submit is enabled
7. Save the FBR invoice number, posting time, QR code, and DI log

If the DI API rejects the invoice, the app raises a validation error and stores
the failure details in DI Log.

POS Fiscal Sales Invoice

This path is used when the invoice is POS and the POS Profile has FBR
integration enabled.

1. Validate that each item has a customs tariff number
2. Load POS Profile FBR credentials and endpoint settings
3. Resolve payment mode into the FBR payment mode code
4. Build the POS fiscal payload
5. Submit the payload to the FBR POS endpoint
6. Save the fiscal invoice number and posting timestamp
7. Generate a QR code

Purchase Invoice Flow

For purchase invoices:

1. Check whether DI is enabled for the company
2. Validate item-level HS code presence
3. Build the DI payload
4. Post automatically if Auto Post on Submit is enabled
5. Save the response details in DI Log

Manual Actions Available in the UI

On submitted sales invoices, the app can expose:

• DI Preview
• Post to FBR
• Validate with FBR
• Verify Buyer

On submitted purchase invoices, the app can expose:

• DI Preview
• Post to FBR

QR Code Flow

When an invoice is posted successfully and an FBR invoice number is available,
the app generates a QR code and stores it as a base64 PNG data URI for UI and
print use.

Print Output

The app ships a Sales Tax Invoice print format that can render FBR-specific
invoice data and the generated QR code.