Drivers

Server

List drivers

GET

https://api.wocart.store

/api/drivers

X-API-Key (header)

Returns a paginated list of drivers. Each item includes compensationWilayaCount — the number of wilayas with a configured per-delivery fee for this driver.

List drivers › query Parameters

wilayaId

integer · min: 1 · max: 58

Filter to drivers with a configured compensation row for this wilaya (1–58)

status

string · enum

Filter by availability status

Enum values:

available

busy

inactive

vehicleType

string · enum

Filter by vehicle type

Enum values:

motorcycle

car

van

search

string

Search by first name, last name, or phone

limit

integer · max: 100

Maximum number of results to return

Default: 50

offset

integer | null · min: 0

Number of results to skip for pagination

Default: 0

List drivers › Responses

200

List of drivers

success

boolean · required

Driver[] · required

count

integer · required

Number of items returned

GET/api/drivers

curl https://api.wocart.store/api/drivers \
  --header 'X-API-Key: <api-key>'

Example Responses

{
  "success": true,
  "data": [
    {
      "id": "drv_123",
      "firstName": "Mohamed",
      "lastName": "Amiri",
      "phone": "0551234567",
      "phone2": null,
      "vehicleType": "van",
      "status": "available",
      "totalDelivered": 50,
      "totalEarnings": 25000,
      "pendingCash": 5000,
      "totalPaid": 20000,
      "notes": "notes",
      "createdAt": "2024-08-25T15:00:00Z",
      "updatedAt": "2024-08-25T15:00:00Z",
      "compensationWilayaCount": 12,
      "recentShipments": [
        {
          "id": "id",
          "orderId": "orderId",
          "orderNumber": "orderNumber",
          "customerName": "customerName",
          "wilayaId": 0,
          "deliveryType": "home",
          "codAmount": 0,
          "driverFee": 0,
          "providerStatus": "providerStatus",
          "outForDeliveryAt": "outForDeliveryAt",
          "deliveredAt": "deliveredAt",
          "returnedAt": "returnedAt",
          "deliveryAttempts": 0,
          "stage": "new",
          "createdAt": "createdAt"
        }
      ],
      "openShipmentCount": 0,
      "cashReconciliation": {
        "pendingCash": 0,
        "pendingOrdersTotal": 0,
        "pendingOrdersCount": 0,
        "drift": 0
      }
    }
  ],
  "count": 0
}

json

application/json

Create driver

POST

https://api.wocart.store

/api/drivers

X-API-Key (header)

Create driver › Request Body

firstName

string · minLength: 1 · required

lastName

string · minLength: 1 · required

phone

string · pattern: ^0[5-7]\d{8}$ · required

Algerian mobile number starting with 05, 06, or 07

phone2

string | null · pattern: ^0[5-7]\d{8}$

Optional secondary phone number

vehicleType

string | null · enum

Type of vehicle. Omit or null if unknown.

Enum values:

motorcycle

car

van

status

string · enum

Availability status. Defaults to available.

Enum values:

available

busy

inactive

Default: available

notes

string | null

Internal notes about the driver (not visible to customers)

Create driver › Responses

Driver created. Returns full driver record including compensationWilayaCount and recentShipments.

success

boolean · required

Driver · required

Delivery driver profile with denormalized earnings statistics

message

string · required

POST/api/drivers

curl https://api.wocart.store/api/drivers \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "firstName": "Mohamed",
  "lastName": "Amiri",
  "phone": "0551234567",
  "phone2": "phone2",
  "vehicleType": "motorcycle",
  "status": "available",
  "notes": "notes"
}'

Example Request Body

{
  "firstName": "Mohamed",
  "lastName": "Amiri",
  "phone": "0551234567",
  "phone2": "phone2",
  "vehicleType": "motorcycle",
  "status": "available",
  "notes": "notes"
}

json

Example Responses

{
  "success": true,
  "data": {
    "id": "drv_123",
    "firstName": "Mohamed",
    "lastName": "Amiri",
    "phone": "0551234567",
    "phone2": null,
    "vehicleType": "van",
    "status": "available",
    "totalDelivered": 50,
    "totalEarnings": 25000,
    "pendingCash": 5000,
    "totalPaid": 20000,
    "notes": "notes",
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z",
    "compensationWilayaCount": 12,
    "recentShipments": [
      {
        "id": "id",
        "orderId": "orderId",
        "orderNumber": "orderNumber",
        "customerName": "customerName",
        "wilayaId": 0,
        "deliveryType": "home",
        "codAmount": 0,
        "driverFee": 0,
        "providerStatus": "providerStatus",
        "outForDeliveryAt": "outForDeliveryAt",
        "deliveredAt": "deliveredAt",
        "returnedAt": "returnedAt",
        "deliveryAttempts": 0,
        "stage": "new",
        "createdAt": "createdAt"
      }
    ],
    "openShipmentCount": 0,
    "cashReconciliation": {
      "pendingCash": 0,
      "pendingOrdersTotal": 0,
      "pendingOrdersCount": 0,
      "drift": 0
    }
  },
  "message": "Operation completed successfully"
}

json

application/json

Get driver

GET

https://api.wocart.store

/api/drivers/{id}

X-API-Key (header)

Returns full driver detail: compensationWilayaCount, recentShipments (the 10 most recent orders given to this driver, newest first), openShipmentCount (orders still out) and cashReconciliation (the cash counter against the delivered shipments not yet handed over). Use GET /{id}/compensations for the per-wilaya pay grid.

Get driver › path Parameters

id

string · required

Driver ID

Get driver › Responses

200

Driver detail

success

boolean · required

Driver · required

Delivery driver profile with denormalized earnings statistics

GET/api/drivers/{id}

curl https://api.wocart.store/api/drivers/:id \
  --header 'X-API-Key: <api-key>'

Example Responses

{
  "success": true,
  "data": {
    "id": "drv_123",
    "firstName": "Mohamed",
    "lastName": "Amiri",
    "phone": "0551234567",
    "phone2": null,
    "vehicleType": "van",
    "status": "available",
    "totalDelivered": 50,
    "totalEarnings": 25000,
    "pendingCash": 5000,
    "totalPaid": 20000,
    "notes": "notes",
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z",
    "compensationWilayaCount": 12,
    "recentShipments": [
      {
        "id": "id",
        "orderId": "orderId",
        "orderNumber": "orderNumber",
        "customerName": "customerName",
        "wilayaId": 0,
        "deliveryType": "home",
        "codAmount": 0,
        "driverFee": 0,
        "providerStatus": "providerStatus",
        "outForDeliveryAt": "outForDeliveryAt",
        "deliveredAt": "deliveredAt",
        "returnedAt": "returnedAt",
        "deliveryAttempts": 0,
        "stage": "new",
        "createdAt": "createdAt"
      }
    ],
    "openShipmentCount": 0,
    "cashReconciliation": {
      "pendingCash": 0,
      "pendingOrdersTotal": 0,
      "pendingOrdersCount": 0,
      "drift": 0
    }
  }
}

json

application/json

Update driver

PATCH

https://api.wocart.store

/api/drivers/{id}

X-API-Key (header)

Partial update — only include fields you want to change. Use PATCH /{id}/status to change availability status. Set phone2, vehicleType, or notes to null to clear them.

Update driver › path Parameters

id

string · required

Driver ID

Update driver › Request Body

firstName

string · minLength: 1

lastName

string · minLength: 1

phone

string · pattern: ^0[5-7]\d{8}$

Algerian mobile number starting with 05, 06, or 07

phone2

string | null · pattern: ^0[5-7]\d{8}$

Updated secondary phone. Send null to clear it.

vehicleType

string | null · enum

Updated vehicle type. Send null to clear it.

Enum values:

motorcycle

car

van

notes

string | null

Updated internal notes. Send null to clear.

Update driver › Responses

Driver updated. Returns full updated driver record.

success

boolean · required

Driver · required

Delivery driver profile with denormalized earnings statistics

message

string · required

PATCH/api/drivers/{id}

curl https://api.wocart.store/api/drivers/:id \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "firstName": "firstName",
  "lastName": "lastName",
  "phone": "0551234567",
  "phone2": "phone2",
  "vehicleType": "motorcycle",
  "notes": "notes"
}'

Example Request Body

{
  "firstName": "firstName",
  "lastName": "lastName",
  "phone": "0551234567",
  "phone2": "phone2",
  "vehicleType": "motorcycle",
  "notes": "notes"
}

json

Example Responses

{
  "success": true,
  "data": {
    "id": "drv_123",
    "firstName": "Mohamed",
    "lastName": "Amiri",
    "phone": "0551234567",
    "phone2": null,
    "vehicleType": "van",
    "status": "available",
    "totalDelivered": 50,
    "totalEarnings": 25000,
    "pendingCash": 5000,
    "totalPaid": 20000,
    "notes": "notes",
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z",
    "compensationWilayaCount": 12,
    "recentShipments": [
      {
        "id": "id",
        "orderId": "orderId",
        "orderNumber": "orderNumber",
        "customerName": "customerName",
        "wilayaId": 0,
        "deliveryType": "home",
        "codAmount": 0,
        "driverFee": 0,
        "providerStatus": "providerStatus",
        "outForDeliveryAt": "outForDeliveryAt",
        "deliveredAt": "deliveredAt",
        "returnedAt": "returnedAt",
        "deliveryAttempts": 0,
        "stage": "new",
        "createdAt": "createdAt"
      }
    ],
    "openShipmentCount": 0,
    "cashReconciliation": {
      "pendingCash": 0,
      "pendingOrdersTotal": 0,
      "pendingOrdersCount": 0,
      "drift": 0
    }
  },
  "message": "Operation completed successfully"
}

json

application/json

Delete driver

DELETE

https://api.wocart.store

/api/drivers/{id}

X-API-Key (header)

Permanently deletes a driver who never had an order. 409 while the driver has orders out (DRIVER_HAS_ACTIVE_ORDERS — finish or take them back first) or has past deliveries (DRIVER_HAS_SHIPMENTS — set the driver inactive instead).

Delete driver › path Parameters

id

string · required

Driver ID

Delete driver › Responses

Driver deleted

success

boolean · required

message

string · required

Update driver status

PATCH

https://api.wocart.store

/api/drivers/{id}/status

X-API-Key (header)

Updates driver availability status. Returns the full updated driver record.

Update driver status › path Parameters

id

string · required

Driver ID

Update driver status › Request Body

status

string · enum · required

New availability status for the driver

Enum values:

available

busy

inactive

Update driver status › Responses

200

Status updated

success

boolean · required

Driver · required

Delivery driver profile with denormalized earnings statistics

message

string · required

PATCH/api/drivers/{id}/status

curl https://api.wocart.store/api/drivers/:id/status \
  --request PATCH \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: <api-key>' \
  --data '{
  "status": "available"
}'

Example Request Body

{
  "status": "available"
}

json

Example Responses

{
  "success": true,
  "data": {
    "id": "drv_123",
    "firstName": "Mohamed",
    "lastName": "Amiri",
    "phone": "0551234567",
    "phone2": null,
    "vehicleType": "van",
    "status": "available",
    "totalDelivered": 50,
    "totalEarnings": 25000,
    "pendingCash": 5000,
    "totalPaid": 20000,
    "notes": "notes",
    "createdAt": "2024-08-25T15:00:00Z",
    "updatedAt": "2024-08-25T15:00:00Z",
    "compensationWilayaCount": 12,
    "recentShipments": [
      {
        "id": "id",
        "orderId": "orderId",
        "orderNumber": "orderNumber",
        "customerName": "customerName",
        "wilayaId": 0,
        "deliveryType": "home",
        "codAmount": 0,
        "driverFee": 0,
        "providerStatus": "providerStatus",
        "outForDeliveryAt": "outForDeliveryAt",
        "deliveredAt": "deliveredAt",
        "returnedAt": "returnedAt",
        "deliveryAttempts": 0,
        "stage": "new",
        "createdAt": "createdAt"
      }
    ],
    "openShipmentCount": 0,
    "cashReconciliation": {
      "pendingCash": 0,
      "pendingOrdersTotal": 0,
      "pendingOrdersCount": 0,
      "drift": 0
    }
  },
  "message": "Operation completed successfully"
}

json

application/json

List driver compensations

GET

https://api.wocart.store

/api/drivers/{id}/compensations

X-API-Key (header)

Returns all 58 wilayas with the driver's configured per-delivery fee. feePerDelivery is null when no row has been configured for that wilaya (in which case the assigned order's driver fee defaults to 0).

List driver compensations › path Parameters

id

string · required

Driver ID

List driver compensations › Responses

200

Per-wilaya compensation grid for this driver.

success

boolean · required

DriverCompensationRow[] · required

Upsert driver compensation for one wilaya

PUT

https://api.wocart.store

/api/drivers/{id}/compensations/{wilayaId}

X-API-Key (header)

Sets (or updates) the per-delivery fee this driver is paid for the given wilaya. Idempotent.

Upsert driver compensation for one wilaya › path Parameters

id

string · required

Driver ID

wilayaId

integer · min: 1 · max: 58 · required

Wilaya ID (1–58)

Upsert driver compensation for one wilaya › Request Body

feePerDelivery

number · min: 0 · required

DZD per delivery in this wilaya.

Upsert driver compensation for one wilaya › Responses

200

Compensation saved.

success

boolean · required

object · required

message

string · required

Remove driver compensation for one wilaya

DELETE

https://api.wocart.store

/api/drivers/{id}/compensations/{wilayaId}

X-API-Key (header)

Removes the per-delivery fee row for this driver/wilaya pair. Future assignments in that wilaya will compute driverFee = 0 until a new row is set.

Remove driver compensation for one wilaya › path Parameters

id

string · required

Driver ID

wilayaId

integer · min: 1 · max: 58 · required

Wilaya ID (1–58)

Remove driver compensation for one wilaya › Responses

Compensation removed.

success

boolean · required

message

string · required

Customer Tags Driver Payments