Whether you're a software developer building an FBR-integrated system or a business owner trying to understand the technical requirements, this guide covers everything you need to know about integrating with the FBR Digital Invoicing API through PRAL DI API v1.12.
Understanding the FBR Digital Invoicing Ecosystem
The FBR Digital Invoicing system works through a chain of three components:
- Your Business Software — The invoicing application your staff uses daily
- Licensed Integrator (PRAL/Haball/EY/WebDNA) — The authorized gateway that connects your software to FBR
- FBR IRIS Portal — The government system where all invoices are stored and verified
Most businesses choose PRAL (Pakistan Revenue Automation Limited) as their integrator because it's government-backed and free of cost.
Pre-Integration Requirements
1. Business Registration
- Active NTN (National Tax Number) registered with FBR
- Sales Tax Registration Number (STRN)
- Business must be in the list of entities required to integrate (Tier-1 retailers, manufacturers, etc.)
2. IRIS Portal Setup
- Visit iris.fbr.gov.pk
- Login with your NTN credentials
- Navigate to Registration → Digital Invoicing
- Select PRAL as your Licensed Integrator
- Accept terms and complete registration
- Receive your Client ID and Client Secret — these are your API credentials
API Architecture Deep Dive
Base URLs
| Environment | Purpose |
|---|---|
| Sandbox | Testing and development — no real FBR submissions |
| Production | Live environment — real invoices sent to FBR |
Authentication Flow (OAuth 2.0)
Every API interaction requires a valid access token:
POST /api/auth/token Content-Type: application/x-www-form-urlencoded client_id=YOUR_CLIENT_ID client_secret=YOUR_CLIENT_SECRET grant_type=client_credentials
Response:
{
"access_token": "eyJhbGciOiJIUzI1NiIs...",
"token_type": "Bearer",
"expires_in": 3600
}
Important: Tokens expire after 1 hour. Implement automatic token refresh in your application.
Reference Data APIs
Before creating invoices, your system must fetch reference data. This is what makes an API-driven approach superior to hardcoding — when FBR updates any reference data, your software automatically picks up the changes.
Key Reference Data Endpoints:
- HS Codes — Harmonized System codes for classifying products. Over 5,000 codes with descriptions
- UOM Codes — Unit of Measurement codes (KG, PCS, MTR, LTR, etc.). Each HS code has associated valid UOM codes
- Sale Types — Classification of sale transactions (standard sale, zero-rated, exempt, reduced rate)
- Tax Rates — Current applicable tax rates for different sale types and product categories
- Document Types — Invoice, Credit Note, Debit Note identifiers
- Extra Tax Rates — Additional taxes like further tax, extra tax, advance withholding tax
Invoice Submission Flow
The recommended flow for submitting an invoice:
- Validate — Call the pre-submit validation endpoint to check for errors
- Review — Fix any validation errors returned
- Submit — Send the validated invoice to FBR
- Confirm — Receive the FBR response with IRN (Invoice Reference Number) and QR code data
Invoice Payload Structure:
{
"header": {
"document_type": "INV",
"sale_type": "1",
"invoice_number": "INV-2025-001",
"invoice_date": "2025-04-17",
"buyer_ntn": "1234567-8",
"buyer_name": "Ali Traders",
"buyer_phone": "03001234567"
},
"items": [
{
"hs_code": "8471.30",
"item_name": "Laptop Computer",
"uom_code": "PCS",
"quantity": 2,
"rate": 150000,
"amount": 300000,
"sales_tax": 51000
}
],
"totals": {
"total_amount": 300000,
"total_sales_tax": 51000,
"grand_total": 351000
}
}
Tax Calculation Logic
Understanding how taxes work in the FBR DI system is crucial:
Sales Tax (GST)
Standard rate is 18% on most goods (previously 17%, updated in recent budget). However, rates vary by product category and sale type. Never hardcode this value — always fetch from the API.
Further Tax
Applied when the buyer is not on FBR's Active Taxpayer List (ATL). Currently 3% of the value of supply.
Extra Tax
Additional tax on specific product categories as notified by FBR through SROs.
Advance Income Tax
Withholding tax collected at the point of sale for certain transactions.
Error Handling Best Practices
Common API errors and their solutions:
| Error | Cause | Solution |
|---|---|---|
| Invalid HS Code | Using an outdated or incorrect HS code | Always fetch HS codes from the reference data API |
| Buyer NTN Not Found | NTN not registered or incorrectly formatted | Validate buyer NTN format before submission |
| Duplicate Invoice | Same invoice number submitted twice | Implement unique invoice number generation |
| Token Expired | Access token has expired | Implement automatic token refresh before each API call |
| Invalid UOM for HS Code | UOM code not valid for the selected HS code | Filter UOM options based on selected HS code |
| Tax Calculation Mismatch | Calculated tax doesn't match FBR expected amount | Use FBR-provided tax rates, not hardcoded values |
Sandbox Testing Checklist
Before going live, verify these scenarios in the sandbox:
- ✅ Standard B2B invoice (buyer with NTN)
- ✅ B2C invoice (buyer with CNIC)
- ✅ Invoice with multiple line items
- ✅ Invoice with further tax (non-ATL buyer)
- ✅ Invoice with reduced rate (SRO)
- ✅ Zero-rated supply
- ✅ Credit note against existing invoice
- ✅ Debit note adjustment
- ✅ Invoice with UOM conversion
- ✅ Error handling for rejected invoices
Going Live — Production Checklist
- Switch API base URL from sandbox to production
- Update client credentials if production uses different keys
- Submit first test invoice with a real transaction
- Verify invoice in FBR IRIS portal
- Scan QR code with Tax Asaan app to verify
- Confirm printable invoice includes all FBR-required elements
The Easier Alternative: Pre-Built Solutions
Building your own FBR integration from scratch typically takes 3-6 months of developer time. You need to handle authentication, reference data caching, invoice validation, error handling, QR code generation, and ongoing maintenance as FBR updates their API.
Alternatively, you can use a ready-made solution like Logic Layer's FBR Digital Invoicing, which is already fully integrated with PRAL DI API v1.12 and ready to use — including web app + Android mobile app.
- 100% API-driven with no hardcoded logic
- Web app + Android mobile app included
- Built-in sandbox/production toggle
- Pre-submit validation to prevent FBR rejections
- Starting from just PKR 2,500/month
👉 Contact Logic Layer for a free demo and consultation.
FAQs
Can I use my own software with PRAL integration?
Yes, if you have development resources, you can integrate any software with the PRAL API using OAuth 2.0 authentication.
Is there an API rate limit?
FBR imposes rate limits on API calls. Implement caching for reference data to minimize API calls.
What programming languages can I use?
The API is RESTful and language-agnostic. Logic Layer's solution is built in PHP (Laravel), but you can use any language that supports HTTP requests.
How do I handle API downtime?
Implement a queue system that stores invoices locally when the API is unavailable and automatically retries submission when the connection is restored.
