Module: SRB Integration v1.3.0
Integrate BIXCRM invoices with SRB Sindh Revenue Board POS (sandbox and production APIs via CURL).
How to use in BIXCRM (daily operations)
- Sign in to the admin area with a role that includes SRB Integration permissions.
- Open Srb Integration (sidebar) or search for SRB 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 SRB Integration section in the admin sidebar. Screens your staff may use (depending on role):
- API Settings
- Bulk Submit
- Settings
- SRB Audit Log
- SRB Report
Detailed guide — features, workflows, API & FAQ
Features
- Submit invoices to SRB (manual + auto-submit)
- Credit note submission with source invoice SRB reference
- Simulation mode for safe testing
- Encrypted API credentials at rest
- Custom field mapping (HS code, sale type, buyer SNTN)
- QR codes on invoice PDF / client view / public verify page
- SRB 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 → SRB Integration
- Open Setup → Settings → Integrations → SRB Integration
- Configure auto-submit, field mapping, retry, webhooks, and REST API
- Open SRB Integration → API Settings (or click Open SRB API settings on the settings tab)
- Set mode, environment, seller SNTN, POS ID, 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 SRB submissions is enabled. Webhook delivery also runs on cron.
Admin navigation
| Menu item | Permission | URL |
|---|---|---|
| ----------- | ------------ | ----- |
| Settings | settings | admin/settings?group=srb_integration |
| API Settings | settings | admin/srb_integration |
| Bulk Submit | send | admin/srb_integration/srb/bulk_submit |
| SRB Report | view_srb_report | admin/srb_integration/srb/report |
| Audit Log | view_srb_report | admin/srb_integration/srb/audit_log |
Bulk submit
SRB Integration → Bulk Submit lists invoices not yet sent to SRB (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 | /srb_integration/srb_rest | Service info |
| GET | /srb_integration/srb_rest/invoice_status/{id} | SRB status for invoice |
| POST | /srb_integration/srb_rest/invoice_submit/{id} | Submit single invoice |
| POST | /srb_integration/srb_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). Header: X-SRB-Integration-Signature (HMAC-SHA256).
Field mapping
| Setting | Source |
|---|---|
| --------- | -------- |
| HS code slug | Line item CF → catalog product CF → default |
| Sale type slug | Same as HS code |
| Buyer SNTN slug | Customer VAT → customer CF → unregistered default |
Credit notes
- Submit original invoice to SRB first
- Create credit note with applied credit to that invoice
- Use Send credit note to SRB on credit note preview
Auto-submit for credit notes supports cron/system-created documents (same as invoices).
SaaS multi-tenant
When nasbix_saas is active, tenant isolation is enforced via filters on:
srb_integration_company_idsrb_integration_settings_company_idsrb_integration_send_company_idsrb_integration_send_credit_note_company_idsrb_integration_report_company_idsrb_integration_verify_company_idsrb_integration_invoice_panel_company_idsrb_integration_client_invoice_company_idsrb_integration_invoice_pdf_company_idsrb_integration_credit_note_panel_company_id
Hooks
| Hook | Type | Purpose |
|---|---|---|
| ------ | ------ | --------- |
srb_integration_company_id | filter | Default tenant ID |
srb_integration_settings_company_id | filter | Settings page tenant |
srb_integration_send_company_id | filter | Invoice submit tenant |
srb_integration_send_credit_note_company_id | filter | Credit note submit tenant |
srb_integration_report_company_id | filter | Report / export tenant |
srb_integration_verify_company_id | filter | Public verify page tenant |
srb_integration_send_payload | filter | Final payload before POST |
srb_integration_invoice_payload | filter | Invoice payload |
srb_integration_di_payload | filter | Raw DI payload builder |
srb_integration_credit_note_payload | filter | Credit note payload |
srb_integration_parse_response | filter | Parse API response |
srb_integration_di_post_url | filter | Override POST URL |
srb_integration_di_validate_url | filter | Override validate URL |
srb_integration_item_hs_code | filter | Line item HS code |
srb_integration_credit_note_source_srb_number | filter | Source invoice SRB number |
srb_integration_after_submit | action | Fires after submit (webhooks) |
srb_integration_webhook_payload | filter | Outbound webhook body |
srb_integration_retry_delay_minutes | filter | Retry backoff schedule |
srb_integration_simulation_invoice_number | filter | Simulated SRB invoice number |
srb_integration_qr_verification_url | filter | QR verification URL |
srb_integration_before_invoice_added | filter | Pre-create invoice hook |
API configuration
Default gateway URLs (override in API Settings):
| Environment | POST URL |
|---|---|
| ------------- | ---------- |
| Sandbox | https://pos.srb.gos.pk/di_data/v1/di/postinvoicedata_sb |
| Production | https://pos.srb.gos.pk/di_data/v1/di/postinvoicedata |
Obtain production URLs and credentials from the [SRB POS portal](https://pos.srb.gos.pk/PoSRegistration/) after registering your POS stations.
Troubleshooting
| Issue | Check |
|---|---|
| ------- | ------- |
| No settings error | API key saved for tenant |
| HTTP 401 | Token + SRB credentials |
| Invalid endpoint | Custom URL must start with https:// |
| Credit note blocked | Source invoice SRB status = sent |
| Retries not running | Cron + retry enabled |
| Webhooks not firing | HTTPS URL + cron + subscribed events |
| REST API 403 | API enabled + valid Bearer key |
| Verify page shows raw keys | Module lang loads automatically |
Tests
php modules/srb_integration/tests/SrbLogicTest.php
Permissions
| Capability | Key | Used for |
|---|---|---|
| ------------ | ----- | ---------- |
| View | view | SRB panel on invoices |
| Send | send | Submit to SRB, bulk submit |
| Settings | settings | API config, test connection |
| View Report | view_srb_report | Report, audit log, exports |
Features
Integrate BIXCRM invoices with SRB Sindh Revenue Board POS (sandbox and production APIs via CURL).
- Submit invoices to SRB (manual + auto-submit)
- Credit note submission with source invoice SRB reference
- Simulation mode for safe testing
- Encrypted API credentials at rest
- Custom field mapping (HS code, sale type, buyer SNTN)
- QR codes on invoice PDF / client view / public verify page
- SRB 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 SRB 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 SRB 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 SRB Integration.
- Setup → Staff → Roles → assign SRB Integration permissions (view, create, edit, delete, approve, export, settings as needed).
- Open SRB 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.