UVS International · Pharmaceutical
Connecting ERP Sales Invoices to FBR IMS
Building a controlled, auditable invoice-submission workflow for UVS International
Upheld Solutions integrated Pakistan’s FBR Invoice Management System into UVS International’s Pharmaceutical ERP, creating a controlled workflow for transforming, validating, submitting and tracking digital invoices directly from the business application.
Case study overview
The integration is part of the ERP sales workflow rather than a separate invoicing utility. It connects the source transaction, tax configuration, external submission state and operator history in one application context.
The engineering challenge extended beyond making an HTTP request. Internal ERP data had to be transformed into the IMS contract, validated before transmission, protected against duplicate work and reconciled when a network outcome could not be known safely.
The challenge
Digital Invoicing Is More Than Sending JSON
The ERP’s internal invoice structure did not directly match the FBR IMS contract. Reliable submission also required the application to understand tax configuration, credentials, external identifiers, retries, duplicate protection and uncertain network outcomes.
- Sandbox and production configuration
- FBR BPOS/POS identification
- PCT/HS codes
- Product tax rates
- Automatic and manual submission
- Duplicate prevention
- Permanent request/response history
- Gateway faults and non-JSON responses
- Connection failures
- FBR invoice numbers
- QR verification values
Integration architecture
From ERP Transaction to Operator Visibility
The integration is designed as a complete financial workflow rather than a standalone API call.
- 01
ERP Transaction
- 02
Tax Data Validation
- 03
FBR Payload Transformation
- 04
Secure Submission
- 05
External Response
- 06
Persistence
- 07
Reconciliation
- 08
Operator Visibility
Submission workflow
- 01
Sale Invoice
The ERP sale invoice remains the source business transaction.
- 02
Submission Trigger
Automatic after commit or manually initiated by an operator.
- 03
Unique Background Job
Queued work is unique to the sale invoice.
- 04
ERP → FBR Transformation
Business data is converted into the IMS contract.
- 05
Local Validation
Predictable data and configuration failures stop locally.
- 06
Secure FBR IMS Request
The configured environment receives the authenticated request.
Accepted
Persist the accepted response, FBR invoice number and verification value.
Rejected
Persist the rejection details so the operator can correct an actionable failure.
Uncertain
Block unsafe retry until the actual remote state is reconciled.
Persist Complete Attempt
Display Status / FBR Number / History / QR
Data transformation
Translating Business Data Into the FBR Contract
A dedicated transformation layer converts ERP invoice data into the required IMS structure without exposing production identifiers in the public case study.
- Deterministic USIN
- Environment-specific BPOS ID
- Buyer name and phone
- Product barcode and name
- PCT/HS code
- Quantity and price
- Discount
- Tax rate and calculated tax
- Invoice totals
- Payment mode
- Invoice type
Line calculations are aggregated so sale value, discount, tax, quantity and bill amount remain internally consistent before submission.
Local validation
Reject Bad Data Before It Reaches the Government Gateway
Predictable failures are moved closer to the operator, producing actionable application errors instead of unnecessary external requests.
- Integration disabled
- Missing endpoint
- Missing bearer token
- Missing BPOS ID
- Missing customer
- Missing invoice items
- Invalid payment mode
- Missing PCT/HS code
- Invalid PCT/HS code
- Missing tax rate
- Zero quantity
- Negative quantity
Submission control
Automatic When Appropriate, Manual When Needed
The workflow supports automation without moving the external request inside the ERP transaction.
Automatic
When enabled, synchronization is queued only after the ERP transaction commits. The external request does not run before the ERP’s own transaction is safely committed.
Manual
Operators can initiate synchronization from the invoice interface and use controlled retry only when the recorded failure state permits it.
Operator control
Automation Without Removing Human Control
Administrators can enable or disable automatic invoice synchronization while retaining manual submission controls. This lets the business continue operating under controlled circumstances without changing application code.
Layered protection
Preventing the Same Invoice From Being Submitted Twice
Duplicate prevention is implemented at multiple layers because relying on a single UI button state is not sufficient for a financial integration.
Unique Queue Jobs
Prevents duplicate queued work for the same sale invoice.
Per-Invoice Lock
Protects concurrent posting attempts.
Existing-Submission Check
Recognizes invoices that have already been posted.
Unique FBR Invoice Index
Database integrity reinforces application-level protection.
Persistent USIN
Maintains a stable transaction identity.
Response Reconciliation
Recognizes previous accepted responses instead of blindly resubmitting.
Failure reconciliation
What If the Request Times Out?
A connection failure does not necessarily mean FBR rejected or never received the invoice. The remote system may have accepted the request even though the ERP never received the response. Treating that uncertainty as a normal failure could create a duplicate fiscal submission.
Do not immediately retry.
- 1
Mark as Uncertain
- 2
Block Unsafe Automatic Retry
- 3
Reconcile Against FBR Records/Portal
- 4
Determine Actual Submission State
- 5
Retry Only When Safe
Response handling
Normalizing External Responses Without Losing Evidence
Accepted IMS responses include the InvoiceNumber, success code 100 and the successful receipt. The application also retains HTTP status, gateway faults, empty or non-JSON responses, raw response bodies and application exceptions. Gateway code 900908 is retained when returned as part of compact diagnostic detail.
Audit trail
Every Submission Attempt Remains Traceable
Operators can review what the ERP sent, what came back, who initiated the action and the resulting state without relying on temporary application logs alone.
- Request payload
- Response payload
- Automatic/manual source
- Triggering user
- Application status
- FBR status code
- Error information
- FBR invoice number
- Submission timestamp
- Failure timestamp
Invoice visibility
Submission state stays on the sale invoice
- Current FBR status
- FBR invoice number
- Attempt history
- QR verification value/code
Credential security
Keeping Integration Credentials Out of Business-Managed Settings
FBR credentials were moved from database-managed settings into deployment environment configuration. Sandbox and production use separate endpoints, tokens and BPOS identifiers, and the production endpoint uses HTTPS.
A migration deliberately removed previously stored plaintext credentials. Actual credentials, endpoint secrets and token examples are never displayed.
Reusable client
Extracting the Integration Into a Reusable Laravel Client
marslankhalid/fbr-ims-laravel
Alongside the ERP-specific implementation, a reusable Laravel package has been developed for the FBR IMS contract.
- Sandbox/production configuration
- Bearer-authenticated client
- Typed Invoice object
- Typed InvoiceItem object
- Basic contract validation
- Normalized success responses
- Normalized gateway-fault responses
- Service-provider registration
- Laravel facade
- Publishable configuration
- PHP 8.1 support
- Laravel 9–12 support
The current UVS International ERP runs Laravel 8.83 and continues to use its application-level FBR services. The extracted package targets Laravel 9–12 and is not currently the ERP’s runtime integration client.
Engineering evolution
How the Integration Evolved
March 2026
Initial end-to-end integration
July 2026
Security and data-integrity hardening
July 2026
Legacy IMS contract alignment and improved diagnostics
July 2026
HTTPS production configuration
July 2026
Operator-controlled automatic synchronization
5
Application integration tests passed
3 / 11
Package tests / assertions passed
8
Relevant FBR-focused tests passed
These eight relevant tests do not represent the complete Pharmaceutical ERP test suite.
Outcome
A Controlled Digital-Invoicing Workflow Inside the ERP
The integration gives UVS International’s ERP an auditable workflow for preparing, validating, transmitting and tracking FBR invoice submissions without separating fiscal invoicing from the underlying sales transaction.
- Reduced manual FBR invoice entry
- Tax data validation before transmission
- Persistent visibility into every submission attempt
- Controlled automatic and manual synchronization
- Protection against duplicate submissions
- Safer handling of uncertain network outcomes
- Environment-isolated credentials and configuration
- Direct visibility of FBR submission state from the sale invoice
Delivery boundary
Current Scope Boundary
Database fields and source-invoice relationships have been prepared for sale-return FBR processing, but the complete credit-note/return submission workflow has not yet been implemented.
Platform
Pharmaceutical ERP
The FBR workflow is integrated into the wider sales and distribution environment rather than operating as an isolated invoicing utility.
Reliable external integrations
Integrating Your ERP With an External Business System?
Reliable integrations need more than an API request. Validation, security, retries, concurrency, auditability and failure recovery need to be designed into the workflow.