FBR Digital Invoice API Integration: Developer Guide for Pakistani Software Companies

FBR Digital Invoice API Overview

FBR's Digital Invoice API allows businesses and software companies to integrate their systems directly with FBR's central invoicing platform. This RESTful API supports real-time invoice submission, validation, and verification. This guide covers everything developers need to know to build a successful integration.

API Endpoints

Base URLs

• Sandbox: https://gw.fbr.gov.pk/di_data/v1/di/postinvoicedata_sb
• Production: https://gw.fbr.gov.pk/di_data/v1/di/postinvoicedata

Available Endpoints

• POST /postinvoicedata: Submit a new invoice
• POST /validateinvoicedata: Validate invoice without posting
• GET /HS_UOM: Get Units of Measure for HS codes
• GET /itemdesccode: Get HS code listing
• GET /transtypecode: Get transaction types
• GET /uom: Get all Units of Measure
• GET /SroSchedule: Get SRO schedule rates
• GET /provinces: Get province listing

Authentication

All API requests require Bearer token authentication:

Authorization: Bearer YOUR_API_TOKEN
Content-Type: application/json

Obtain your tokens from the FBR IRIS Portal under API Integration settings. Sandbox and production use separate tokens.

Invoice Payload Structure

The invoice submission payload must include:

{
  "InvoiceNumber": "",
  "POSID": 0,
  "USIN": "unique-system-identifier",
  "DateTime": "2026-04-09 14:30:00",
  "BuyerNTN": "1234567",
  "BuyerCNIC": "",
  "BuyerName": "Buyer Company Name",
  "BuyerPhoneNumber": "",
  "TotalBillAmount": 100000,
  "TotalQuantity": 100,
  "TotalSaleValue": 84746,
  "TotalTaxCharged": 15254,
  "Discount": 0,
  "FurtherTax": 0,
  "PaymentMode": 1,
  "RefUSIN": "",
  "InvoiceType": 1,
  "Items": [...]
}

Item Structure

{
  "ItemCode": "5208.1100",
  "ItemName": "Cotton Fabric - Plain Weave",
  "Quantity": 100,
  "PCTCode": "5208.1100",
  "TaxRate": 18,
  "SaleValue": 84746,
  "TotalAmount": 100000,
  "TaxCharged": 15254,
  "Discount": 0,
  "FurtherTax": 0,
  "InvoiceType": 1,
  "RefUSIN": ""
}

Response Handling

Success Response

A successful submission returns the FBR Invoice Number:

{
  "invoiceNumber": "1234567DIAEXYZ123456",
  "dated": "2026-04-09 14:30:15",
  "validationResponse": {
    "status": "Valid",
    "statusCode": "00"
  }
}

Error Response

Validation errors return detailed messages per item:

{
  "validationResponse": {
    "status": "Invalid",
    "statusCode": "01",
    "error": "Description of error"
  }
}

Best Practices for Integration

1. Handle Timeouts Properly

FBR's API can be slow during peak hours. Set your CURL timeout to at least 300 seconds. Critical: if a request times out, do not automatically retry. FBR may have processed the invoice. Mark the invoice as failed and prompt the user to verify on FBR portal before retrying.

2. Implement Idempotency

Use unique USIN values for each invoice. Before retrying a submission, check if the invoice has already received an FBR number. FBR does not reject duplicate submissions — it assigns new numbers.

3. Test Thoroughly in Sandbox

FBR's sandbox environment mirrors production behavior. Test all scenarios including edge cases, validation errors, and timeout handling before going live.

4. Log Everything

Log complete request and response payloads for every API call. This is essential for debugging, compliance audits, and dispute resolution.

5. Queue-Based Processing

Use a job queue for API submissions rather than synchronous calls. This improves user experience and allows proper error handling and monitoring.

Common API Errors

• Invalid HS Code: The PCT code doesn't exist in FBR's database
• Invalid NTN: Buyer NTN is not registered with FBR
• Amount Mismatch: Total doesn't match sum of items
• Token Expired: Generate a new API token from IRIS portal
• Rate Limited: Too many requests — implement exponential backoff

Using DigitalInvoices.pk Instead

Building your own FBR integration is complex and requires ongoing maintenance as FBR updates their API. DigitalInvoices.pk provides a ready-made solution with:

• Pre-built FBR API integration with all error handling
• Automatic timeout and retry management
• Multi-company support from a single dashboard
• Regular updates as FBR changes their API

Conclusion

FBR's Digital Invoice API is well-documented but requires careful implementation, especially around timeout handling and idempotency. Whether you build your own integration or use a managed solution like DigitalInvoices.pk, ensure your implementation is robust enough to handle real-world network conditions.