marslankhalid/fbr-ims-laravel

A Laravel client for Pakistan FBR IMS invoice web services.

0.1 2026-07-19 22:26 UTC

Requires

• php: ^8.1
• guzzlehttp/guzzle: ^7.5
• illuminate/contracts: ^9.0 || ^10.0 || ^11.0 || ^12.0
• illuminate/support: ^9.0 || ^10.0 || ^11.0 || ^12.0

Requires (Dev)

• phpunit/phpunit: ^9.6 || ^10.5 || ^11.0

MIT

• Arslan

• invoice
• laravel
• IMS
• pakistan
• fbr

Published on Packagist.org on 2026-07-19 22:28 UTC

README

A small Laravel package for posting invoices to Pakistan FBR's IMS invoice web service. It supports environment-specific endpoints and credentials, typed invoice objects, gateway-fault parsing, and the documented IMS success response.

This community package is not affiliated with or endorsed by FBR. Confirm endpoint, authentication, payload, and tax requirements with FBR before production use.

Requirements

• PHP 8.1+
• Laravel 9–12

Installation

composer require marslankhalid/fbr-ims-laravel
php artisan vendor:publish --tag=fbr-ims-config

Configure .env:

FBR_IMS_ENVIRONMENT=sandbox
FBR_SANDBOX_URL=https://esp.fbr.gov.pk:8244/FBR/v1/api/Live/PostData
FBR_IMS_SANDBOX_TOKEN=
FBR_IMS_SANDBOX_POS_ID=

FBR_PRODUCTION_URL=https://gw.fbr.gov.pk/imsp/v1/api/Live/PostData
FBR_IMS_PRODUCTION_TOKEN=
FBR_IMS_PRODUCTION_POS_ID=

Usage with arrays

use MarslanKhalid\FbrIms\Contracts\Client;

$response = app(Client::class)->post([
    'InvoiceNumber' => '',
    'POSID' => 110014,
    'USIN' => 'USIN0',
    'DateTime' => '2026-07-20 12:00:00',
    'BuyerName' => 'Buyer Name',
    'BuyerPhoneNumber' => '03001234567',
    'TotalBillAmount' => 117,
    'TotalQuantity' => 1,
    'TotalSaleValue' => 100,
    'TotalTaxCharged' => 17,
    'Discount' => 0,
    'FurtherTax' => 0,
    'PaymentMode' => 1,
    'RefUSIN' => null,
    'InvoiceType' => 1,
    'Items' => [[
        'ItemCode' => 'IT_1011',
        'ItemName' => 'Test Item',
        'PCTCode' => '11001010',
        'Quantity' => 1,
        'TaxRate' => 17,
        'SaleValue' => 100,
        'Discount' => 0,
        'TaxCharged' => 17,
        'FurtherTax' => 0,
        'TotalAmount' => 117,
        'InvoiceType' => 1,
        'RefUSIN' => null,
    ]],
]);

if ($response->successful()) {
    $invoiceNumber = $response->invoiceNumber;
} else {
    report("FBR error {$response->code}: {$response->message} {$response->description}");
}

Typed invoice objects

use MarslanKhalid\FbrIms\Data\Invoice;
use MarslanKhalid\FbrIms\Data\InvoiceItem;
use MarslanKhalid\FbrIms\Facades\FbrIms;

$item = new InvoiceItem(
    itemCode: 'IT_1011',
    itemName: 'Test Item',
    pctCode: '11001010',
    quantity: 1,
    taxRate: 17,
    saleValue: 100,
    discount: 0,
    taxCharged: 17,
    totalAmount: 117,
);

$invoice = new Invoice(
    posId: 110014,
    usin: 'USIN0',
    dateTime: now(),
    totalBillAmount: 117,
    totalQuantity: 1,
    totalSaleValue: 100,
    totalTaxCharged: 17,
    items: [$item],
);

$response = FbrIms::post($invoice);

Responses

Successful IMS responses such as the following are normalized:

{"InvoiceNumber":"192757FGNA32386557","Code":"100","Response":"Invoice received successfully"}

Gateway faults are preserved, including WSO2 code 900908 (Resource forbidden). Use $response->body and $response->rawBody for audit logging.

Security and idempotency

• Keep tokens in environment variables; never commit them.
• Use a unique USIN for each business invoice.
• Persist the request and complete response before retrying.
• If FBR returns code 100, store the returned invoice number and do not repost the invoice.
• A transport timeout is ambiguous: reconcile with FBR before retrying.

Testing

composer install
vendor/bin/phpunit

License

MIT

Contributing

Contributions are welcome. Read CONTRIBUTING.md for the development workflow and CODE_OF_CONDUCT.md before opening an issue or pull request.

Security vulnerabilities should be reported privately as described in SECURITY.md, not through public issues.