FBR Digital Invoicing API Documentation: Sample JSON Payload and Response (DI v1.12)
A plain-English walkthrough of the FBR Digital Invoicing (DI) API v1.12 documentation — the invoice header and item fields, a sample sale-invoice JSON request and response, and how the IRN and QR code come back.
How the DI API request is shaped
An FBR Digital Invoicing request is a single JSON object with an invoice header plus an items array. The header carries invoice-level fields — invoiceType (Sale Invoice or Debit Note), invoiceDate in YYYY-MM-DD, seller NTN/CNIC, business name, province and address, the same buyer fields, buyerRegistrationType (Registered or Unregistered), and — for sandbox only — a scenarioId such as SN001.
Each entry in items describes one line: hsCode, productDescription, rate (for example '18%'), uoM, quantity, valueSalesExcludingST, salesTaxApplicable, and optional fields such as furtherTax, extraTax, fixedNotifiedValueOrRetailPrice, sroScheduleNo and sroItemSerialNo. The request is sent to FBR's validate endpoint (a dry run) or the post endpoint (a real submission) with a Bearer token that decides whether you hit sandbox or production.
A minimal sample sale-invoice payload
A standard-rate sale to a registered buyer (scenario SN001) looks like this: a header with invoiceType 'Sale Invoice', the seller and buyer NTNs, provinces and addresses, buyerRegistrationType 'Registered', scenarioId 'SN001' (sandbox), and one item — hsCode '0101.2100', rate '18%', uoM 'Numbers, pieces, units', quantity 400, valueSalesExcludingST 1000, salesTaxApplicable 180, saleType 'Goods at standard rate (default)'.
Two details trip people up most. First, extraTax must be an empty string (not 0) for reduced-rate, zero-rated, exempt and non-adjustable supplies, or FBR returns error 0091. Second, for 3rd Schedule goods the tax is calculated on fixedNotifiedValueOrRetailPrice (the printed retail price) with valueSalesExcludingST set to 0, not the other way round.
What the response returns
A successful post returns an invoiceNumber (the Invoice Reference Number / IRN, for example '7000007DI1747119701593'), a dated timestamp, and a validationResponse with statusCode '00' and status 'Valid', including a per-item status list. That IRN plus the data for the Version 2.0 QR code is what must be printed on the invoice.
A failure returns statusCode '01' with an errorCode and message — either at invoice level (header problem, no item statuses) or per item (for example errorCode 0077 'Valid SRO/Schedule No. is mandatory where rate is not 18%'). The fix is to correct the flagged field and re-validate; FBR's error codes map to specific fields, so the message points straight at the problem.
Building this yourself vs using a ready platform
Constructing these payloads correctly means keeping up with HS-code-to-UoM rules, sale-type-to-rate lookups, SRO schedules, the empty-string extraTax rule and the tax-calculation formulas that FBR validates server-side. A direct integration is doable but is ongoing work as the spec and SROs change.
Digi Invoice is built on the DI v1.12 specification, so it assembles the correct payload from a simple invoice form, validates every field before submission, and surfaces FBR's error codes in plain language when something is off — you get the IRN and QR without writing or maintaining the API code yourself.