Complete Operator & Developer Platform Handbook
This interactive visual guide covers every screen, fiscal calculation, PRAL scenario clearance rule, bulk import pipeline, and developer SDK across the InvoiceHub PK platform.
Hierarchical Multi-Tenancy & Company Workspace Switching
The platform supports a 4-tier hierarchical enterprise structure designed for conglomerates, accounting firms, and multi-branch retailers.
Returns the operator instantly to their home organisation level without logging out.
Select any client company, subsidiary, or physical POS outlet. All invoices, buyers, items, and quotas instantly scope to this entity.
Role-Based Access Control: Company Admin vs. Client / Branch
The platform enforces granular role segregation across multi-entity hierarchies, distinguishing between master corporate governance and localized point-of-sale execution.
Company Admin (Master Company)
Corporate Governance & Multi-Entity MasterAssigned to headquarters management and parent holding entities. Company Admins possess overarching authority across the parent company and all affiliated child branches.
- ✓ Sub-Client & Branch Creation: Spawn child branches, POS stations, and subsidiaries up to the allotted subclient limit.
- ✓ Quota Management: Administer shared enterprise invoice pools or allocate dedicated quotas per branch.
- ✓ Master Company Conversion: Convert standalone company profiles into Master Companies directly.
- ✓ Cross-Entity Operations: Seamlessly switch context between outlets to view unified sales, buyers, items, and audit trails.
Client / Branch User
Point-of-Sale Cashier & Local OperatorAssigned to physical branch operators, cashiers, or single-store merchants. Scoped strictly to their designated store or POS station.
- ✓ Sales Invoicing: Create, validate, and certify digital sales tax invoices with live FBR QR codes.
- ✓ Local Directory: Search registered buyers, ATL status verification, and product catalog lookups.
- ✕ Restricted Hierarchy: Cannot create unauthorized sub-clients or reassign corporate parent relationships.
- ✕ Isolated Data Scope: Prevented from accessing peer branch financial transactions or unassigned company workspaces.
Company Registration & Sub-Entities / Branching Controls
When registering a client company (/clients/create), administrators configure the organizational architecture, sub-entity authorization, and quota limits.
Controls whether this business entity can create child branches, physical store outlets, POS terminals, and sub-clients.
Structure & Hierarchy Management Actions
From the Company Profile screen (/clients/{client}), administrators can restructure company hierarchies, convert accounts, add branches, and reassign parent entities with automated onward commission routing.
Upgrades standalone clients to Master Companies with branch creation capabilities.
Creates branch outlets or POS stations under the master company with inherited credentials.
Reassigns branches across parents with automated Section 233 commission transfers.
FBR Sandbox Scenario Testing & 1-Click Production Clearance Suite
FBR PRAL regulations mandate that before any enterprise is unlocked to submit live invoices to production (gw.fbr.gov.pk), the merchant must execute and clear all applicable business sector scenarios in the PRAL Sandbox environment (/sandbox/scenarios).
Apex Steel Mills Ltd — NTN: 8885801
Business Activities: Manufacturer, Wholesaler • Sector: Steel & Rerolling
Full PRAL Scenarios Catalog (SN001–SN028)
InvoiceHub PK includes built-in compliant presets and validators for all official PRAL digital invoicing scenarios:
| Scenario ID | Scenario Title & Specification | Document Type | Tax Rates |
|---|---|---|---|
| SN001 |
Standard Sales to Registered Buyer
Regular domestic sale of taxable goods to an ATL registered entity.
|
Sale Invoice | 18% ST |
| SN002 |
Sales to Unregistered Person / Consumer
Retail supply with mandatory 4% Further Tax applied on top of 18% ST.
|
Sale Invoice | 18% ST + 4% FT |
| SN003 |
Debit Note Adjustment
Upward value/tax escalation referencing original PRAL invoice IRN.
|
Debit Note | Variable |
| SN004 |
Credit Note Adjustment
Sales return or price concession referencing original PRAL invoice IRN.
|
Credit Note | Reversal |
| SN006 |
Steel Melters & Re-rollers Production Supply
Special steel invoicing with electricity unit deduction matrix.
|
Steel Invoicing | Special Steel ST |
| SN007 |
Third Schedule Goods (Printed Retail Price)
Sales tax calculated on printed Maximum Retail Price (MRP).
|
Sale Invoice | 18% on MRP |
Invoice Creator & FBR Certification Gateway
The Invoice Creator (/invoices/create) allows operators to prepare digital sales tax invoices compliant with SRO 350(I)/2024 and PRAL digital invoicing standards.
1-Click "Fetch from FBR" Taxpayer Auto-Fill
Avoid typing errors and non-ATL buyer penalties. Simply enter a 7-digit NTN or 13-digit CNIC and click Fetch from FBR to populate registered business details directly from PRAL Iris servers in ~80ms.
Line Items Engine, PCT Code Search & Advance Taxes
The platform computes sales tax (18%), extra tax, further tax (for non-ATL buyers), FED, and withholding advance income taxes (Sections 236CB and 236H) automatically.
| # | Product Description | HS / PCT Code | Qty | Price (PKR) | Tax | Line Total |
|---|---|---|---|---|---|---|
| 1 | Pure Copper Electrical Cable (10mm) | 7408.1100 | 10 Meter | 1,450.00 | 18% ST | 17,110.00 |
Bulk Excel / CSV Invoicing & Custom Field Mapper
Designed for enterprise ERPs and accounting teams processing thousands of invoices per hour. The Bulk Import Engine (/invoices/import) ingests any arbitrary Excel or CSV layout with dynamic column mapping, pre-flight fiscal validation, and asynchronous queue execution.
Drag & Drop Spreadsheet
Upload raw .xlsx or .csv files up to 25MB directly. Automatically parses multiple sheets.
Interactive Column Mapper
Map custom ERP columns (e.g. "Customer_Tax_ID" → Buyer NTN) with remembered presets.
Pre-Flight Fiscal Validation
Validates HS codes, tax mathematics, and non-ATL buyer status before queue submission.
Certified Ledger, FBR QR Code & Fiscal Verification
Once posted, every invoice is issued an immutable FBR Invoice Reference Number (IRN), a dynamic cryptographically signed QR code verifying authenticity with PRAL servers, and a certified audit log.
Scannable by Tax Asaan app or any standard QR scanner to verify live tax credit validity.
Invoice Template Studio & Thermal POS Layouts
The Template Customizer (/invoices/template) lets you personalize PDF layouts, thermal POS receipts (80mm/58mm), custom typography, bank settlement cards, and tokenized invoice numbering.
Full A4 corporate layouts with customizable brand accent colors, logos, and bank settlement footers.
High-speed point-of-sale thermal receipts formatted with instant scannable PRAL QR codes.
Dynamic Numbering Engine & Fiscal Year Rollover
The Numbering Engine provides customizable tokenized patterns ({PREFIX}/{FY}/{SEQ:5}) with zero-collision row locks and automatic Pakistani fiscal year rollover (July 1 to June 30).
Official Developer SDKs, E-Commerce Plugins & OpenAPI
Integrate your Laravel, WooCommerce, Shopify, or custom ERP platforms using our official open-source packages and OpenAPI 3.1 specifications (visit Resources Hub).
Laravel SDK
PHP 8.2–8.5 compatible with automatic retry, IRN caching, and mock testing.
WooCommerce Plugin
Automatic checkout order sync, FBR IRN receipt generation, and QR injection.
Shopify & HMAC Webhooks
Plug orders/create webhooks directly into InvoiceHub PK with automatic FBR post.
Shopify Store Connector & Metafield Setup Guide Zero-Code Webhook
Step-by-step guide to connect Shopify orders, create Order Metafields, and inject FBR QR codes into emails.
- In Shopify Admin, go to Settings → Notifications.
- Scroll down to Webhooks → Click Create webhook.
- Set Event to
Order payment(topic:orders/paid). - Set Format to
JSON. - Set URL to:
In Shopify Admin → Settings → Custom data → click Orders → Add definition:
{% if order.metafields.fbr_di.invoice_number %}
<div style="margin-top: 16px; padding: 12px; border: 1px solid #6366f1; border-radius: 8px; background: #f8fafc;">
<p style="margin: 0; font-weight: bold; color: #1e1b4b;">FBR PRAL Certified Digital Invoice: {{ order.metafields.fbr_di.invoice_number }}</p>
<p style="margin: 4px 0 0; font-size: 12px; color: #475569;">Status: {{ order.metafields.fbr_di.status }} • SRO 350(I)/2024 Compliant</p>
<p style="margin: 8px 0 0;"><a href="{{ order.metafields.fbr_di.qr_url }}" target="_blank" style="color: #4f46e5; font-weight: 600;">Verify on FBR Tax Asaan Portal →</a></p>
</div>
{% endif %}
OpenAPI 3.1 & Interactive Swagger Sandbox
Explore all endpoints, payloads, request schemas, and code generation across cURL, PHP, Node.js, and Python at /docs/api.
HMAC-SHA256 Webhook Delivery & Manual Replay
Operator Productivity & Keyboard Shortcuts
Instant search across invoices, drafts, buyers, items, and clients from any screen.
Auto-fills legal name, STRN, ATL status, and province in ~80ms with zero typos.
Run and clear all mandatory sector scenarios with PRAL in seconds.