FBR Digital Invoicing API Documentation

Complete developer guide for integrating FBR e-invoicing via EZ Invoice REST API endpoints. For ERP vendors, software houses, POS integrators, and AI agents.

Base URL
https://ezinvoice.pk/api
Authentication
Bearer Token
Format
JSON
Version
v1

Overview

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:

Sandbox Mode

Use for development, testing, and FBR compliance scenario validation. Uses sandbox FBR tokens configured per company.

Endpoint: postinvoicedata_sb
Production Mode

Use for submitting live invoices to FBR. Requires valid production tokens from the FBR IRIS portal.

Endpoint: postinvoicedata

Authentication & Headers

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.

Required HTTP Headers
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
Important: The seller is identified by 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.

API Endpoints

POST /api/postinvoicedata Production

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.

Description

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.

Request Body (JSON)
{
  "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
    }
  ]
}
Success Response (200)
{
  "validationResponse": {
    "status": "Valid",
    "message": "Invoice validated successfully"
  },
  "invoiceNumber": "FBR-INV-000123456",
  ...
}
Error Response (422 / 404 / 500)
{
  "success": false,
  "message": "Seller not found. No company matches the provided NTN/CNIC."
}
POST /api/postinvoicedata_sb Sandbox

Submit an invoice to the FBR Sandbox environment for testing and compliance scenario validation. The request format is identical to the production endpoint.

Differences from Production
  • Uses the company's sandbox token (stored as iris_sb_token)
  • FBR endpoint: https://gw.fbr.gov.pk/di_data/v1/di/postinvoicedata_sb
  • Intended for FBR compliance scenario testing before going live
GET /api/scenarios Public

Retrieve all active sandbox scenarios available for FBR compliance testing.

Response
[
  {
    "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
  }
]
GET /api/bank-accounts/{companyId} Public

Retrieve all active bank accounts for a given company ID.

Path Parameters
ParameterTypeDescription
companyIdIntegerThe ID of the company
Response
[
  {
    "id": 1,
    "company_id": 5,
    "bank_name": "Habib Bank Limited",
    "account_title": "ABC Trading Co.",
    "account_number": "1234567890",
    "iban": "PK36HABB001234567890",
    "active": 1
  }
]

Invoice Request Body Reference

Complete reference of all fields accepted by the invoice submission endpoints.

Top-Level Fields
Field Type Required Description
sellerNTNCNICStringYesSeller's NTN (7 digits) or CNIC number. Used to identify the company and its FBR token.
buyerNTNCNICStringNoBuyer's NTN or CNIC. If provided, used to find or create a buyer record.
buyerBusinessNameStringNoBuyer's business name. Defaults to "Unknown Buyer".
buyerAddressStringNoBuyer's address.
buyerRegistrationTypeStringNoRegistration type. Defaults to "Registered".
buyerProvinceStringNoBuyer's province name (e.g., "Sindh", "Punjab").
invoiceDateString (Date)NoInvoice date in Y-m-d format. Defaults to today.
invoiceNumberStringNoUser-defined invoice reference number.
invoiceRefNoStringNoAdditional invoice reference.
invoiceTypeStringNoType of invoice. Defaults to "Sale Invoice".
ReasonStringNoDR/CR note reason (for debit/credit notes).
itemsArrayNoArray of invoice line items.
Item-Level Fields
Field Type Required Description
hsCodeStringNoHarmonized System code for the product.
productDescriptionStringNoDescription of the product/service.
quantityNumberNoQuantity of items. Defaults to 0.
uoMStringNoUnit of Measurement (e.g., "Nos", "Kg", "Ltr").
rateStringNoTax rate description (e.g., "Standard Rate", "Exempt").
saleTypeStringNoSale type matching a sandbox scenario (e.g., "Goods at Standard Rate").
valueSalesExcludingSTNumberNoValue excluding sales tax.
salesTaxApplicableNumberNoSales tax amount applicable.
totalValuesNumberNoTotal value including tax.
discountNumberNoDiscount amount. Defaults to 0.
sroScheduleNoStringNoSRO Schedule number description.
sroItemSerialNoStringNoSRO Item serial number description.
salesTaxWithheldAtSourceNumberNoSales tax withheld at source flag/amount.
extraTaxNumberNoExtra tax amount.
furtherTaxNumberNoFurther tax amount.
fedPayableNumberNoFederal Excise Duty payable.
fixedNotifiedValueOrRetailPriceNumberNoFixed notified value or retail price.

Response Format

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.
Stored Invoice Status Values

Each submitted invoice is stored locally with one of these statuses:

Error Handling

Common Errors & Solutions
ErrorCauseSolution
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

Code Examples

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));

Best Practices

Always Test in Sandbox First

Use /api/postinvoicedata_sb for development and testing. Only switch to production after all FBR compliance scenarios pass.

Validate Before Submitting

Ensure all required fields are present and correctly formatted. Validate HS codes, tax rates, and buyer information client-side before API calls.

Log All Requests & Responses

Maintain audit logs of every API call, including request IDs, timestamps, and FBR invoice numbers for traceability.

Implement Retry Logic

Handle transient network failures with exponential backoff. Store failed invoices locally for retry.

Use Unique Request IDs

Always send a unique x-request-id header for each request to enable request tracing and deduplication.

Keep Company Tokens Updated

Ensure FBR tokens (sandbox and production) are correctly configured in the EZ Invoice company settings. Expired tokens cause submission failures.

AI Agent & LLM Integration Notes

This documentation is structured for optimal parsing by AI agents, LLMs, and coding assistants. Key AEO features:

  • JSON-LD TechArticle and APIReference structured data for schema-aware AI crawlers
  • Clear hierarchical headings (h2/h3/h4/h5/h6) for semantic content extraction
  • Canonical URL for content deduplication across AI knowledge bases
  • Comprehensive llms-api.txt available at https://ezinvoice.pk/llms-api.txt for direct AI consumption
  • Machine-readable JSON request and response examples in every code block
  • Keyword-optimized meta tags for AI search engine discovery