Module: FBR Integration v1.3.0
Integrate BIXCRM invoices with FBR (sandbox and production APIs via CURL).
How to use in BIXCRM (daily operations)
- Sign in to the admin area with a role that includes FBR Integration permissions.
- Open Fbr Integration (sidebar) or search for FBR Integration in the admin menu.
- Start on the Dashboard (if available) to see open tasks, pending approvals, and KPIs.
- Review Settings after upgrades — new options may need defaults for your company.
- Create or import master data first; most modules block transactions until masters exist.
- Run the main business flow (create → submit → approve → post/complete) using the screens listed in Admin menu below.
- Use Reports / Analytics screens to reconcile stock, finance, compliance, or SLA metrics.
- For integrations (API, EDI, gateways, tax), confirm credentials in Settings and monitor logs or webhook delivery screens.
- Train staff with role-based access — give approvers approve permissions only, operators create/edit on their area.
- If something fails overnight, check BIXCRM cron ran and open the module log / failed queue screen if present.
Admin menu — where to work
Open the FBR Integration section in the admin sidebar. Screens your staff may use (depending on role):
- Bulk Submit
- FBR Audit Log
- FBR Report
- Settings
Detailed guide — features, workflows, API & FAQ
Features
- Submit invoices to FBR (manual + auto-submit)
- Credit note submission with source invoice FBR reference
- Simulation mode for safe testing
- Encrypted API credentials at rest
- Custom field mapping (HS code, sale type, buyer NTN)
- QR codes on invoice PDF / client view
- FBR report (CSV / PDF export)
- Retry queue with exponential backoff (cron)
- Test connection button (validate endpoint)
- Audit log of submit / retry / test actions
- Bulk submit admin UI for unsent invoices
- Webhooks (HTTPS + HMAC) on submit success/failure
- External REST API for third-party integrations
- Configurable API URLs per environment
- Urdu + Arabic language packs
- SaaS multi-tenant hooks (
nasbix_saas)
Setup
- Activate module: Setup → Modules → FBR Integration
- Open Setup → Settings → Integrations → FBR Integration
- Configure auto-submit, field mapping, retry, webhooks, and REST API
- Open FBR Integration → API settings
- Set mode, environment, seller NTN, API key (and optional custom URLs)
- Click Test connection
- Start in Simulation, then switch to Live
Cron (required for retries & webhooks)
Ensure BIXCRM cron runs on schedule. Failed live submissions retry when Retry failed FBR submissions is enabled. Webhook delivery also runs on cron.
Bulk submit
FBR Integration → Bulk Submit lists invoices not yet sent to FBR (excludes drafts). Select invoices and submit in batch (max 50 per request).
External REST API
Enable in settings and set an API key. Endpoints (site URL, not admin):
| Method | Path | Description |
|---|---|---|
| -------- | ------ | ------------- |
| GET | /fbr_integration/fbr_rest | Service info |
| GET | /fbr_integration/fbr_rest/invoice_status/{id} | FBR status for invoice |
| POST | /fbr_integration/fbr_rest/invoice_submit/{id} | Submit single invoice |
| POST | /fbr_integration/fbr_rest/bulk_submit | JSON body: {"invoice_ids":[1,2,3]} |
Authenticate: Authorization: Bearer {api_key} or ?api_key=
Webhooks
Configure an HTTPS URL and optional signing secret. Events: submit.success, submit.failed. Payload includes event, company_id, timestamp, and data (submission context).
Field mapping
| Setting | Source |
|---|---|
| --------- | -------- |
| HS code slug | Line item CF → catalog product CF → default |
| Sale type slug | Same as HS code |
| Buyer NTN slug | Customer VAT → customer CF → unregistered default |
Credit notes
- Submit original invoice to FBR first
- Create credit note with applied credit to that invoice
- Use Send credit note to FBR on credit note preview
Hooks
| Hook | Type |
|---|---|
| ------ | ------ |
fbr_integration_send_payload | filter |
fbr_integration_parse_response | filter |
fbr_integration_item_hs_code | filter |
fbr_integration_credit_note_source_fbr_number | filter |
fbr_integration_after_submit | action |
fbr_integration_webhook_payload | filter |
fbr_integration_retry_delay_minutes | filter |
Troubleshooting
| Issue | Check |
|---|---|
| ------- | ------- |
| No settings error | API key saved for tenant |
| HTTP 401 | Token + FBR IP whitelist |
| Credit note blocked | Source invoice FBR status = sent |
| Retries not running | Cron + retry enabled |
| Webhooks not firing | HTTPS URL + cron + subscribed events |
| REST API 403 | API enabled + valid Bearer key |
Tests
php modules/fbr_integration/tests/FbrLogicTest.php
Features
Integrate BIXCRM invoices with FBR (sandbox and production APIs via CURL).
- Submit invoices to FBR (manual + auto-submit)
- Credit note submission with source invoice FBR reference
- Simulation mode for safe testing
- Encrypted API credentials at rest
- Custom field mapping (HS code, sale type, buyer NTN)
- QR codes on invoice PDF / client view
- FBR report (CSV / PDF export)
- **Retry queue** with exponential backoff (cron)
- **Test connection** button (validate endpoint)
- **Audit log** of submit / retry / test actions
- **Bulk submit** admin UI for unsent invoices
- **Webhooks** (HTTPS + HMAC) on submit success/failure
- **External REST API** for third-party integrations
- **Configurable API URLs** per environment
- **Urdu + Arabic** language packs
- SaaS multi-tenant hooks (`nasbix_saas`)
Permissions
Granular staff capabilities are registered on activation. Assign them under Setup → Staff → Roles for the FBR Integration capability group.
Typical capabilities include view, create, edit, delete, plus module-specific actions (approve, export, settings, API access).
Cron Jobs
Background tasks (if enabled) run through BIXCRM's main cron. Example crontab (every 5 minutes):
* * * * * php /path/to/bixcrm/index.php cron/index > /dev/null 2>&1
Check module settings for scheduled jobs (alerts, sync, reports, retention).
After activation — configuration checklist
- Go to Setup → Modules and activate FBR Integration.
- If prompted, click Upgrade Database or reload admin — migrations run automatically.
- Assign permissions under Setup → Staff → Roles.
- Open the module menu and configure settings.
- BIXCRM 3.0+
- PHP 7.4+ (8.1+ recommended)
- MySQL 5.7+ / MariaDB 10.3+ (InnoDB)
- PHP extensions: mysqli, json, mbstring, curl, fileinfo
One-time setup (first time only)
- Setup → Modules → activate FBR Integration.
- Setup → Staff → Roles → assign FBR Integration permissions (view, create, edit, delete, approve, export, settings as needed).
- Open FBR Integration → Settings and complete company defaults, prefixes, integrations, and notification options.
- Create master data (warehouses, products, templates, accounts, routes, etc.) before processing live transactions.
- Enable BIXCRM cron (
php /path/to/bixcrm/index.php cron/index) for sync, retries, alerts, and scheduled jobs. - Optionally enable REST API / webhooks in module settings if you integrate external systems.
BIXCRM Knowledge Base — usage guide generated from module README and documentation.