A proper FBR API integration in Pakistan is what turns a normal invoicing app into a compliance-aware system. Your team maps customers and products once; each invoice is validated in software before it becomes a payload the FBR can accept.
For the full business context, start with FBR digital invoicing in Pakistan (main guide)—this page is for integration and operations readers.
What the FBR side of integration does
Through FBR-recognized interfaces, your software can run pre-submission validation, then perform real-time invoice posting (or the timing your program allows) so authority-side records can align with what you issue to buyers. The exact services and field names are defined in the current official documentation; treat any sample below as illustrative of the shape of an integration, not a copy-paste of a live spec.
Step-by-step integration (typical order)
- Credentials & environment — Register for sandbox/production per FBR process; store keys outside spreadsheets; separate test from live data.
- Map master data — Customers (NTN, province, registration type) and products (HS, UoM, price rules) must match what you will put on every line.
- Build the invoice in your app — Line-level taxes in the right order: sales tax, further tax, extra tax, FED, withholding as applicable—before any API call.
- Validate — Call validation services first; do not “post and hope” if your stack supports a pre-check path.
- Post / submit — On success, persist the response (status, trace IDs, FBR reference fields per spec) on the invoice record.
- Reconcile & monitor — Finance matches posted invoices to sales and to returns; repeat failures are almost always a data defect—see FBR invoice errors & solutions.
Our blog How to integrate the FBR API (step by step) goes deeper on roles, testing, and go-live checklists.
Example: illustrative JSON payload (not live API spec)
The real schema uses the field names in FBR/PRAL documentation. This generic structure shows what most teams logically send: header + line items + tax breakdowns.
{
"invoice": {
"issueDate": "2026-04-28",
"buyer": {
"ntn": "0000000-0",
"businessName": "Example Buyer (Pvt) Ltd",
"province": "Punjab",
"registrationType": "Registered"
},
"lines": [
{
"lineNo": 1,
"hsCode": "0000.0000",
"uom": "NOS",
"quantity": 10,
"unitPriceExclTax": 1000.00,
"salesTax": 180.00,
"furtherTax": 0.00
}
]
}
}Replace field names, mandatory blocks, and tax logic with the current official document for your program and sector.
Common API errors (message patterns) & what to do
FBR/PRAL responses vary by build; the meaning of failures is consistent. When you see something like the patterns below, fix data first, not the transport layer.
| Error pattern (as users often describe it) | Root cause (most common) | Fix (copy this checklist) |
|---|---|---|
| Invalid HS / HS code not found | Product master does not use the HS/UoM combination FBR expects. | Open the product, align HS and UoM to the catalog, re-validate, re-post. |
| Buyer not found / invalid NTN | NTN, province, or registration type not consistent with FBR records. | Re-verify the customer; correct NTN; re-fetch or re-enter from IRIS-consistent data. |
| Tax line mismatch / further tax | Manual Excel vs system tax order; wrong buyer class. | Recalculate in software; fix buyer registration type; never patch “totals” only. |
| Authentication / session failed | Expired credential, wrong environment, or clock skew. | Rotate token per SOP, confirm sandbox vs production URL, check server time. |
The full list with your exact wording: FBR invoice errors & solutions and the blog on common FBR invoice errors.
Why integration quality matters
Poorly mapped fields—wrong HS, UoM, or tax lines—create avoidable validation loops. Good integration keeps catalog and customers aligned with FBR expectations. In Wise Digital Invoice, FBR connection is per company with clear controls so operators are not pasting credentials into ad hoc tools.
Get a walkthrough
Wise Digital Invoice packages validation, posting, and reporting. Sign in or contact us for a free demo on your data model.
FAQ: FBR API integration Pakistan
- Is FBR API integration the same for every business?
- No—sector, program, and FBR materials define what you must send. The integration discipline (validate → post → log) is the same.
- What is real-time invoice posting to FBR?
- Issuing a structured payload close to the business event, after validation, so finance is not batching at period-end—subject to your program’s timing rules. See the flow section of our main guide.
- How do I fix invoice errors from the API?
- Map the error to buyer, line, or tax; fix the source record; re-validate. Use FBR invoice errors & solutions for a systematic playbook.