Live courier tracking on the map

Purpose#

The courier tracking map («تتبّع المناديب») shows where your couriers are now, the parcels each one carries, and their route over recent hours, kept for 30 days.

Who can use it#

The map is available to company staff accounts (company admin, in-charge, hub) and to a merchant who owns a private delivery company, when the plan has the live_tracking feature:

• Company: the super admin enables it in the plan form under "Plan features and limits", then "Available features". New plans have it off; an older plan whose features were never configured allows everything.
• Merchant with a private company: it is read from the merchant's plan, and nothing is restricted if the platform has no active merchant plan.
• A delivery company that must subscribe and has no active subscription is refused with a renewal message; this does not apply to the platform's own company or to companies exempt from subscriptions.

What you need#

• Couriers who sign in to the courier app and allow location access (this guide covers only its API).
• The tracking tables in the database (super admin, «صيانة النظام» in the menu, shown in Arabic in the English interface); otherwise the page says «الميزة لسا مو جاهزة على السيرفر» ("not ready on the server yet").
• A browser that reaches unpkg.com (map library) and OpenStreetMap tile servers.

Use the map#

1. Open the tracking map

   It is «تتبّع المناديب» in the company menu, and under "My delivery company" for a merchant (Arabic in the English interface too). If the plan lacks the feature you see «تتبّع المناديب مو ضمن باقتك» ("not in your plan") with a «شوف الباقات» ("See plans") button.

2. Pick a courier

   The top counters filter the list: All, «متصل» (online), «عم يتحرّك» (moving), «خامل» (idle), «غير متصل» (offline), and a plain total «طرد معهم» (parcels with them). Search by name, phone or tracking number, then click a courier. The map refreshes every 15 seconds; "View all" fits every courier in view.

3. Review the courier and their parcels

   The panel shows speed (km/h), battery, parcel count, a call button and a numbered list of the courier's parcels (delivery or pickup, tracking number, status, address, COD). A parcel without coordinates is tagged «بدون موقع على الخريطة» ("no location on the map"). The checkbox «لاحق المندوب المختار» ("follow") keeps the map on the courier.

4. Show the route

   Choose None, 2, 8 or 24 hours; the route is drawn with its length in km.

Couriers that have sent a position show as markers. States: online (last position within 2 minutes), moving (online at 3 km/h or more), idle (within 15 minutes), offline (older) and «ما بعت موقعه لسا» (never sent). «خارج الدوام» ("off duty") marks a courier who chose offline in the app and is not online.

What the courier app must send#

These requests use the Authorization: Bearer token received at courier login (a staff or merchant token for fleet and trail); unlike login and the parcel calls, they do not require the apiKey header.

1. GET /api/v10/deliveryman/tracking-config returns tracking_enabled, duty_required, on_duty, interval (20 seconds) and distance_filter (15 metres).
2. POST /api/v10/deliveryman/location (up to 30 requests per minute):

curl -X POST "https://YOUR_PLATFORM_HOST/api/v10/deliveryman/location" \
  -H "Authorization: Bearer COURIER_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"lat": 33.5138, "lng": 36.2765, "accuracy": 12, "speed": 4.2, "heading": 90, "battery": 80}'

After losing connection, upload a batch as {"points": [ ... ]} (at most 200). The reply's saved counts the points written to the route. If the feature is off for your company, or the courier switched to offline (off duty, on_duty false) in the app, the API still succeeds with saved 0 and stores nothing. A courier who merely shows as offline on the map (no position for over 15 minutes) can still upload.

3. POST /api/v10/deliveryman/duty with on_duty switches the online status. Older apps may use POST /api/v10/deliveryman/parcel-location-update (lat, long), which also records a point when the feature is on and the courier has not switched to offline in the app.

Staff apps use GET /api/v10/tracking/fleet and GET /api/v10/tracking/deliverymen/{id}/trail?hours=8 (1 to 72, default 8), 30 per minute, under the same plan feature.

Storage and the 30-day clean-up#

The system keeps each courier's last position, and adds a route point only if the reading is at least 15 metres from the reference point, or at least a minute after it. For a single upload the reference point is the previous reading received; inside an uploaded batch it is the last point stored from that batch. So a courier standing still, with the app sending a reading every 20 seconds, adds no points; the minute rule mainly applies after upload gaps, and a standing courier who uploads a buffered batch gets about one stored point per minute of it. Every day at 03:40 tracking:prune deletes route points older than 30 days (the last position stays). It runs through Laravel's scheduler, so the server's scheduled-task cron must be running.

Common mistakes#

• «ما في ولا مندوب بعت موقعه لسا…» (no courier has sent a location): couriers have not opened the app or allowed location.
• A courier does not move on the map: check they did not go offline in the app; that stops saving even without the online rule.

Limits and permissions#

• Only your own couriers are shown; other accounts are refused.
• If the plan feature is off, the map page shows a "not in your plan" screen, while the page's data feed and trail route and the fleet and trail API endpoints answer HTTP 403; the courier's location endpoint answers successfully without storing anything.
• Most labels stay Arabic in the English interface (only All, View all, None, Back and a few more are translated).