Download the PHP package fbr/digital-invoicing without Composer

FBR Digital Invoicing Laravel Package

A comprehensive Laravel package for integrating with Pakistan's Federal Board of Revenue (FBR) Digital Invoicing System API v1.12.

Features

• ✅ Complete FBR API Integration - Full support for invoice submission and validation
• ✅ Reference Data APIs - Access to provinces, UOM, HS codes, SRO items, and more
• ✅ Multiple Environments - Sandbox and production environment support
• ✅ Fluent Builder Pattern - Easy-to-use invoice and item builders
• ✅ Database Models - Laravel Eloquent models with relationships
• ✅ Background Processing - Queue-based invoice submission with retry logic
• ✅ Comprehensive Validation - Built-in validation for all invoice data
• ✅ Error Handling - Detailed error reporting and logging
• ✅ QR Code Helpers - Generate QR codes as per FBR requirements
• ✅ Artisan Commands - Sync reference data and manage invoices
• ✅ 28 Scenarios Support - All FBR sandbox testing scenarios
• ✅ STATL Integration - Registration status validation
• ✅ Facade Support - Clean Laravel facade interface

Installation

Install the package via Composer:

Publish the configuration file:

Publish and run the migrations:

Configuration

Add the following to your .env file:

The configuration file config/fbr-digital-invoicing.php contains all available options:

Quick Start

Basic Invoice Creation and Submission

Validation Before Submission

Using Database Models

Supported Scenarios

The package supports all 28 official FBR sandbox testing scenarios based on "DI Scenarios Description for Sandbox Testing" v1.11:

Manufacturing & Standard Sales (SN001-SN009)

SN001: Sale of Standard Rate Goods to Registered Buyers

• Sale of goods subject to the standard sales tax rate made to sales tax registered buyers
• Buyers can usually claim input tax credits
• Rate: 18% | Buyer: Registered | Example: General manufacturing sales

SN002: Sale of Standard Rate Goods to Unregistered Buyers

• Standard rate goods sold to buyers who are not registered for sales tax (B2C sales)
• Rate: 18% | Buyer: Unregistered | Example: Retail sales to consumers

SN003: Sale of Steel (Melted and Re-Rolled) - Billets, Ingots and Long Bars

• Steel sector governed by strict traceability and sector-specific rules
• Rate: 18% | Buyer: Unregistered | Example: Steel manufacturing

SN004: Sale of Steel Scrap by Ship Breakers

• Ship breakers dismantle old ships and recover scrap steel with special tax treatment
• Rate: 18% | Buyer: Unregistered | Example: Ship breaking industry

SN005: Sales of Reduced Rate Goods (Eighth Schedule)

• Goods taxed at reduced sales tax rate to encourage affordability
• Rate: 1% | Buyer: Unregistered | Example: Essential commodities, basic food items

SN006: Sale of Exempt Goods (Sixth Schedule)

• Goods listed in the Sixth Schedule are exempt from sales tax
• Rate: Exempt | Buyer: Registered | Example: Agricultural products, medicines

SN007: Sale Of Zero-Rated Goods (Fifth Schedule)

• Zero-rated goods charged at 0% but seller can claim input tax credits
• Rate: 0% | Buyer: Unregistered | Example: Exported goods

SN008: Sale of 3rd Schedule Goods

• Items subject to sales tax based on printed retail price rather than transaction value
• Rate: 18% | Buyer: Unregistered | Example: Branded consumer products

SN009: Purchase From Registered Cotton Ginners

• Purchases from registered cotton ginners, subject to specific cotton trade taxation rules
• Rate: 18% | Buyer: Registered | Example: Cotton industry trade

Services & Specialized Industries (SN010-SN019)

SN010: Sale Of Telecom Services by Mobile Operators

• Mobile operators providing telecom services (calls, data, SMS)
• Rate: 17% | Buyer: Unregistered | Example: Telecom services

SN011: Sale of Steel through Toll Manufacturing - Billets, Ingots and Long Bars

• Third-party processing raw steel into finished products
• Rate: 18% | Buyer: Unregistered | Example: Steel toll manufacturing

SN012: Sale Of Petroleum Products

• Petroleum products with distinct sales tax rates or federal excise duties
• Rate: 1.43% | Buyer: Unregistered | Example: Petrol, diesel, lubricants

SN013: Sale Of Electricity to Retailers

• Selling electricity to retailers who distribute to end consumers
• Rate: 5% | Buyer: Unregistered | Example: Power distribution

SN014: Sale of Gas to CNG Stations

• Natural gas sold to CNG filling stations with special tax treatment
• Rate: 18% | Buyer: Unregistered | Example: CNG supply

SN015: Sale of Mobile Phones

• Sales of mobile handsets with additional duties or regulatory charges
• Rate: 18% | Buyer: Unregistered | Example: Mobile phone sales

SN016: Processing / Conversion of Goods

• Services where raw materials are converted into finished products
• Rate: 5% | Buyer: Unregistered | Example: Manufacturing services

SN017: Sale of Goods Where FED Is Charged in ST Mode

• Federal Excise Duty collected through the sales tax system
• Rate: 8% | Buyer: Unregistered | Example: FED-applicable goods

SN018: Sale Of Services Where FED Is Charged in ST Mode

• Services (advertisement, franchise, insurance) liable to FED via sales tax framework
• Rate: 8% | Buyer: Unregistered | Example: Advertisement services

SN019: Sale of Services (as per ICT Ordinance)

• IT services taxed under ICT ordinance with variations in rates or exemptions
• Rate: 5% | Buyer: Unregistered | Example: Software development, IT consultancy

Specialized Products & Retail (SN020-SN028)

SN020: Sale of Electric Vehicles

• Electric vehicles incentivized through reduced sales tax rates
• Rate: 1% | Buyer: Unregistered | Example: EV sales

SN021: Sale of Cement /Concrete Block

• Cement and concrete blocks with strict regulation due to environmental impact
• Rate: Rs.3 per unit | Buyer: Unregistered | Example: Construction materials

SN022: Sale of Potassium Chlorate

• Sensitive chemical subject to fixed tax per kilogram rather than value
• Rate: 18% + Rs.60 per kg | Buyer: Unregistered | Example: Chemical manufacturing

SN023: Sale of CNG

• Compressed Natural Gas with regulated pricing and specific tax treatments
• Rate: Rs.200 per unit | Buyer: Unregistered | Example: CNG stations

SN024: Sale Of Goods Listed in SRO 297(1)/2023

• Specific goods subject to reduced, conditional, or fixed-rate taxation
• Rate: 25% | Buyer: Unregistered | Example: Solar equipment, medical devices

SN025: Drugs Sold at Fixed ST Rate Under Serial 81 Of Eighth Schedule Table 1

• Pharmaceutical products at fixed sales tax rate to make medicines affordable
• Rate: 0% | Buyer: Unregistered | Example: Essential medicines

SN026: Sale Of Goods at Standard Rate to End Consumers by Retailers

• Retailers selling taxable goods directly to end consumers
• Rate: 18% | Buyer: Registered | Example: Retail sales

SN027: Sale Of 3rd Schedule Goods to End Consumers by Retailers

• Retailers selling 3rd Schedule goods based on maximum retail price (MRP)
• Rate: 18% | Buyer: Registered | Example: FMCG retail

SN028: Sale of Goods at Reduced Rate to End Consumers by Retailers

• Essential goods at reduced tax rate to keep vital products affordable
• Rate: 1% | Buyer: Registered | Example: Baby milk, books

Using Scenarios in Code

Reference Data APIs

Access FBR reference data easily:

Artisan Commands

Sync Reference Data

Available sync types:

• provinces - Province codes
• uom - Unit of measurement codes
• doctypes - Document type codes
• hscodes - Harmonized system codes
• sroitems - SRO item codes
• transtypes - Transaction type codes
• all - All reference data (default)

Queue Configuration

For background processing, configure your queues:

Run queue worker:

QR Code Generation

Generate QR codes as per FBR requirements:

Error Handling

The package provides comprehensive error handling:

Database Models

Invoice Model

InvoiceItem Model

Testing

The package includes comprehensive tests:

Example Integration

See the examples/basic-usage.php file for comprehensive usage examples covering:

1. Basic invoice creation and submission
2. Validation before submission
3. Using database models and background jobs
4. Fetching reference data
5. Creating scenario-based invoices
6. Checking registration status

Error Codes

The package handles all FBR error codes as documented in the API specification:

Sales Error Codes (0001-0300, 0401-0402)

Purchase Error Codes (0156-0177)

Common error codes:

• 0001 - Seller not registered for sales tax
• 0002 - Invalid Buyer Registration No or NTN
• 0005 - Invalid date format
• 0052 - Invalid HS Code
• 0401 - Unauthorized seller access
• 0402 - Unauthorized buyer access

API Rate Limiting

The package includes built-in retry logic with exponential backoff:

• Timeout: 30 seconds (configurable)
• Retry Attempts: 3 (configurable)
• Backoff: Progressive delay between retries
• Server Errors: Automatically retried
• Client Errors: Not retried (4xx status codes)

Logging

All API interactions are logged when enabled:

Log entries include:

• Request/response details
• Error information
• Performance metrics
• Retry attempts

Production Considerations

1. Environment Configuration:

2. Queue Workers: Set up supervised queue workers
3. Monitoring: Monitor queue jobs and failed jobs
4. Caching: Reference data is cached for 30 days by default
5. Logging: Review logs regularly for errors
6. Rate Limiting: Respect FBR API rate limits

Security

• Never commit your bearer token to version control
• Use environment variables for all sensitive configuration
• Regularly rotate your bearer token (5-year validity)
• Monitor API usage and unauthorized access attempts
• Follow Laravel security best practices

Contributing

Please see CONTRIBUTING for details.

Security Vulnerabilities

Please review our security policy on how to report security vulnerabilities.

Changelog

Please see CHANGELOG for more information on what has changed recently.

Credits

• Inayat Ullah
• All Contributors

License

The MIT License (MIT). Please see License File for more information.

Support

• 📧 Email: [email protected]
• 📖 Documentation: Full Documentation
• 🐛 Issues: GitHub Issues
• 💬 Discussions: GitHub Discussions

Disclaimer: This package is not officially affiliated with FBR Pakistan. It is a third-party integration built according to the official FBR Digital Invoicing API specification v1.12.