API Reference

Welcome to the Courier & Delivery Platform API. This API is designed to allow partners (E-commerce websites, POS systems, ERPs, and mobile apps) to seamlessly integrate their platforms with our delivery services.

By integrating our APIs, you can programmatically calculate distance/time estimates, automatically dispatch optimal cargo vehicles based on cargo specs, and track delivery statuses live.

API Prefix Endpoints:
This documentation lists versioned endpoints. The API supports two versions:
  • V1 (Production default): https://{{base_url}}/api/v1/customer/... (identical to /api/customer/...)
  • V2 (Scheduled Orders active): https://{{base_url}}/api/v2/customer/...

Authentication

The API uses Bearer Token Authentication powered by Laravel Sanctum. All endpoints except /login require an authorization header.

Authorization Header format:
Authorization: Bearer YOUR_ACCESS_TOKEN

1. Partner Login / Access Token Generation

Submit your partner phone number and password credentials to obtain the access token.

HTTP Request

POST /login (or /api/v1/customer/login)

Request Body Parameters

Parameter Type Status Description
phone String Required Partner account phone number. Must be exactly 10 digits and start with 091, 092, 093, 094, or 095.
password String Required The password associated with your account.

Integration Flow

Below is the recommended integration flow for programmatic order dispatching:

Step 1: Authenticate

Login and obtain a Bearer token. Store it securely in your backend session variables.

Step 2: Lookup types

Fetch shipment types and vehicle categories to align specifications with our systems.

Step 3: Estimate Shipment

Call the /orders/estimate endpoint to verify distance, time, and see what vehicle category our smart engine suggests.

Step 4: Confirm Order

Confirm the shipment. Our background worker immediately alerts matched nearby drivers.

Step 5: Listen to Webhooks

Your server listens to event notifications (e.g. shipment.accepted, shipment.picked_up, shipment.delivered) to keep your database synced.

Lookup APIs

1. Get Shipment Types

Retrieve the active list of shipment types supported by the platform (e.g., general boxes, furniture, food, construction).

HTTP Request

GET /shipment-types

2. Get Vehicle Types & Categories

Retrieve vehicle categories and nested vehicle types with their active pricing metrics (base fare + per km rate).

HTTP Request

GET /vehicle-types

Shipment Status Codes

All shipment (order) statuses are represented by an integer in the database payload. Reference this table to map status flags:

Status ID Arabic Name Driver Label Description
1قيد الانتظارطلب جديدPending driver assignment. Dispatching matches.
2مقبولتم قبول الطلبDriver accepted the shipment.
3في الطريق للمصدرالسائق في الطريق إليكDriver is driving to the pickup source coordinates.
4وصل للمصدرالسائق وصل لنقطة التحميلDriver arrived at the pickup site.
5قيد التوصيلجاري توصيل الشحنةCargo loaded; shipment is in-transit.
6تم التوصيلتم تنفيذ الطلب بنجاحDelivered successfully.
7ملغية (قبل القبول)تم إلغاء الطلب قبل قبول السائقCancelled before any driver accepted it.
8ملغية (بعد القبول)تم إلغاء الطلب بعد قبول السائقCancelled after a driver accepted it.

Shipment Management

1. Estimate Shipment Cost

Calculates road distance, time, and maps the cargo criteria onto the most optimal vehicle model.

Smart Dispatch Flow:
Instead of choosing the vehicle, you supply cargo type and size. The engine makes the selection dynamically.

HTTP Request

POST /orders/estimate

Request Body Parameters

Parameter Type Status Description
shipment_type_id Integer Required The ID of the shipment type (from `/shipment-types`).
size String Required Size group. Must be: small, medium, large, or heavy.
source_lat Numeric Conditional Latitude of the pickup point. Required if address_id is omitted.
source_lng Numeric Conditional Longitude of the pickup point. Required if address_id is omitted.
destination_lat Numeric Conditional Latitude of drop-off. Required if address_id is empty and auto_dispose is not true.
details Object Optional Dynamic details block. Validated against cargo type. (e.g. details.needs_helpers for furniture).

2. Confirm Shipment (Create Order)

Creates a live order in our database. Initiates driver matching and reserves transaction funds.

HTTP Request

POST /orders/confirm

Multipart/Form-Data support:
If submitting a cargo load snapshot image in the cargo_image field, you must submit this request as multipart/form-data instead of raw JSON.

Additional V2 Scheduled Order parameters

Under API version V2, you can submit scheduled delivery tasks to be matched at a future time:

Parameter Type Status Description
is_scheduled Boolean Optional Pass true or 1 to flag as a scheduled delivery.
scheduled_at String Conditional Required if is_scheduled is true. Format: Y-m-d H:i:s (must be a future date).

3. Get Shipment Details

Retrieve live updates for an order, including the assigned driver coordinates (when in transit).

HTTP Request

GET /orders/order/{id}

4. Cancel Shipment

Cancels an active shipment before it transitions to status 6 (Delivered).

HTTP Request

POST /orders/order/{id}/cancel

5. Retry Driver Search

If no driver accepts an order during the initial matching timer, re-open matching notifications using this route.

HTTP Request

POST /orders/order/{id}/retry

6. List Partner Shipments

Retrieve the full paginated order history placed under your API account credentials.

HTTP Request

GET /orders/my-orders

Driver APIs

1. Accept Order

Accepts a pending order matching the driver's criteria. The order status transitions to 2 (Accepted).

HTTP Request

POST /driver/orders/accept-order

Request Body Parameters

Parameter Type Status Description
order_id Integer Required ID of the order to accept.
lat Numeric Optional Driver's current latitude.
lng Numeric Optional Driver's current longitude.

2. Update Order Status

Updates the order state as the driver performs the shipment delivery. Valid transition status codes must be provided.

HTTP Request

PUT /driver/orders/update-status

Request Body Parameters

Parameter Type Status Description
order_id Integer Required ID of the order to update.
status_id Integer Required Target status code. Valid codes:
3 (Driving to source)
4 (Arrived at source)
5 (In-transit / cargo loaded)
6 (Delivered successfully)

3. Update Location (In-transit Tracking)

Sends real-time coordinates during active transit. This broadcasts changes to client-side tracking maps.

HTTP Request

PUT /driver/orders/update-location

Request Body Parameters

Parameter Type Status Description
order_id Integer Required ID of the active order.
current_lat Numeric Required Current latitude.
current_lng Numeric Required Current longitude.

4. Set Working Center / Location

Configures the driver's working base coordinates and operational search radius.

HTTP Request

PUT /driver/orders/set-location

Request Body Parameters

Parameter Type Status Description
current_lat Numeric Required Operational center latitude.
current_lng Numeric Required Operational center longitude.
working_radius Numeric Optional Operating radius in KM. If omitted, falls back to the system settings default.

5. Get Available Orders

Retrieves nearby unassigned orders matching the driver's approved vehicles and preferred cargo specifications.

HTTP Request

GET /driver/orders/available

Query Parameters

Parameter Type Status Description
lat Numeric Optional Update current driver latitude before searching.
lng Numeric Optional Update current driver longitude before searching.
Scheduled Orders (V2):
Under version V2, you can use additional endpoints to manage scheduled orders:
  • GET /driver/orders/scheduled — List available future scheduled rides.
  • GET /driver/orders/my-scheduled — List your accepted scheduled rides.
  • POST /driver/orders/accept-scheduled — Accept a scheduled ride (requires order_id).
  • POST /driver/orders/cancel-scheduled — Cancel/drop your booking of a scheduled ride (requires order_id).

6. Reject Order

Dismisses a pending nearby order from the driver's feed, preventing it from appearing in future available order listings.

HTTP Request

POST /driver/orders/reject-order

Request Body Parameters

Parameter Type Status Description
order_id Integer Required The order ID to reject.

Webhooks

Receive live, push event notifications on shipment status modifications straight to your server endpoints.

Webhook Signature Validation

Each webhook request includes an X-Mahtta-Signature header. Verify the signature by calculating the HMAC-SHA256 signature using the raw request body and your developer secret key.

Supported Event Notifications:

  • shipment.created — Shipment recorded.
  • shipment.accepted — Matched with driver.
  • shipment.picked_up — Cargo loaded.
  • shipment.delivered — Complete.
  • shipment.cancelled — Aborted.

Idempotency & Request Safety

Avoid duplicate delivery charges due to network disconnects during POST operations.

1. Double click protection: The server places an atomic concurrency lock on your account for 10 seconds during shipment creations to filter duplicate submissions.

2. Idempotency Key: Submit a unique UUID string inside the Idempotency-Key header to query or resend creations safely.

Rate Limits

Rate limits are verified globally for all routes inside the api middleware group:

60 requests per minute per user account session/IP address.

Returned Headers

  • X-RateLimit-Limit: 60
  • X-RateLimit-Remaining: 59
  • Retry-After: 30

Error Handling

Errors returned by the server include clear JSON diagnostic blocks.

Validation Errors (422 Unprocessable Content):

{
  "status": false,
  "message": "liquid_type is required for liquids cargo.",
  "errors": {
    "details.liquid_type": [
      "liquid_type is required for liquids cargo."
    ]
  }
}
POST /orders/estimate
Code Sample
Loading code sample...
Response Example
Loading response sample...