Dispatch Module

OAS 3.1.0 v1.2.0 ✓ Valid 3.1

specs/dispatch-module.yaml • 9 operations • 13 schemas • 1 webhooks

⬇ Download .yaml

Dispatch Module

Configured Target Servers

https://dev.hubz.nyotek.com Server endpoint

Detected OpenAPI 3.1 / JSON Schema 2020-12 Features

✦ webhooks✦ schema examples array

Dispatch

POST /ext/dispatch Create a new dispatch request

Create a new dispatch request with a pickup and delivery address

Request Body (application/json)

{
  "pickup": {
    "ref_id": "b93d16aa-e34d-4c65-b6ef-acdcca470615",
    "lat": 24.712181,
    "lng": 46.679747,
    "address_line": "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
  },
  "destination": {
    "ref_id": "b93d16aa-e34d-4c65-b6ef-acdcca470615",
    "lat": 24.712181,
    "lng": 46.679747,
    "address_line": "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
  },
  "user_metadata": {
    "id": "15ed2668-f118-40c3-a52c-8ad90fe11ed7",
    "username": "theUser",
    "firstName": "John",
    "lastName": "James",
    "email": "john@email.com",
    "phone": 9669876654321
  },
  "vendor_logo_url": "https://picsum.photos/200/300",
  "vendor_id": "15ed2668-f118-40c3-a52c-8ad90fe11ed7",
  "vendor_name": {
    "en-us": "English based text",
    "ar-sa": "جملة عربية"
  },
  "vendor_oid": "15ed2668-f118-40c3-a52c-8ad90fe11ed7",
  "vendor_sid": "15EEDFRG",
  "vendor_bid": "15ed2668-f118-40c3-a52c-8ad90fe11ed7",
  "vendor_payload": {
    "pickup_wait_time": 20,
    "order_price": 123.65
  }
}

Responses

201 Successful operation

{
  "data": {
    "id": "01HQ0PV32FMRA1XGT609QFV2VJ"
  }
}

400 if a dispatch with a an existing order/vendor_oid exists

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

401 Unauthorized if incorrect api_key is given

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

500 any other errors from the server

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

GET /ext/dispatches/d/{driver_id} Fetch dispatches by driver id

Fetch all the dispatches by assigned driver id

Request Parameters

Name	In	Type (OAS 3.1)	Required
`driver_id`	path	`string`	Yes

Responses

200 successful operation

{
  "data": [
    {
      "id": "01HQ0PV32FMRA1XGT609QFV2VJ",
      "created_at": "sample_string",
      "modified_at": "sample_string",
      "r_id": "DYJ7XZ7",
      "assigned_driver_id": "01HQ0PV32FMRA1XGT609QFV2VJ",
      "pickup": {
        "ref_id": "b93d16aa-e34d-4c65-b6ef-acdcca470615",
        "lat": 24.712181,
        "lng": 46.679747,
        "address_line": "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
      },
      "destination": {
        "ref_id": "b93d16aa-e34d-4c65-b6ef-acdcca470615",
        "lat": 24.712181,
        "lng": 46.679747,
        "address_line": "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
      },
      "user_metadata": {
        "id": "15ed2668-f118-40c3-a52c-8ad90fe11ed7",
        "username": "theUser",
        "firstName": "John",
        "lastName": "James",
        "email": "john@email.com",
        "phone": 9669876654321
      },
      "vendor_logo_url": "https://picsum.photos/200/300",
      "vendor_id": "15ed2668-f118-40c3-a52c-8ad90fe11ed7",
      "vendor_name": {
        "en-us": "English based text",
        "ar-sa": "جملة عربية"
      },
      "vendor_oid": "15ed2668-f118-40c3-a52c-8ad90fe11ed7",
      "vendor_sid": "15EEDFRG",
      "vendor_bid": "15ed2668-f118-40c3-a52c-8ad90fe11ed7",
      "media_url": {
        "1": "https://picsum.photos/200/300",
        "2": "https://picsum.photos/200/400"
      },
      "status": [
        {
          "status": "accepted",
          "status_captured_time": "2024-02-28 12:05:24.992",
          "ref_id": "01HQ0PV32FMRA1XGT609QFV2VJ",
          "ref_type": "user"
        }
      ]
    }
  ]
}

401 Unauthorized if incorrect api_key is given

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

500 any other errors from the server

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

GET /ext/dispatches Fetch all dispatches

Fetch all the dispatches

Responses

200 successful operation

{
  "data": [
    {
      "id": "01HQ0PV32FMRA1XGT609QFV2VJ",
      "created_at": "sample_string",
      "modified_at": "sample_string",
      "r_id": "DYJ7XZ7",
      "assigned_driver_id": "01HQ0PV32FMRA1XGT609QFV2VJ",
      "pickup": {
        "ref_id": "b93d16aa-e34d-4c65-b6ef-acdcca470615",
        "lat": 24.712181,
        "lng": 46.679747,
        "address_line": "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
      },
      "destination": {
        "ref_id": "b93d16aa-e34d-4c65-b6ef-acdcca470615",
        "lat": 24.712181,
        "lng": 46.679747,
        "address_line": "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
      },
      "user_metadata": {
        "id": "15ed2668-f118-40c3-a52c-8ad90fe11ed7",
        "username": "theUser",
        "firstName": "John",
        "lastName": "James",
        "email": "john@email.com",
        "phone": 9669876654321
      },
      "vendor_logo_url": "https://picsum.photos/200/300",
      "vendor_id": "15ed2668-f118-40c3-a52c-8ad90fe11ed7",
      "vendor_name": {
        "en-us": "English based text",
        "ar-sa": "جملة عربية"
      },
      "vendor_oid": "15ed2668-f118-40c3-a52c-8ad90fe11ed7",
      "vendor_sid": "15EEDFRG",
      "vendor_bid": "15ed2668-f118-40c3-a52c-8ad90fe11ed7",
      "media_url": {
        "1": "https://picsum.photos/200/300",
        "2": "https://picsum.photos/200/400"
      },
      "status": [
        {
          "status": "accepted",
          "status_captured_time": "2024-02-28 12:05:24.992",
          "ref_id": "01HQ0PV32FMRA1XGT609QFV2VJ",
          "ref_type": "user"
        }
      ]
    }
  ]
}

401 Unauthorized if incorrect api_key is given

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

500 any other errors from the server

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

GET /ext/dispatch/{id} Fetch a dispatch

Fetch a dispatch

Request Parameters

Name	In	Type (OAS 3.1)	Required
`id`	path	`string`	Yes

Responses

200 successful operation

{
  "data": {
    "id": "01HQ0PV32FMRA1XGT609QFV2VJ",
    "created_at": "sample_string",
    "modified_at": "sample_string",
    "r_id": "DYJ7XZ7",
    "assigned_driver_id": "01HQ0PV32FMRA1XGT609QFV2VJ",
    "pickup": {
      "ref_id": "b93d16aa-e34d-4c65-b6ef-acdcca470615",
      "lat": 24.712181,
      "lng": 46.679747,
      "address_line": "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
    },
    "destination": {
      "ref_id": "b93d16aa-e34d-4c65-b6ef-acdcca470615",
      "lat": 24.712181,
      "lng": 46.679747,
      "address_line": "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
    },
    "user_metadata": {
      "id": "15ed2668-f118-40c3-a52c-8ad90fe11ed7",
      "username": "theUser",
      "firstName": "John",
      "lastName": "James",
      "email": "john@email.com",
      "phone": 9669876654321
    },
    "vendor_logo_url": "https://picsum.photos/200/300",
    "vendor_id": "15ed2668-f118-40c3-a52c-8ad90fe11ed7",
    "vendor_name": {
      "en-us": "English based text",
      "ar-sa": "جملة عربية"
    },
    "vendor_oid": "15ed2668-f118-40c3-a52c-8ad90fe11ed7",
    "vendor_sid": "15EEDFRG",
    "vendor_bid": "15ed2668-f118-40c3-a52c-8ad90fe11ed7",
    "media_url": {
      "1": "https://picsum.photos/200/300",
      "2": "https://picsum.photos/200/400"
    },
    "status": [
      {
        "status": "accepted",
        "status_captured_time": "2024-02-28 12:05:24.992",
        "ref_id": "01HQ0PV32FMRA1XGT609QFV2VJ",
        "ref_type": "user"
      }
    ]
  }
}

401 Unauthorized if incorrect api_key is given

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

500 any other errors from the server

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

POST /ext/dispatch/{id}/status Cancel a dispatch

cancel an existing dispatch

Request Parameters

Name	In	Type (OAS 3.1)	Required
`id`	path	`string`	Yes

Request Body (application/json)

{
  "status": "cancelled",
  "ref_id": "15ed2668-f118-40c3-a52c-8ad90fe11ed7",
  "ref_type": "user"
}

Responses

204 successful operation

401 Unauthorized if incorrect api_key is given

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

404 if the dispatch id is not found in the system

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

500 any other errors from the server

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

PATCH /ext/dispatch/{id}/pickup Update pickup address

update pickup address of an existing dispatch

Request Parameters

Name	In	Type (OAS 3.1)	Required
`id`	path	`string`	Yes

Request Body (application/json)

{
  "ref_id": "b93d16aa-e34d-4c65-b6ef-acdcca470615",
  "lat": 24.712181,
  "lng": 46.679747,
  "address_line": "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
}

Responses

204 successful operation

401 Unauthorized if incorrect api_key is given

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

404 if the dispatch id is not found in the system

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

500 any other errors from the server

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

PATCH /ext/dispatch/{id}/destination Update destination address

update destination address of an existing dispatch

Request Parameters

Name	In	Type (OAS 3.1)	Required
`id`	path	`string`	Yes

Request Body (application/json)

{
  "ref_id": "b93d16aa-e34d-4c65-b6ef-acdcca470615",
  "lat": 24.712181,
  "lng": 46.679747,
  "address_line": "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
}

Responses

204 successful operation

401 Unauthorized if incorrect api_key is given

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

404 if the dispatch id is not found in the system

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

500 any other errors from the server

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

POST /ext/estimate Request delivery estimates

request delivery estimates for a new dispatch

Request Body (application/json)

{
  "pickup": {
    "ref_id": "b93d16aa-e34d-4c65-b6ef-acdcca470615",
    "lat": 24.712181,
    "lng": 46.679747,
    "address_line": "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
  },
  "destination": {
    "ref_id": "b93d16aa-e34d-4c65-b6ef-acdcca470615",
    "lat": 24.712181,
    "lng": 46.679747,
    "address_line": "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
  },
  "pickup_wait_time": 20
}

Responses

200 Successful operation

{
  "data": {
    "pickup_estimated_time": 20,
    "destination_estimated_time": 20,
    "total_estimated_time": 20,
    "delivery_price": 42,
    "delivery_price_text": "sample_string",
    "vat_price": 42,
    "vat_price_text": "sample_string"
  }
}

401 Unauthorized if incorrect api_key is given

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

500 any other errors from the server

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

RegisterWebhook

POST /ext/webhook Register a webhook

Request Body (application/json)

{
  "webhook": "https://host.com/webhook"
}

Responses

204 Successful operation

400 bad request if the url is invalid or will not respond with a 200 status code.

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

401 Unauthorized if incorrect api_key is given

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

500 any other errors from the server

{
  "error": "generic error",
  "error_desc": "identifier 45 not found"
}

OpenAPI 3.1 Webhooks

WEBHOOK POST statusUpdates statusUpdates

Webhook Payload Sample

{
  "payload_type": "status_update",
  "payload": {
    "id": "01HQ0PV32FMRA1XGT609QFV2VJ",
    "status": "accepted",
    "status_captured_time": "2024-02-28 12:05:24.992",
    "ref_id": "01HQ0PV32FMRA1XGT609QFV2VJ",
    "ref_type": "user",
    "vendor_oid": "15ed2668-f118-40c3-a52c-8ad90fe11ed7",
    "vendor_sid": "15EEDFRG",
    "vendor_id": "15ed2668-f118-40c3-a52c-8ad90fe11ed7"
  }
}

Component Schemas (JSON Schema 2020-12)

LocaleTextObject

object

Address

object

Property	Type	Required
`ref_id`	`string`	—
`lat`	`number` (double)	✓
`lng`	`number` (double)	✓
`address_line`	`string`	—

User

object

Property	Type	Required
`id`	`string`	✓
`username`	`string`	—
`firstName`	`string`	—
`lastName`	`string`	—
`email`	`string`	✓
`phone`	`string`	✓

VendorPayload

object

Property	Type	Required
`pickup_wait_time`	`integer`	—
`order_price`	`number` (float)	—

DispatchRequest

object

Property	Type	Required
`pickup`	`object`	✓
`destination`	`object`	✓
`user_metadata`	`object`	✓
`vendor_logo_url`	`string`	—
`vendor_id`	`string`	✓
`vendor_name`	`object`	✓
`vendor_oid`	`string`	✓
`vendor_sid`	`string`	—
`vendor_bid`	`string`	✓
`vendor_payload`	`object`	—

DispatchResponse

object

Property	Type	Required
`id`	`string`	—

ErrorResponse

object

Property	Type	Required
`error`	`string`	—
`error_desc`	`string`	—

DispatchUnit

object

Property	Type	Required
`id`	`string`	—
`created_at`	`string`	—
`modified_at`	`string`	—
`r_id`	`string`	—
`assigned_driver_id`	`string`	—
`pickup`	`object`	—
`destination`	`object`	—
`user_metadata`	`object`	—
`vendor_logo_url`	`string`	—
`vendor_id`	`string`	—
`vendor_name`	`object`	—
`vendor_oid`	`string`	—
`vendor_sid`	`string`	—
`vendor_bid`	`string`	—
`media_url`	`object`	—
`status`	`array<object>`	—

DispatchStatus

object

Property	Type	Required
`status`	`string`	—
`status_captured_time`	`string`	—
`ref_id`	`string`	—
`ref_type`	`string`	—

CancelDispatch

object

Property	Type	Required
`status`	`string`	—
`ref_id`	`string`	—
`ref_type`	`string`	—

EstimateRequest

object

Property	Type	Required
`pickup`	`object`	✓
`destination`	`object`	✓
`pickup_wait_time`	`integer`	—

EstimateResponse

object

Property	Type	Required
`pickup_estimated_time`	`integer`	—
`destination_estimated_time`	`integer`	—
`total_estimated_time`	`integer`	—
`delivery_price`	`number` (float)	—
`delivery_price_text`	`string`	—
`vat_price`	`number` (float)	—
`vat_price_text`	`string`	—

DispatchPayload

object

Property	Type	Required
`payload_type`	`string`	—
`payload`	`object`	—