The Ultimate Guide to FBR API Integration: 13 Essential Features for Seamless Digital Invoicing in Pakistan

Author: Published: Updated:

Summary: FBR API integration for digital invoicing in Pakistan: sandbox vs production, local validation, submission handling, 28 FBR scenarios, STATL and QR codes.

The Ultimate Guide to FBR API Integration: 13 Essential Features for Seamless Digital Invoicing in Pakistan

The Federal Board of Revenue (FBR) has made digital invoicing mandatory for a growing list of businesses in Pakistan, and every one of those invoices has to pass through the FBR Digital Invoicing API. Integrating with that API directly is slow and error-prone: strict JSON schemas, reference-data codes, sandbox scenarios, timeouts and cryptic rejection messages. FBRSTAPP wraps all of that into one integration layer. This guide explains the 13 features that layer provides and why each one matters for compliance.

In short: FBRSTAPP handles the full invoice lifecycle: local validation, queued submission with retries, sandbox and production environments, FBR reference data (provinces, UOM, HS codes, SRO items), all 28 FBR sandbox scenarios, STATL buyer checks and the FBR QR code. You configure two tokens; the platform does the rest.

How FBR API integration works end to end

Before the feature list, here is the path every invoice takes. Nothing reaches FBR until it has passed local validation, and nothing is lost if the FBR gateway is slow or temporarily down.

FBRSTAPP invoice lifecycle: create, validate, queue, submit to the FBR Digital Invoicing API, receive the FBR invoice number, deliver with QR code
FBRSTAPP invoice lifecycle: create, validate, queue, submit to the FBR Digital Invoicing API, receive the FBR invoice number, deliver with QR code

1. Complete FBR API integration

FBRSTAPP supports the entire invoice lifecycle, not only invoice creation. It submits each invoice to the FBR servers, performs real-time validation against the FBR schema, stores the FBR response, and lets you look up previously submitted invoices.

Whether you issue one invoice a day or thousands, the integration makes sure the data reaches FBR securely and in the exact format FBR expects.

2. FBR reference data built in

FBR rejects invoices that use unknown codes. FBRSTAPP keeps the official FBR reference tables in sync and uses them in every form and import:

  • Provinces for the correct provincial sales-tax treatment
  • Units of measurement (UOM) for every line item
  • HS codes for product classification
  • SRO items and serials for reduced-rate, exempt and special-regime goods

Because every invoice is built from FBR-approved values, rejection rates drop sharply.

3. Sandbox and production environments

FBR requires every business to complete its sandbox scenarios before a production token is issued. FBRSTAPP supports both environments side by side: build and test in the sandbox without touching real tax records, then switch to production with a single setting once your scenarios pass.

FBR sandbox versus production environment: endpoints, tokens, purpose and exit criteria
FBR sandbox versus production environment: endpoints, tokens, purpose and exit criteria
FBRSTAPP Settings > FBR API Settings: choose the active environment and store the sandbox and production tokens (stored encrypted)
FBRSTAPP Settings > FBR API Settings: choose the active environment and store the sandbox and production tokens (stored encrypted)

4. Guided invoice building

Instead of hand-writing large nested JSON payloads, invoices are assembled step by step: customer, line items, HS codes, quantities, rates and SRO references. The platform turns that into the exact FBR payload. The same builder powers the on-screen form, Excel bulk upload and the API, so every channel produces identical, valid JSON.

5. Linked local records

Invoices, line items, customers, submissions and reference data are stored in a relational model with proper relationships. Reports, searches and status tracking run on your own data without calling the FBR API again, and every FBR response is kept with the invoice for audit.

6. Background processing with retries

FBR gateway timeouts are common during peak hours. Submissions are pushed to a queue instead of blocking the user, and failed attempts are retried automatically with the original payload. Users never wait on a spinner, and no invoice is lost when FBR is temporarily unavailable.

7. Validation before the FBR call

Every invoice is validated locally against FBR rules first: NTN and CNIC formats, tax calculations, reference codes and mandatory fields. Errors are shown in plain language while the invoice is still a draft. That saves API quota, speeds up data entry and prevents rejections.

Local validation checklist FBRSTAPP runs before an invoice is sent to the FBR API, and what happens when a check fails or passes
Local validation checklist FBRSTAPP runs before an invoice is sent to the FBR API, and what happens when a check fails or passes

8. Readable error handling

When FBR does reject a submission, the raw error code is translated into a human-readable message that tells the operator what to fix. Every error is logged with the request, response and timestamp, so support and developers can trace exactly what went wrong and when.

9. FBR QR code generation

FBR requires a specific QR code on every digital invoice. After FBR accepts an invoice, FBRSTAPP generates the QR code in the size and version FBR requires (Version 2.0, 25 x 25, printed at 1.0 x 1.0 inch). The code carries the FBR invoice number with key invoice details such as the date, seller and buyer, total and sales tax, and is placed with the FBR Digital Invoicing logo on the printable PDF. Buyers and auditors can scan it to verify the invoice. See how FBR digital invoice verification works.

10. Maintenance and automation tools

Administrators get command-line and scheduled tools to sync the latest FBR reference data, inspect and re-queue pending submissions, and trigger bulk re-submissions. These run as cron jobs so the platform stays current without manual work.

11. All 28 FBR sandbox scenarios

The FBR sandbox defines 28 test scenarios: standard-rate sales to registered and unregistered buyers, reduced-rate Eighth Schedule goods, exempt Sixth Schedule goods, zero-rated supplies, Third Schedule retail-price items, services, and more. FBRSTAPP pre-configures each scenario with the fields FBR expects, shows only the scenarios that apply to your business activity and sector, and tracks which ones you have passed.

FBRSTAPP Scenario Invoice Generator listing the FBR sandbox scenarios applicable to a business profile
FBRSTAPP Scenario Invoice Generator listing the FBR sandbox scenarios applicable to a business profile

12. STATL buyer verification

The Sales Tax Active Taxpayer List (STATL) determines how a buyer must be taxed. FBRSTAPP checks the buyer’s NTN against STATL in real time, so the invoice automatically uses the registered-buyer or unregistered-buyer scenario and applies further tax where the law requires it.

STATL check flow: buyer NTN is looked up on the active taxpayer list to decide between registered and unregistered buyer treatment
STATL check flow: buyer NTN is looked up on the active taxpayer list to decide between registered and unregistered buyer treatment

13. A clean integration interface

All of the above sits behind a small, stable interface. Submitting, validating or verifying an invoice is a single call for developers, and a single button for operators, while the orchestration (validation, queueing, retries, logging, QR generation) happens underneath. Integrators can connect their own ERP or POS without re-implementing FBR rules.

Conclusion

Integrating with FBR does not have to slow your business down. With complete API coverage, local validation, queued submission, sandbox-to-production support, STATL checks and FBR QR codes, FBRSTAPP does the heavy lifting so you can focus on selling.

Frequently asked questions

What is FBR API integration?

It is the connection between your invoicing software and the FBR/PRAL Digital Invoicing API, which validates and records each sales tax invoice and returns an FBR invoice number.

How does FBR API integration work?

The software sends each invoice as JSON with your security token. The validate call checks it, the post call records it, and FBR returns the FBR invoice number that is printed with the FBR QR code. Testing happens in the sandbox first, then in production.

Who needs FBR API integration?

Sales tax registered persons that FBR has notified for digital invoicing, either through their own integration or through software such as FBRSTAPP.

What are the requirements for FBR API integration?

Digital invoicing access in IRIS, sandbox and production tokens, the FBR sandbox scenarios for your business activity, a whitelisted IP for production calls, and correct reference data such as HS codes, units, rates and SROs.

Is FBR API integration mandatory?

Digital invoicing is mandatory for the categories FBR has notified, and invoices can only be reported through the DI API, so those businesses need an integration of their own or ready software.

About the author

, Founder, FBRSTAPP. Muhammad Yousaf Iqbal is the founder of FBRSTAPP, a Pakistani cloud application for FBR digital invoicing. He leads the product and its integration with the FBR/PRAL Digital Invoicing API, from sandbox scenario testing to production submission, FBR invoice numbers and QR codes.

More about Muhammad Yousaf Iqbal · LinkedIn