How to Connect a Custom Web App to the PRAL Digital Invoice API

From access to your first posted invoice

1. Step 1

   Get access: IRIS, integrator and sandbox

   Register for Digital Invoicing in IRIS and pick the integrator. The PRAL papers say PRAL integration and sandbox are free. If you pick another integrator, that company reviews your application and handles IP whitelisting and sandbox. The sandbox opens after approval, and you copy its address, token and sample JSON from the Sandbox tab.

   IRIS registration and who must join →

2. Step 2

   Know the two calls and the addresses

   There are two main calls: validate (checks the invoice without saving it) and post (sends it for real). Sandbox and production have separate addresses, and the sandbox ones end in _sb. Sandbox post: gw.fbr.gov.pk/di_data/v1/di/postinvoicedata_sb. Production post: gw.fbr.gov.pk/di_data/v1/di/postinvoicedata. Validate uses validateinvoicedata_sb or validateinvoicedata.

3. Step 3

   Send the token in the header

   Every request carries your token in the Authorization header as a Bearer token. Use the sandbox token for the sandbox and the production token for production. The papers say a token is valid for 5 years. An HTTP 401 means a bad token or a token from the wrong environment.

   POST https://gw.fbr.gov.pk/di_data/v1/di/postinvoicedata_sb
   Authorization: Bearer <your-sandbox-token>
   Content-Type: application/json

   💡 Do not call the API from the visitor's browser with the token inside. Keep it on a server or a PC you control. ApnaBill does the same: the token stays in the FBR Sender on the shop PC.

4. Step 4

   Build the invoice JSON

   The invoice is one JSON. The header goes once: invoiceType, invoiceDate, seller and buyer details, buyerRegistrationType and invoiceRefNo. Then comes an items list. The sandbox also needs a scenarioId. Each item needs: hsCode, productDescription, rate, uoM, quantity, totalValues, valueSalesExcludingST, fixedNotifiedValueOrRetailPrice, salesTaxApplicable, salesTaxWithheldAtSource and saleType. Optional: extraTax, furtherTax, sroScheduleNo, fedPayable, discount, sroItemSerialNo.

   {
     "invoiceType": "...",
     "invoiceDate": "YYYY-MM-DD",
     "buyerRegistrationType": "Registered | Unregistered",
     "invoiceRefNo": "...",
     "scenarioId": "SNxxx (sandbox only)",
     "items": [ { "hsCode": "0000.0000", "uoM": "...", "quantity": 1, "rate": "..." } ]
   }
   // Field names only. Take exact values and the full field list from the PRAL Technical Documentation.

   💡 The buyer NTN or CNIC may be left out only when the buyer is Unregistered.

5. Step 5

   Write the fields the way FBR expects

   Date is YYYY-MM-DD and a future date is rejected. NTN and CNIC are digits only, with no dashes. The HS code is 4 digits, a dot, then 4 digits. Province is the province name, not a city. The buyer type is exactly Registered or Unregistered. The unit (UoM) is case-sensitive, so write KG, not kg. Numbers cannot be negative or empty, with up to 2 decimals and up to 4 for quantity. The tax amount must equal the sale value times the rate. If the rate is not 18%, give the SRO or schedule number and the SRO item serial number.

   Find the HS code for a product →

6. Step 6

   Use the FBR reference lists instead of guessing

   FBR gives lists of the exact valid values, and they need your token. They cover provinces, document types, HS codes, SRO items, sale types, units (and the units allowed for an HS code) and the rates allowed for each sale type. There are also checks for whether a registration number is active and whether it is Registered or Unregistered.

   See the list paths in the PRAL guide →

7. Step 7

   Read the reply, including each item line

   A good reply has statusCode 00 and an invoiceNumber made by FBR. A bad reply has statusCode 01 and an error code. Also look inside invoiceStatuses, because each item line can have its own error. HTTP replies are 200, 401 and 500 (server problem).

   Look up an error code →

8. Step 8

   Plan for failures, then print the number and QR

   There is no bulk upload: send each invoice in real time when it is made. Nothing retries by itself, so your software must keep a queue and send again after an internet or system fault. After a successful post, print the FBR invoice number and the QR code on the bill. After sending, changes are made in the IRIS portal or with a debit note, not by editing in your own software.

   QR code and print size →

Make your first invoice free

Questions about this guide

Related guides and tools

• How to Send an FBR Digital Invoice, Step by Step

  Six steps from IRIS registration to your first live invoice, for shops and retailers.

• FBR Invoice QR Code: What It Is and What Size to Print

  What the QR code holds, why you cannot make it yourself, and the two print sizes the FBR papers mention.

• What Is Annexure-C and How It Relates to FBR Digital Invoices

  What Annexure-C is, how digital invoices feed it, and what ApnaBill does and does not do about it.

• PRAL guide (full summary) →
• IRIS guide →
• FBR error codes →
• HS code finder →

All guides →