Search Knowledge Base Articles

Mobile SFA — Overview & module guide

Module: Mobile SFA v1.5.0

Mobile Sales Force Automation for field sales reps — territories, routes, visits, orders, and collections via REST API

Screen-by-screen guides (each tab explained)

Click a menu item below for step-by-step instructions on that Mobile SFA screen:

How to use in BIXCRM (daily operations)

Sign in to the admin area with a role that includes Mobile SFA permissions.
Open Mobile Sfa (sidebar) or search for Mobile SFA 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 Mobile SFA section in the admin sidebar. Screens your staff may use (depending on role):

API Keys
Collections
Dashboard
Executive Reports
Mobile Devices
Orders
Routes & Beats
Sales Reps
Settings
SFA
Territories
Visits
Webhooks

Detailed guide — features, workflows, API & FAQ

Phase 1 (Complete) — Foundation

Sales rep profiles linked to BIXCRM staff
Territory management with client assignment
Mobile device registration & approval
REST API for mobile app authentication
API keys for integration partners
Admin dashboard, permissions, audit logs

Phase 2 (Complete) — Visits & Check-In

Customer visit check-in/check-out with GPS
Visit types: sales call, delivery, collection, survey
Geofence validation against client coordinates
Photo attachments (base64 or multipart)
Admin: visit list, map view, rep activity report
Visit REST API endpoints

Phase 3 (Complete) — Beat & Route Planning

Daily beat/route plans per sales rep
Ordered customer stops with planned times
Reusable weekly route templates
Route compliance: planned vs actual visit matching
Admin: route list, create/edit, templates, compliance report
Optional sync to Distributors & Wholesalers dw_routes
Route REST API endpoints

Phase 4 (Complete) — Mobile Order Taking

Mobile order capture with line items
Product catalog API (BIXCRM items + optional DW pricing)
Order workflow: Draft → Submitted → Synced
Sync to BIXCRM invoice or estimate
Admin: order list, detail, manual sync
Order REST API endpoints

Phase 5 (Complete) — Collections & Payments

Field payment recording with multiple payment modes
Customer outstanding balance & unpaid invoices API
Auto/manual sync to BIXCRM invoice payments
Collection receipt PDF generation
Accounting Pro integration via payment hooks
Collection REST API endpoints

Phase 6 (Complete) — Offline Sync & Enterprise

Offline batch sync (POST /sync/batch) with idempotent client_ref
Delta sync bundle (GET /sync/pull?since=)
Push notifications (FCM) + route stop reminders via cron
Inventory Management stock API integration
Distributors van stock API (driver staff link)
Executive reports: rep productivity, territory coverage, route compliance
Webhooks: visit.completed, order.synced, collection.recorded/synced

Mobile API

Base URL: {your-site}/mobile_sfa/api

Login

POST /mobile_sfa/api/auth/login
Content-Type: application/json

{
  "employee_code": "REP-0001",
  "pin": "1234",
  "device_uuid": "unique-device-id",
  "platform": "android",
  "app_version": "1.0.0"
}

Response includes token — use as Authorization: Bearer {token} for subsequent requests.

Endpoints (Phase 1)

Method	Endpoint	Auth	Description
--------	----------	------	-------------
GET	`/mobile_sfa/api`	—	API discovery
POST	`/mobile_sfa/api/auth/login`	—	Sales rep login
POST	`/mobile_sfa/api/auth/logout`	Session	Logout
GET	`/mobile_sfa/api/profile`	Session	Rep profile
GET	`/mobile_sfa/api/territories`	Token	Assigned territories
GET	`/mobile_sfa/api/customers`	Session	Territory customers
GET	`/mobile_sfa/api/customers/{id}`	Session	Single customer
POST	`/mobile_sfa/api/devices/register`	Session	Register device
GET	`/mobile_sfa/api/sync/status`	Token	Feature flags

Visits (Phase 2)

Method	Endpoint	Auth	Description
--------	----------	------	-------------
GET	`/mobile_sfa/api/visits`	Session	Visit history (filters: date_from, date_to, status)
GET	`/mobile_sfa/api/visits/active`	Session	Current open check-in
POST	`/mobile_sfa/api/visits/check-in`	Session	Start visit
POST	`/mobile_sfa/api/visits/check-out`	Session	End visit
GET	`/mobile_sfa/api/visits/{id}`	Session	Visit detail + photos
POST	`/mobile_sfa/api/visits/{id}/photos`	Session	Upload photo
POST	`/mobile_sfa/api/visits/{id}/cancel`	Session	Cancel open visit

Routes (Phase 3)

Method	Endpoint	Auth	Description
--------	----------	------	-------------
GET	`/mobile_sfa/api/routes`	Session	Route list (filters: date_from, date_to, status)
GET	`/mobile_sfa/api/routes/today`	Session	Today's beat plan with stops
GET	`/mobile_sfa/api/routes/{id}`	Session	Route detail + stops + compliance
POST	`/mobile_sfa/api/routes/stops/{id}/skip`	Session	Skip a planned stop

Orders (Phase 4)

Method	Endpoint	Auth	Description
--------	----------	------	-------------
GET	`/mobile_sfa/api/products`	Session	Product catalog (client_id for DW pricing)
GET	`/mobile_sfa/api/orders`	Session	Order history
POST	`/mobile_sfa/api/orders/create`	Session	Create draft order
POST	`/mobile_sfa/api/orders/update`	Session	Update draft order
POST	`/mobile_sfa/api/orders/{id}/submit`	Session	Submit order
POST	`/mobile_sfa/api/orders/{id}/cancel`	Session	Cancel order
GET	`/mobile_sfa/api/orders/{id}`	Session	Order detail + lines

Collections (Phase 5)

Method	Endpoint	Auth	Description
--------	----------	------	-------------
GET	`/mobile_sfa/api/customers/{id}/outstanding`	Session	Unpaid invoices & balance
GET	`/mobile_sfa/api/collections`	Session	Collection history
POST	`/mobile_sfa/api/collections/record`	Session	Record field collection
GET	`/mobile_sfa/api/collections/{id}`	Session	Collection detail
GET	`/mobile_sfa/api/collections/{id}/receipt`	Session	Receipt PDF
POST	`/mobile_sfa/api/collections/{id}/cancel`	Session	Cancel collection

Check-in example:

POST /mobile_sfa/api/visits/check-in
Authorization: Bearer {token}
Content-Type: application/json

{
  "client_id": 12,
  "visit_type": "sales_call",
  "lat": 24.8607,
  "lng": 67.0011,
  "notes": "Met with store manager"
}

Permissions

Feature	Capabilities
---------	-------------
Dashboard	view
Sales Reps	view, create, edit, delete
Territories	view, create, edit, delete
Devices	view, edit, delete
Visits	view, delete
Routes	view, create, edit, delete
Orders	view, edit (sync), delete
Collections	view, edit (sync), delete
Executive Reports	view
Webhooks	view, create, edit, delete
API Keys	view, create, delete
Settings	view, edit

Roadmap

All 6 phases complete. See [docs/ROADMAP.md](docs/ROADMAP.md) for full history.

Design Principles

No core changes — hooks + module folder only
Uses BIXCRM clients — tblclients for customer master data
Optional integrations — Distributors & Wholesalers, Invoices, Inventory (future phases)
Incremental migrations — auto-upgrade via msfa_maybe_upgrade_database()

Features

Mobile Sales Force Automation for field sales reps — territories, routes, visits, orders, and collections via REST API

Sales rep profiles linked to BIXCRM staff
Territory management with client assignment
Mobile device registration & approval
REST API for mobile app authentication
API keys for integration partners
Admin dashboard, permissions, audit logs

Permissions

Granular staff capabilities are registered on activation. Assign them under Setup → Staff → Roles for the Mobile SFA 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 Mobile SFA.
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

Staff permissions (from module)

Assign under Setup → Staff → Roles. Each feature can expose different actions:

Feature	Actions
Dashboard `msfa_dashboard`	view
Sales Reps `msfa_sales_reps`	view, create, edit, delete
Territories `msfa_territories`	view, create, edit, delete
Mobile Devices `msfa_devices`	view, edit, delete
Visits `msfa_visits`	view, delete
Routes & Beats `msfa_routes`	view, create, edit, delete
Orders `msfa_orders`	view, edit, delete
Collections `msfa_collections`	view, edit, delete
API Keys `msfa_api`	view, create, delete
Settings `msfa_settings`	view, edit
Webhooks `msfa_webhooks`	view, create, edit, delete
Executive Reports `msfa_reports`	view

One-time setup (first time only)

Setup → Modules → activate Mobile SFA.
Setup → Staff → Roles → assign Mobile SFA permissions (view, create, edit, delete, approve, export, settings as needed).
Open Mobile SFA → 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.

Did you find this article useful?

Mobile SFA — Dashboard (how to use)

← Back to Mobile SFA overviewDashboardModule: Mobile SFAWhere to open in adminLog in to Admin.Open s...
Mobile SFA — Sales Reps (how to use)

← Back to Mobile SFA overviewSales RepsModule: Mobile SFAWhere to open in adminLog in to Admin.Open ...
Mobile SFA — Territories (how to use)

← Back to Mobile SFA overviewTerritoriesModule: Mobile SFAWhere to open in adminLog in to Admin.Open...
Mobile SFA — Mobile Devices (how to use)

← Back to Mobile SFA overviewMobile DevicesModule: Mobile SFAWhere to open in adminLog in to Admin.O...
Mobile SFA — Visits (how to use)

← Back to Mobile SFA overviewVisitsModule: Mobile SFAWhere to open in adminLog in to Admin.Open side...

Search Knowledge Base Articles

Mobile SFA — Overview & module guide

Screen-by-screen guides (each tab explained)

How to use in BIXCRM (daily operations)

Admin menu — where to work

Detailed guide — features, workflows, API & FAQ

Phase 1 (Complete) — Foundation

Phase 2 (Complete) — Visits & Check-In

Phase 3 (Complete) — Beat & Route Planning

Phase 4 (Complete) — Mobile Order Taking

Phase 5 (Complete) — Collections & Payments

Phase 6 (Complete) — Offline Sync & Enterprise

Mobile API

Login

Endpoints (Phase 1)

Visits (Phase 2)

Routes (Phase 3)

Orders (Phase 4)

Collections (Phase 5)

Permissions

Roadmap

Design Principles

Features

Permissions

Cron Jobs

After activation — configuration checklist

Staff permissions (from module)

One-time setup (first time only)

Did you find this article useful?

Related Articles

Mobile SFA — Dashboard (how to use)

Mobile SFA — Sales Reps (how to use)

Mobile SFA — Territories (how to use)

Mobile SFA — Mobile Devices (how to use)

Mobile SFA — Visits (how to use)