FBR invoice API integration, explained for businesses and developers

What the FBR invoice API does

FBR's digital invoicing is API-driven: instead of manually keying invoices into a portal, software submits each sale to FBR's system (operated through PRAL) in a structured format. FBR validates the data and responds with a unique Invoice Reference Number (IRN) and the details needed to print a verifiable QR code. That round trip — submit, validate, receive IRN and QR — is the core of every FBR-compliant invoice. For the non-technical version, see FBR integration, and for what "digital" really means, what is digital invoicing.

The step-by-step integration flow

At a high level, an integration follows the same sequence for every invoice. The software authenticates with FBR and obtains a token. It builds the invoice as structured data — seller and buyer details, item lines with HS codes, tax by line, and totals. It submits that to the digital invoicing endpoint. FBR validates it against its rules and reference data, then responds either with acceptance (returning the IRN and QR data) or a rejection with a reason. Finally, the software records the result and prints the IRN and QR on the invoice.

Everything that feels complicated about "the API" is really just doing those steps reliably, for every sale, without a human in the loop — and handling the cases where a submission fails and needs to be retried or corrected.

Authentication and tokens, in plain terms

Access is token-based. The software proves who it is and receives a token that authorises its requests, rather than a person logging in each time. Tokens are issued first for a sandbox (testing) environment and later for production (live) use. Some setups also involve technical prerequisites such as IP whitelisting. These details are exactly the kind of thing that changes over time, so a live integration has to be maintained, not just built once.

Scenario testing before go-live

Before real invoices can flow, a solution works through FBR's sandbox scenario tests — sample invoices across sale types such as standard-rated, reduced-rate, exempt, and zero-rated. Passing the assigned scenarios is what unlocks a production token. This step matters because it is where configuration mistakes (a wrong tax treatment, a missing field) get caught safely, before they can appear on a real, reported invoice. Our FBR Digital Invoice Guide covers where this testing sits in the overall setup.

How integration actually works under the hood

Reference data such as tax rates, HS codes, and units of measure is fetched from the API rather than hardcoded, so the integration stays correct when FBR updates rates. Good integrations also handle rejections gracefully — surfacing the reason immediately so it can be fixed — and queue-and-retry submissions when connectivity drops, so no sale silently goes unreported. This is the same reliability that makes counter-based POS integration workable at speed.

Build it yourself, or use a ready platform

If you have developers, you can integrate any system capable of authenticated API calls. The trade-off is ongoing ownership: authentication, validation, error handling, and keeping up with FBR's changes are all yours to maintain. The alternative is to use a platform that already carries the integration — our FBR invoice software submits every invoice, handles the token flow and validation, and returns the IRN and QR automatically, so your team works with invoices rather than API payloads. Current plans are on the pricing page.

What FBR Invoice Atsolhive handles for you

On our platform, the API layer is invisible to the user: create an invoice, and it's validated, submitted, and returned with its IRN and QR code. That includes POS-based flows — see FBR POS integration — and the reporting that follows. If your business needs something bespoke on top of that, get in touch or start from the homepage, and we'll talk through it.

What data an FBR invoice actually carries

When people picture "an API call," they imagine something abstract, but the payload is just the invoice expressed as structured data. It includes the seller's registration details, the buyer's details where the buyer is registered, and a line for each item sold — description, quantity, unit price, HS code, the applicable tax rate and amount, and the line total — followed by invoice-level totals. The response adds FBR's own contribution: the IRN and the data for the QR code.

Understanding this helps demystify the whole exercise. Everything the API needs is information a correct invoice already contains; the integration's job is to present it in the exact structure FBR expects and to handle FBR's reply. When a submission is rejected, it is almost always because one of these fields is wrong or missing — a bad HS code, a mismatched registration number — which is the same root cause behind most common invoice mistakes.

Reliability, retries, and error handling

A real business cannot afford for a sale to silently fail to reach FBR because the connection dropped for a moment. This is why the unglamorous parts of an integration matter most: queuing invoices that could not be submitted immediately, retrying them automatically when the connection returns, and clearly flagging any that FBR rejects so a person can fix them. An integration that only handles the happy path looks fine in a demo and causes compliance gaps in real use.

When you evaluate any FBR invoicing solution — built or bought — these are the questions worth asking: what happens when the internet drops mid-sale, how are rejections surfaced, and how quickly can a rejected invoice be corrected and resubmitted. Our platform handles this retry-and-flag logic for you, which is a large part of what "already integrated" really buys.

Security and access considerations

Because the integration acts on your business's behalf with FBR, access needs to be handled carefully. Tokens should be kept secure, access should be limited to the systems that need it, and any technical prerequisites FBR sets — such as IP whitelisting where required — should be met. These are the kinds of details that a maintained platform keeps current, and that a home-grown integration has to keep revisiting as requirements evolve.

It is also worth separating the sandbox and production environments cleanly in your own thinking. Testing belongs in the sandbox, where mistakes have no consequences; only once your flows are proven should real invoices go to production. Mixing the two — or leaving test credentials active against live data — is an avoidable source of both errors and risk. A good platform enforces this separation for you, so your live invoicing is never running on anything that has not already been validated.

So should you build or buy?

If you are a software company building your own product, or you have specific systems that must talk to FBR directly, building the integration may make sense — provided you can commit to maintaining it as FBR changes. For most businesses whose goal is simply to issue compliant invoices, a ready platform is faster to adopt, cheaper to run than a maintained in-house integration, and one less thing to worry about when FBR updates its system. Our FBR invoice software is built for exactly that outcome, with pricing to match different business sizes.