How couriers work: the mobile API instead of a web panel

The short answer#

There is no courier web panel. Couriers work only through the mobile API under /api/v10/deliveryman/*: login, assigned parcels, status updates, partial delivery, location, the online toggle, and recording the amount collected. This guide does not cover a specific mobile app or its download links (ask the platform operator which app your couriers use); it describes what the API offers so you know how your couriers work with their app.

Who creates a courier account#

Company staff, from Couriers and commissions then New courier: name, mobile number (9 to 15 digits, unique), optional email, password (at least 6 characters), "Parcel limit with it", status and commission. The system generates a 6-digit login number shown on the courier's card ("رقم الدخول:", login number). The older "Delivery Man" menu (permission-controlled) can create couriers too. The number of couriers is capped by the company's plan (or the merchant's plan under "My delivery company"). A suspended courier cannot sign in and does not appear in dispatch.

What the API lets a courier do#

The apiKey header (one shared value taken from the platform's configuration, not per courier; ask the platform operator for it) is required for login, dashboard, the parcel calls, parcel-status-update and payment-logs; location, tracking-config and duty do not enforce it. Every endpoint except login needs an Authorization: Bearer token, and only a courier account is accepted. The subscription check that blocks writes in the merchant and company apps does not apply to couriers.

A courier's day#

1. Sign in

   Send driver_id (login number, mobile or email) and password (at least 6 characters), limited to 10 requests per minute.

   bashCopy

   curl -X POST "https://YOUR_PLATFORM_HOST/api/v10/deliveryman/login" \
     -H "apiKey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"driver_id": "123456", "password": "COURIER_PASSWORD"}'
   

   The reply carries data.token and data.user. Errors: HTTP 422 for missing fields, 401 with "رقم الدخول (أو الموبايل) أو كلمة المرور غلط." (wrong login number, mobile or password), 403 with "حساب المندوب موقوف — تواصل مع شركتك." (courier account suspended), and 400 with Invalid Api Key when the header is missing or wrong.

2. Receive and open parcels

   The company assigns parcels on the dispatch board (see the dispatch guide). The system queues a notification to the courier on assignment or rescheduling; whether it reaches the phone depends on the notification rules and Firebase setup. dashboard lists parcels by status and parcel/details/{id} returns the parcel with its events.

3. Record the delivery result

   parcel-status-update accepts status_action: 9 full delivery, 32 partial delivery (with cash_collection), 24 final failure (the parcel goes back to the company), and 5 refusal or failed attempt, which returns the parcel to the warehouse for another try. Any other value is rejected with HTTP 400. Actions 9 and 32 accept note, optional image and signature (signatureImage); 24 accepts note or reason; 5 accepts reason or note. Images and signature are not used for 24 and 5.

4. Record the cash collected

   There is no separate endpoint for collecting money. A full delivery records the parcel's whole COD amount; a partial delivery records cash_collection, which cannot exceed the COD amount. The amount is added to the cash the courier holds, and the company collects it in Courier settlements.

5. Send location and status

   GET .../tracking-config returns tracking_enabled and an interval of 20 seconds as the suggested pace for sending location, and POST .../duty with on_duty switches the courier online or offline. This guide does not describe the app's own behaviour.

Common mistakes#

• Expecting a courier web panel: there is none. The web pages for couriers are for company staff to manage them.
• Looking for a ready-made app or a download link here: this guide does not cover them.
• "This parcel is not assigned to you" (HTTP 422): a courier can change only a parcel that is assigned to them and currently with them.
• A request refused because of the status: invalid transitions get HTTP 422 with a message naming both statuses.
• Expecting couriers to reschedule or record the return to the merchant: their API has no endpoint for that; company staff record it.

Limits and permissions#

• A courier works only with parcels of their own company that are linked to them; another parcel's details are refused.
• parcel/index lists every parcel the courier was ever linked to (delivery or pickup), not only active ones.
• The profile, income-expense and parcel-payment-logs endpoints exist but are not documented here; their figures may rely on older accounting tables.
• Cash and commissions are settled by the company, not in the app.