The courier delivery workflow through the mobile API

Purpose#

This guide follows one parcel from its assignment to a courier until the courier records the result: open the list, read the details, deliver in full or partially, or report a refusal or failure. There is no courier web panel. Everything here is done through the mobile API under /api/v10/deliveryman/*, called by whatever mobile app the platform operator provides for couriers; this guide does not cover a specific app or its download links (ask the platform operator which app your couriers use). This page describes what the API allows.

Who can use it#

Courier accounts of a delivery company, including couriers of a merchant's private delivery company. A suspended courier cannot sign in (HTTP 403). Company staff do what a courier cannot: assign parcels, reschedule, and undo a recorded result.

What you need#

• The apiKey header (a single platform-wide key configured on the server, the same for every account), the Accept: application/json header, and a Bearer token from POST /api/v10/deliveryman/login, which takes driver_id (courier ID, mobile or email) and password (at least 6 characters) and is limited to 10 requests per minute.
• A parcel assigned to you by the company.
• If your company requires couriers to be online, send POST /api/v10/deliveryman/duty with {"on_duty": true} first; otherwise company dispatchers cannot assign parcels to you.

Steps#

1. Sign in

   Send the login request with the apiKey header. The reply carries data.token; send it as Authorization: Bearer ... on every later call. A wrong ID or password gives HTTP 401, a missing apiKey gives HTTP 400 Invalid Api Key.

2. Open your parcels

   GET /api/v10/deliveryman/dashboard groups parcels by status: assigned, rescheduled, returned to the company, and delivered (full and partial). GET .../parcel/index lists every parcel ever linked to you as delivery or pickup courier, not only active ones. GET .../parcel/details/{id} returns the parcel and its events, or HTTP 404 if it is not linked to you. The lists returned by the dashboard endpoint show the amount to collect (cod_display, cod_original, cod_currency) and is_amount_collected for each parcel.

3. Deliver in full

   POST /api/v10/deliveryman/parcel/delivered/{id}, with optional note, image and signatureImage. The whole amount to collect is recorded as collected. Images must be JPEG, PNG, WebP or GIF up to 5 MB; an invalid image is skipped without an error.

4. Deliver partially

   POST /api/v10/deliveryman/parcel/partial-delivered/{id} with cash_collection (required), plus the same optional fields. The amount must be between 0 and the parcel's amount to collect.

5. Report a refusal or failure

   POST /api/v10/deliveryman/parcel-status-update with parcel_id and status_action, and optionally reason (or note) with your explanation. Use 5 when the recipient refuses or this attempt failed: the parcel goes back to the warehouse for another try, the reason you sent is saved (a default "delivery failed" reason is recorded if you send none) and you are unassigned. Use 24 for a final failure: the parcel returns to the company and the return-to-merchant path begins.

Expected result#

Replies use the shape {success, message, data}; a missing parcel_id or status_action returns HTTP 422 with Laravel's standard message and errors for JSON requests (without the Accept header Laravel redirects instead). On delivered/{id} and partial-delivered/{id}, the rule errors quoted below repeat after a dash and end with a reference like (ref: E1A2B3) (not on parcel-status-update), so they are only the start of the message: match on the HTTP status and part of the text. The fields is required! comes unchanged. Each change is recorded as a parcel event and triggers the notifications set for it.

Rules the system enforces#

• You can act only on a parcel assigned to you whose status is "Delivery Man Assign" (with courier) or "Delivery Re-Schedule" (rescheduled). Otherwise the answer is HTTP 422 with a message starting This parcel is not assigned to you. Repeating a delivery on a parcel that is already delivered gets the same answer. A parcel assigned to you for return to the merchant passes this check; the next rule then refuses delivery, partial delivery and refusal (status_action 9, 32 and 5) on it, while 24 is accepted from "Return assign to merchant" and moves it to "Return to Courier".
• Only moves on the allowed list are accepted; a refused move returns HTTP 422 with a message naming both statuses.
• Rescheduling, pickup steps and the final return to the merchant are done by company staff, with no courier endpoint. A rescheduled parcel stays in your list with the new date and you finish it the same way.
• Lists are built from events that name you, so a parcel you refused or that was reassigned may still be listed.

Common mistakes#

• A status_action other than 5, 9, 24 or 32. HTTP 400, and the text is the untranslated key parcel.invalid_status_action. GET .../parcel-status lists only 9, 24 and 32, although 5 is also accepted.
• No cash_collection on a partial delivery. Only partial-delivered/{id} rejects it (HTTP 422 The fields is required!); parcel-status-update with status_action 32 reads it as 0 and records Partial Delivered with nothing collected. Always send it.
• A collected amount above the parcel's amount, or negative. HTTP 422 with a message starting The collected amount exceeds the parcel COD amount or The collected amount cannot be negative.

Limits and permissions#

• Login and parcel endpoints need the apiKey header. The location, duty and tracking-config endpoints are registered outside that check and need only the Bearer token.
• The default API limit is 60 requests per minute per account; POST /api/v10/deliveryman/location is limited to 30 and POST /api/v10/deliveryman/duty to 20 requests per minute.
• A courier works only with parcels of their own company.
• The partial amount is checked against the parcel's amount in US dollars; see the guide on how a courier records cash on delivery.