Complete developer guide for integrating FBR e-invoicing via EZ Invoice REST API endpoints. For ERP vendors, software houses, POS integrators, and AI agents.
https://ezinvoice.pk/api
Bearer Token
JSON
v1
EZ Invoice provides a RESTful API layer that enables third-party systems — including ERP platforms, POS systems, accounting software, and custom applications — to submit digital invoices to Pakistan's FBR Digital Invoicing System.
The API supports two modes:
Use for development, testing, and FBR compliance scenario validation. Uses sandbox FBR tokens configured per company.
Endpoint:postinvoicedata_sb
Use for submitting live invoices to FBR. Requires valid production tokens from the FBR IRIS portal.
Endpoint:postinvoicedata
All invoice submission endpoints require a valid Bearer token obtained from the FBR IRIS portal. The token is stored per company in the EZ Invoice platform and is automatically appended to the forwarded FBR request.
| Header | Value | Description |
|---|---|---|
Authorization |
Bearer {token} |
FBR-issued bearer token (configured per company in EZ Invoice) |
Content-Type |
application/json |
Request body format |
Accept |
*/* |
Accepted response format |
Accept-Language |
en-US |
Language preference |
x-request-id |
{unique-id} |
Unique request identifier for tracing |
User-Agent |
ezinvoice.pk/1.0 |
Client identifier |
sellerNTNCNIC in the request body. EZ Invoice matches this to a registered company and uses its pre-configured FBR token automatically. You do NOT need to pass the token in your request body.
Submit a digital invoice directly to the FBR production (live) environment. The invoice data is validated, stored locally, and forwarded to FBR for compliance checking.
This endpoint accepts full invoice data including seller, buyer, line items, tax details, and SRO information. It resolves the seller company by NTN/CNIC, looks up or creates the buyer, resolves items against HS codes, and forwards the structured payload to the FBR Digital Invoicing API. The FBR validation response is stored and returned.
{
"sellerNTNCNIC": "1234567-8",
"buyerNTNCNIC": "9876543-2",
"buyerBusinessName": "ABC Trading Co.",
"buyerAddress": "123 Main Street, Karachi",
"buyerRegistrationType": "Registered",
"buyerProvince": "Sindh",
"invoiceDate": "2025-06-12",
"invoiceNumber": "INV-001",
"invoiceRefNo": "REF-001",
"invoiceType": "Sale Invoice",
"Reason": "",
"items": [
{
"hsCode": "8471.3010",
"productDescription": "Laptop Computer",
"quantity": 2,
"uoM": "Nos",
"rate": "Standard Rate",
"valueSalesExcludingST": 200000.00,
"salesTaxApplicable": 36000.00,
"totalValues": 236000.00,
"discount": 0,
"saleType": "Goods at Standard Rate",
"sroScheduleNo": "SRO 123(I)/2025",
"sroItemSerialNo": "Item 1",
"salesTaxWithheldAtSource": 0,
"extraTax": 0,
"furtherTax": 0,
"fedPayable": 0,
"fixedNotifiedValueOrRetailPrice": 0
}
]
}
{
"validationResponse": {
"status": "Valid",
"message": "Invoice validated successfully"
},
"invoiceNumber": "FBR-INV-000123456",
...
}
{
"success": false,
"message": "Seller not found. No company matches the provided NTN/CNIC."
}
Submit an invoice to the FBR Sandbox environment for testing and compliance scenario validation. The request format is identical to the production endpoint.
iris_sb_token)https://gw.fbr.gov.pk/di_data/v1/di/postinvoicedata_sbRetrieve all active sandbox scenarios available for FBR compliance testing.
[
{
"id": 1,
"scenario_code": "SN001",
"scenario_description": "Goods at Standard Rate",
"sale_type_or_purchase_type": "Goods at Standard Rate",
"trans_type_id": 1,
"active": 1
},
{
"id": 2,
"scenario_code": "SN002",
"scenario_description": "Services at Standard Rate",
"sale_type_or_purchase_type": "Services at Standard Rate",
"trans_type_id": 2,
"active": 1
}
]
Retrieve all active bank accounts for a given company ID.
| Parameter | Type | Description |
|---|---|---|
companyId | Integer | The ID of the company |
[
{
"id": 1,
"company_id": 5,
"bank_name": "Habib Bank Limited",
"account_title": "ABC Trading Co.",
"account_number": "1234567890",
"iban": "PK36HABB001234567890",
"active": 1
}
]
Complete reference of all fields accepted by the invoice submission endpoints.
| Field | Type | Required | Description |
|---|---|---|---|
sellerNTNCNIC | String | Yes | Seller's NTN (7 digits) or CNIC number. Used to identify the company and its FBR token. |
buyerNTNCNIC | String | No | Buyer's NTN or CNIC. If provided, used to find or create a buyer record. |
buyerBusinessName | String | No | Buyer's business name. Defaults to "Unknown Buyer". |
buyerAddress | String | No | Buyer's address. |
buyerRegistrationType | String | No | Registration type. Defaults to "Registered". |
buyerProvince | String | No | Buyer's province name (e.g., "Sindh", "Punjab"). |
invoiceDate | String (Date) | No | Invoice date in Y-m-d format. Defaults to today. |
invoiceNumber | String | No | User-defined invoice reference number. |
invoiceRefNo | String | No | Additional invoice reference. |
invoiceType | String | No | Type of invoice. Defaults to "Sale Invoice". |
Reason | String | No | DR/CR note reason (for debit/credit notes). |
items | Array | No | Array of invoice line items. |
| Field | Type | Required | Description |
|---|---|---|---|
hsCode | String | No | Harmonized System code for the product. |
productDescription | String | No | Description of the product/service. |
quantity | Number | No | Quantity of items. Defaults to 0. |
uoM | String | No | Unit of Measurement (e.g., "Nos", "Kg", "Ltr"). |
rate | String | No | Tax rate description (e.g., "Standard Rate", "Exempt"). |
saleType | String | No | Sale type matching a sandbox scenario (e.g., "Goods at Standard Rate"). |
valueSalesExcludingST | Number | No | Value excluding sales tax. |
salesTaxApplicable | Number | No | Sales tax amount applicable. |
totalValues | Number | No | Total value including tax. |
discount | Number | No | Discount amount. Defaults to 0. |
sroScheduleNo | String | No | SRO Schedule number description. |
sroItemSerialNo | String | No | SRO Item serial number description. |
salesTaxWithheldAtSource | Number | No | Sales tax withheld at source flag/amount. |
extraTax | Number | No | Extra tax amount. |
furtherTax | Number | No | Further tax amount. |
fedPayable | Number | No | Federal Excise Duty payable. |
fixedNotifiedValueOrRetailPrice | Number | No | Fixed notified value or retail price. |
The API returns the raw response from the FBR Digital Invoicing Gateway. The key field to check is validationResponse.status.
| Status | HTTP Code | Meaning |
|---|---|---|
| Valid | 200 | Invoice accepted by FBR. An invoiceNumber is assigned. |
| Invalid | 200 | Invoice data failed FBR validation rules. Check validationResponse for details. |
| Exception / Error | 500 | Server-side error occurred. The invoice is saved locally with status "Error". |
| Validation Error | 422 | Missing required fields (e.g., sellerNTNCNIC). |
| Not Found | 404 | Seller company not found for the provided NTN/CNIC. |
| Bad Request | 400 | No FBR token configured for the seller company. |
Each submitted invoice is stored locally with one of these statuses:
Draft — Initial state before FBR submission.Valid — Successfully validated and accepted by FBR. fbr_invoice_number is populated.Invalid — FBR rejected the invoice data.Error — A system error occurred during submission.| Error | Cause | Solution |
|---|---|---|
sellerNTNCNIC is required |
Missing seller identifier in request body | Include sellerNTNCNIC field with valid NTN or CNIC |
Seller not found |
No company matches the NTN/CNIC | Register the company in EZ Invoice first, ensure NTN/CNIC matches |
No FBR token configured |
Company exists but no FBR token is set | Add FBR sandbox/production token in company settings via EZ Invoice dashboard |
Server error: ... |
Internal exception (DB, network, etc.) | Check the error message details; contact support if persistent |
curl -X POST https://ezinvoice.pk/api/postinvoicedata \
-H "Authorization: Bearer YOUR_FBR_TOKEN" \
-H "Content-Type: application/json" \
-H "Accept: */*" \
-H "Accept-Language: en-US" \
-H "x-request-id: $(uuidgen)" \
-H "User-Agent: ezinvoice.pk/1.0" \
-d '{
"sellerNTNCNIC": "1234567-8",
"buyerNTNCNIC": "9876543-2",
"buyerBusinessName": "ABC Trading Co.",
"buyerAddress": "123 Main Street, Karachi",
"buyerRegistrationType": "Registered",
"buyerProvince": "Sindh",
"invoiceDate": "2025-06-12",
"invoiceNumber": "INV-001",
"invoiceRefNo": "REF-001",
"invoiceType": "Sale Invoice",
"items": [
{
"hsCode": "8471.3010",
"productDescription": "Laptop Computer",
"quantity": 2,
"uoM": "Nos",
"rate": "Standard Rate",
"valueSalesExcludingST": 200000.00,
"salesTaxApplicable": 36000.00,
"totalValues": 236000.00,
"discount": 0,
"saleType": "Goods at Standard Rate"
}
]
}'
Sandbox: Replace URL with https://ezinvoice.pk/api/postinvoicedata_sb
<?php
$url = 'https://ezinvoice.pk/api/postinvoicedata';
$token = 'YOUR_FBR_TOKEN';
$data = [
'sellerNTNCNIC' => '1234567-8',
'buyerNTNCNIC' => '9876543-2',
'buyerBusinessName' => 'ABC Trading Co.',
'buyerAddress' => '123 Main Street, Karachi',
'buyerRegistrationType' => 'Registered',
'buyerProvince' => 'Sindh',
'invoiceDate' => date('Y-m-d'),
'invoiceNumber' => 'INV-001',
'invoiceRefNo' => 'REF-001',
'invoiceType' => 'Sale Invoice',
'items' => [
[
'hsCode' => '8471.3010',
'productDescription' => 'Laptop Computer',
'quantity' => 2,
'uoM' => 'Nos',
'rate' => 'Standard Rate',
'valueSalesExcludingST' => 200000.00,
'salesTaxApplicable' => 36000.00,
'totalValues' => 236000.00,
'discount' => 0,
'saleType' => 'Goods at Standard Rate',
]
],
];
$ch = curl_init($url);
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
'Authorization: Bearer ' . $token,
'Content-Type: application/json',
'Accept: */*',
'Accept-Language: en-US',
'x-request-id: ' . uniqid(),
'User-Agent: ezinvoice.pk/1.0',
],
CURLOPT_POSTFIELDS => json_encode($data),
CURLOPT_RETURNTRANSFER => true,
]);
$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);
$result = json_decode($response, true);
print_r($result);
import requests
import uuid
import json
url = "https://ezinvoice.pk/api/postinvoicedata"
token = "YOUR_FBR_TOKEN"
payload = {
"sellerNTNCNIC": "1234567-8",
"buyerNTNCNIC": "9876543-2",
"buyerBusinessName": "ABC Trading Co.",
"buyerAddress": "123 Main Street, Karachi",
"buyerRegistrationType": "Registered",
"buyerProvince": "Sindh",
"invoiceDate": "2025-06-12",
"invoiceNumber": "INV-001",
"invoiceRefNo": "REF-001",
"invoiceType": "Sale Invoice",
"items": [
{
"hsCode": "8471.3010",
"productDescription": "Laptop Computer",
"quantity": 2,
"uoM": "Nos",
"rate": "Standard Rate",
"valueSalesExcludingST": 200000.00,
"salesTaxApplicable": 36000.00,
"totalValues": 236000.00,
"discount": 0,
"saleType": "Goods at Standard Rate",
}
]
}
headers = {
"Authorization": f"Bearer {token}",
"Content-Type": "application/json",
"Accept": "*/*",
"Accept-Language": "en-US",
"x-request-id": str(uuid.uuid4()),
"User-Agent": "ezinvoice.pk/1.0",
}
response = requests.post(url, json=payload, headers=headers)
print(response.status_code)
print(response.json())
// Using fetch API (Node.js or browser)
const url = 'https://ezinvoice.pk/api/postinvoicedata';
const token = 'YOUR_FBR_TOKEN';
const payload = {
sellerNTNCNIC: '1234567-8',
buyerNTNCNIC: '9876543-2',
buyerBusinessName: 'ABC Trading Co.',
buyerAddress: '123 Main Street, Karachi',
buyerRegistrationType: 'Registered',
buyerProvince: 'Sindh',
invoiceDate: '2025-06-12',
invoiceNumber: 'INV-001',
invoiceRefNo: 'REF-001',
invoiceType: 'Sale Invoice',
items: [
{
hsCode: '8471.3010',
productDescription: 'Laptop Computer',
quantity: 2,
uoM: 'Nos',
rate: 'Standard Rate',
valueSalesExcludingST: 200000.00,
salesTaxApplicable: 36000.00,
totalValues: 236000.00,
discount: 0,
saleType: 'Goods at Standard Rate',
},
],
};
fetch(url, {
method: 'POST',
headers: {
'Authorization': `Bearer ${token}`,
'Content-Type': 'application/json',
'Accept': '*/*',
'Accept-Language': 'en-US',
'x-request-id': crypto.randomUUID(),
'User-Agent': 'ezinvoice.pk/1.0',
},
body: JSON.stringify(payload),
})
.then((res) => res.json())
.then((data) => console.log(data))
.catch((err) => console.error(err));
Use /api/postinvoicedata_sb for development and testing. Only switch to production after all FBR compliance scenarios pass.
Ensure all required fields are present and correctly formatted. Validate HS codes, tax rates, and buyer information client-side before API calls.
Maintain audit logs of every API call, including request IDs, timestamps, and FBR invoice numbers for traceability.
Handle transient network failures with exponential backoff. Store failed invoices locally for retry.
Always send a unique x-request-id header for each request to enable request tracing and deduplication.
Ensure FBR tokens (sandbox and production) are correctly configured in the EZ Invoice company settings. Expired tokens cause submission failures.
This documentation is structured for optimal parsing by AI agents, LLMs, and coding assistants. Key AEO features:
llms-api.txt available at https://ezinvoice.pk/llms-api.txt for direct AI consumption