FBR sandbox to production: the scenarios, the token, and the errors that stop you

The FBR digital invoicing API is not complicated. Two endpoints matter, the payload is JSON, and the response comes back in under a second. Teams still lose weeks on it, and almost never because of the API itself.

What follows is drawn from PRAL's own technical specification for the DI API, version 1.12. Where something is not in that document, we say so rather than repeating what other vendors have written.

Sandbox and production share a URL

This is the detail that catches the most teams, and it is worth stating plainly: the sandbox and production endpoints are the same URLs. What determines which environment you are hitting is the bearer token in the Authorization header.

The practical consequence is that a token pasted into the wrong environment variable will file live invoices against a test run, or silently send real documents nowhere. Treat the two tokens with the same care you would apply to a payment gateway key, and make the active environment visible in your own interface rather than inferring it from a URL.

PRAL-issued tokens are valid for five years. That sounds generous until you consider that nobody will remember the renewal, so put the expiry in whatever calendar actually gets looked at.

The twenty-eight scenarios

Before production access, you clear sandbox scenarios — twenty-eight of them, numbered SN001 to SN028. You do not clear all twenty-eight. Which ones apply depends on the business activity declared in your registration, and this is the single most common cause of a stalled go-live: a team working through the wrong set.

A general manufacturer typically has to clear SN001 and SN002 (standard rate to registered and unregistered buyers) along with the scenarios covering their specific goods. A steel melting or re-rolling business picks up SN003, with ship breakers on SN004. Third Schedule goods fall under SN008, cotton ginners SN009, telecom SN010, mobile phones SN015, services SN019, electric vehicles SN020. Retailers selling to end consumers have their own set in SN026 to SN028.

Get the applicable list confirmed in writing before you start building test cases. Working through scenarios that do not apply to you wastes days, and discovering a missing one after you thought you were finished wastes more.

The errors that actually stop people

Validation failures cluster in a handful of places, and all of them are data problems rather than code problems.

Missing HS code (0019)

HS code is mandatory on every line. If your item master does not carry it, this is your project — not the API work. Expect this to be the longest task in the whole integration.

Buyer registration format (0002)

A buyer must be identified by a 13-digit STRN or a 7 or 9 digit NTN. Registrations stored with dashes, spaces or trailing characters fail, and most customer masters have some.

Invoice date format (0005)

YYYY-MM-DD, without exception. Systems that store dates as text in a local format will need a conversion layer.

Notes without a reference or reason (0026–0028)

A debit or credit note must carry the reference of the invoice it adjusts and a stated reason. Systems that treat a credit note as a standalone document cannot satisfy this without a change.

The reference data you should not hard-code

Alongside the two invoice endpoints, the specification documents a set of reference lookups — provinces, document types, item description codes, SRO item codes, transaction types, units of measure, SRO schedules, sale-type-to-rate mappings, and HS-code-to-UoM pairings. There are also lookups for checking a buyer against the active taxpayer list and determining their registration type.

Use them. Rates and schedules change with every finance act, and a system that hard-codes them becomes a maintenance liability the first time something moves. Caching the reference data daily is sensible; baking it into source is not.

The printed invoice has requirements too

Integration is not finished when the API returns a reference. The specification sets out what must appear on the document the customer receives: a QR code to version 2.0 at 25 by 25, printed at one inch square, alongside the FBR Digital Invoicing System logo, on every invoice.

This catches businesses with pre-printed stationery or narrow thermal rolls, and it is worth checking against your actual printers early rather than discovering it the week you go live.

What we could not verify

Several Pakistani vendor sites describe a cancellation endpoint and a 72-hour window for correcting a filed invoice. Neither appears anywhere in PRAL specification v1.12, which documents only the post and validate operations. The specification instead handles adjustments through debit and credit notes.

We mention this because building against a documented-but-nonexistent endpoint is an expensive mistake, and because a vendor repeating the claim has probably not read the specification. If you have seen an official source for it, we would genuinely like to see it.

Common questions