Dispatch Module

OAS 3.1.0 v1.2.0 ✓ Valid 3.1
specs/dispatch-module.yaml • 9 operations • 13 schemas • 1 webhooks
⬇ Download .yaml
Add Operation / Endpoint

POST /ext/dispatch
Summary
operationId
GET /ext/dispatches/d/{driver_id}
Summary
operationId
Parameters
GET /ext/dispatches
Summary
operationId
GET /ext/dispatch/{id}
Summary
operationId
Parameters
POST /ext/dispatch/{id}/status
Summary
operationId
Parameters
PATCH /ext/dispatch/{id}/pickup
Summary
operationId
Parameters
PATCH /ext/dispatch/{id}/destination
Summary
operationId
Parameters
POST /ext/estimate
Summary
operationId
POST /ext/webhook
Summary
operationId
openapi: 3.1.0
info:
  title: Dispatch Module
  description: ""
  version: 1.2.0
servers:
  - url: https://dev.hubz.nyotek.com

paths:
  /ext/dispatch:
    post:
      tags:
        - Dispatch
      summary: Create a new dispatch request
      description: Create a new dispatch request with a pickup and delivery address
      operationId: createDispatch
      requestBody:
        description: Create a new dispatch
        content:
          application/json:
            schema:
              type: object
              required:
                - pickup
                - destination
                - user_metadata
                - vendor_id
                - vendor_name
                - vendor_oid
                - vendor_bid
              properties:
                pickup:
                  type: object
                  required:
                    - lat
                    - lng
                  properties:
                    ref_id:
                      type: string
                      description: Unique identifier for an address
                      examples:
                        - b93d16aa-e34d-4c65-b6ef-acdcca470615
                    lat:
                      type: number
                      format: double
                      examples:
                        - 24.712181
                    lng:
                      type: number
                      format: double
                      examples:
                        - 46.679747
                    address_line:
                      type: string
                      examples:
                        - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
                destination:
                  type: object
                  required:
                    - lat
                    - lng
                  properties:
                    ref_id:
                      type: string
                      description: Unique identifier for an address
                      examples:
                        - b93d16aa-e34d-4c65-b6ef-acdcca470615
                    lat:
                      type: number
                      format: double
                      examples:
                        - 24.712181
                    lng:
                      type: number
                      format: double
                      examples:
                        - 46.679747
                    address_line:
                      type: string
                      examples:
                        - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
                user_metadata:
                  type: object
                  required:
                    - id
                    - email
                    - phone
                  properties:
                    id:
                      type: string
                      description: unique identifier for a user
                      examples:
                        - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                    username:
                      type: string
                      examples:
                        - theUser
                    firstName:
                      type: string
                      examples:
                        - John
                    lastName:
                      type: string
                      examples:
                        - James
                    email:
                      type: string
                      examples:
                        - john@email.com
                    phone:
                      type: string
                      examples:
                        - +9669876654321
                vendor_logo_url:
                  type: string
                  description: restaurant logo url
                  examples:
                    - https://picsum.photos/200/300
                vendor_id:
                  type: string
                  description: Restaurant unique identifier
                  examples:
                    - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                vendor_name:
                  type: object
                  description: locale based text objects
                  required:
                    - en-us
                  additionalProperties:
                    type: string
                    en-us:
                      type: string
                  examples:
                    - en-us: English based text
                      ar-sa: جملة عربية
                vendor_oid:
                  type: string
                  description: unique order identifier
                  examples:
                    - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                vendor_sid:
                  type: string
                  description: unique short readable identifier
                  examples:
                    - 15EEDFRG
                vendor_bid:
                  type: string
                  description: unique restaurant branch identifier
                  examples:
                    - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                vendor_payload:
                  type: object
                  properties:
                    pickup_wait_time:
                      type: integer
                      description: wait time at the pickup/restaurant
                      examples:
                        - 20
                    order_price:
                      type: number
                      format: float
                      examples:
                        - 123.65
        required: true
      responses:
        "201":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: unique identifier of a dispatch
                        examples:
                          - 01HQ0PV32FMRA1XGT609QFV2VJ
        "400":
          description: if a dispatch with a an existing order/vendor_oid exists
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
        "401":
          description: Unauthorized if incorrect api_key is given
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
        "500":
          description: any other errors from the server
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
      security:
        - api_key: []
  /ext/dispatches/d/{driver_id}:
    get:
      tags:
        - Dispatch
      summary: Fetch dispatches by driver id
      description: Fetch all the dispatches by assigned driver id
      operationId: fetchDispatchesByDriverId
      parameters:
        - name: driver_id
          in: path
          description: driver id to use
          required: true
          schema:
            type: string
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: uniques identifier for a dispatch
                          examples:
                            - 01HQ0PV32FMRA1XGT609QFV2VJ
                        created_at:
                          type: string
                          description: dispatch created at timestamp
                        modified_at:
                          type: string
                          description: dispatch modified at timestamp
                        r_id:
                          type: string
                          description: short/readable identifier for a dispatch
                          examples:
                            - DYJ7XZ7
                        assigned_driver_id:
                          type: string
                          description: unique identifier of a driver assigned to a dispatch
                          examples:
                            - 01HQ0PV32FMRA1XGT609QFV2VJ
                        pickup:
                          type: object
                          required:
                            - lat
                            - lng
                          properties:
                            ref_id:
                              type: string
                              description: Unique identifier for an address
                              examples:
                                - b93d16aa-e34d-4c65-b6ef-acdcca470615
                            lat:
                              type: number
                              format: double
                              examples:
                                - 24.712181
                            lng:
                              type: number
                              format: double
                              examples:
                                - 46.679747
                            address_line:
                              type: string
                              examples:
                                - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
                        destination:
                          type: object
                          required:
                            - lat
                            - lng
                          properties:
                            ref_id:
                              type: string
                              description: Unique identifier for an address
                              examples:
                                - b93d16aa-e34d-4c65-b6ef-acdcca470615
                            lat:
                              type: number
                              format: double
                              examples:
                                - 24.712181
                            lng:
                              type: number
                              format: double
                              examples:
                                - 46.679747
                            address_line:
                              type: string
                              examples:
                                - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
                        user_metadata:
                          type: object
                          required:
                            - id
                            - email
                            - phone
                          properties:
                            id:
                              type: string
                              description: unique identifier for a user
                              examples:
                                - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                            username:
                              type: string
                              examples:
                                - theUser
                            firstName:
                              type: string
                              examples:
                                - John
                            lastName:
                              type: string
                              examples:
                                - James
                            email:
                              type: string
                              examples:
                                - john@email.com
                            phone:
                              type: string
                              examples:
                                - +9669876654321
                        vendor_logo_url:
                          type: string
                          description: restaurant logo url
                          examples:
                            - https://picsum.photos/200/300
                        vendor_id:
                          type: string
                          description: Restaurant unique identifier
                          examples:
                            - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                            - 01HQ0PV32FMRA1XGT609QFV2VJ
                        vendor_name:
                          type: object
                          description: locale based text objects
                          required:
                            - en-us
                          additionalProperties:
                            type: string
                            en-us:
                              type: string
                          examples:
                            - en-us: English based text
                              ar-sa: جملة عربية
                        vendor_oid:
                          type: string
                          description: unique order identifier
                          examples:
                            - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                            - 01HQ0PV32FMRA1XGT609QFV2VJ
                        vendor_sid:
                          type: string
                          description: unique short readable identifier
                          examples:
                            - 15EEDFRG
                        vendor_bid:
                          type: string
                          description: unique restaurant branch identifier
                          examples:
                            - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                            - 01HQ0PV32FMRA1XGT609QFV2VJ
                        media_url:
                          type: object
                          description: media urls for any photos/videos taken by the driver upon delivery
                          additionalProperties:
                            type: string
                          examples:
                            - "1": https://picsum.photos/200/300
                              "2": https://picsum.photos/200/400
                        status:
                          type: array
                          items:
                            type: object
                            properties:
                              status:
                                type: string
                                description: status of a dispatch
                                enum:
                                  - accepted
                                  - new
                                  - picked_up
                                  - assigned
                                  - ready_for_pickup
                                  - dispatch_rejected
                                  - dispatch_accepted
                                  - cancelled
                                  - qa_qc
                                  - delivered
                              status_captured_time:
                                type: string
                                description: timestamp of when the dispatch was updated
                                examples:
                                  - "2024-02-28 12:05:24.992"
                              ref_id:
                                type: string
                                description: unique identifier represented by ref_type
                                examples:
                                  - 01HQ0PV32FMRA1XGT609QFV2VJ
                              ref_type:
                                type: string
                                description: actor/resource type
                                examples:
                                  - user
        "401":
          description: Unauthorized if incorrect api_key is given
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
        "500":
          description: any other errors from the server
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
      security:
        - api_key: []
  /ext/dispatches:
    get:
      tags:
        - Dispatch
      summary: Fetch all dispatches
      description: Fetch all the dispatches
      operationId: fetchAllDispatches
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          description: uniques identifier for a dispatch
                          examples:
                            - 01HQ0PV32FMRA1XGT609QFV2VJ
                        created_at:
                          type: string
                          description: dispatch created at timestamp
                        modified_at:
                          type: string
                          description: dispatch modified at timestamp
                        r_id:
                          type: string
                          description: short/readable identifier for a dispatch
                          examples:
                            - DYJ7XZ7
                        assigned_driver_id:
                          type: string
                          description: unique identifier of a driver assigned to a dispatch
                          examples:
                            - 01HQ0PV32FMRA1XGT609QFV2VJ
                        pickup:
                          type: object
                          required:
                            - lat
                            - lng
                          properties:
                            ref_id:
                              type: string
                              description: Unique identifier for an address
                              examples:
                                - b93d16aa-e34d-4c65-b6ef-acdcca470615
                            lat:
                              type: number
                              format: double
                              examples:
                                - 24.712181
                            lng:
                              type: number
                              format: double
                              examples:
                                - 46.679747
                            address_line:
                              type: string
                              examples:
                                - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
                        destination:
                          type: object
                          required:
                            - lat
                            - lng
                          properties:
                            ref_id:
                              type: string
                              description: Unique identifier for an address
                              examples:
                                - b93d16aa-e34d-4c65-b6ef-acdcca470615
                            lat:
                              type: number
                              format: double
                              examples:
                                - 24.712181
                            lng:
                              type: number
                              format: double
                              examples:
                                - 46.679747
                            address_line:
                              type: string
                              examples:
                                - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
                        user_metadata:
                          type: object
                          required:
                            - id
                            - email
                            - phone
                          properties:
                            id:
                              type: string
                              description: unique identifier for a user
                              examples:
                                - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                            username:
                              type: string
                              examples:
                                - theUser
                            firstName:
                              type: string
                              examples:
                                - John
                            lastName:
                              type: string
                              examples:
                                - James
                            email:
                              type: string
                              examples:
                                - john@email.com
                            phone:
                              type: string
                              examples:
                                - +9669876654321
                        vendor_logo_url:
                          type: string
                          description: restaurant logo url
                          examples:
                            - https://picsum.photos/200/300
                        vendor_id:
                          type: string
                          description: Restaurant unique identifier
                          examples:
                            - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                            - 01HQ0PV32FMRA1XGT609QFV2VJ
                        vendor_name:
                          type: object
                          description: locale based text objects
                          required:
                            - en-us
                          additionalProperties:
                            type: string
                            en-us:
                              type: string
                          examples:
                            - en-us: English based text
                              ar-sa: جملة عربية
                        vendor_oid:
                          type: string
                          description: unique order identifier
                          examples:
                            - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                            - 01HQ0PV32FMRA1XGT609QFV2VJ
                        vendor_sid:
                          type: string
                          description: unique short readable identifier
                          examples:
                            - 15EEDFRG
                        vendor_bid:
                          type: string
                          description: unique restaurant branch identifier
                          examples:
                            - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                            - 01HQ0PV32FMRA1XGT609QFV2VJ
                        media_url:
                          type: object
                          description: media urls for any photos/videos taken by the driver upon delivery
                          additionalProperties:
                            type: string
                          examples:
                            - "1": https://picsum.photos/200/300
                              "2": https://picsum.photos/200/400
                        status:
                          type: array
                          items:
                            type: object
                            properties:
                              status:
                                type: string
                                description: status of a dispatch
                                enum:
                                  - accepted
                                  - new
                                  - picked_up
                                  - assigned
                                  - ready_for_pickup
                                  - dispatch_rejected
                                  - dispatch_accepted
                                  - cancelled
                                  - qa_qc
                                  - delivered
                              status_captured_time:
                                type: string
                                description: timestamp of when the dispatch was updated
                                examples:
                                  - "2024-02-28 12:05:24.992"
                              ref_id:
                                type: string
                                description: unique identifier represented by ref_type
                                examples:
                                  - 01HQ0PV32FMRA1XGT609QFV2VJ
                              ref_type:
                                type: string
                                description: actor/resource type
                                examples:
                                  - user
        "401":
          description: Unauthorized if incorrect api_key is given
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
        "500":
          description: any other errors from the server
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
      security:
        - api_key: []
  /ext/dispatch/{id}:
    get:
      tags:
        - Dispatch
      summary: Fetch a dispatch
      description: Fetch a dispatch
      operationId: fetchDispatch
      parameters:
        - name: id
          in: path
          description: ID of the dispatch to use
          required: true
          schema:
            type: string
      responses:
        "200":
          description: successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      id:
                        type: string
                        description: uniques identifier for a dispatch
                        examples:
                          - 01HQ0PV32FMRA1XGT609QFV2VJ
                      created_at:
                        type: string
                        description: dispatch created at timestamp
                      modified_at:
                        type: string
                        description: dispatch modified at timestamp
                      r_id:
                        type: string
                        description: short/readable identifier for a dispatch
                        examples:
                          - DYJ7XZ7
                      assigned_driver_id:
                        type: string
                        description: unique identifier of a driver assigned to a dispatch
                        examples:
                          - 01HQ0PV32FMRA1XGT609QFV2VJ
                      pickup:
                        type: object
                        required:
                          - lat
                          - lng
                        properties:
                          ref_id:
                            type: string
                            description: Unique identifier for an address
                            examples:
                              - b93d16aa-e34d-4c65-b6ef-acdcca470615
                          lat:
                            type: number
                            format: double
                            examples:
                              - 24.712181
                          lng:
                            type: number
                            format: double
                            examples:
                              - 46.679747
                          address_line:
                            type: string
                            examples:
                              - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
                      destination:
                        type: object
                        required:
                          - lat
                          - lng
                        properties:
                          ref_id:
                            type: string
                            description: Unique identifier for an address
                            examples:
                              - b93d16aa-e34d-4c65-b6ef-acdcca470615
                          lat:
                            type: number
                            format: double
                            examples:
                              - 24.712181
                          lng:
                            type: number
                            format: double
                            examples:
                              - 46.679747
                          address_line:
                            type: string
                            examples:
                              - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
                      user_metadata:
                        type: object
                        required:
                          - id
                          - email
                          - phone
                        properties:
                          id:
                            type: string
                            description: unique identifier for a user
                            examples:
                              - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                          username:
                            type: string
                            examples:
                              - theUser
                          firstName:
                            type: string
                            examples:
                              - John
                          lastName:
                            type: string
                            examples:
                              - James
                          email:
                            type: string
                            examples:
                              - john@email.com
                          phone:
                            type: string
                            examples:
                              - +9669876654321
                      vendor_logo_url:
                        type: string
                        description: restaurant logo url
                        examples:
                          - https://picsum.photos/200/300
                      vendor_id:
                        type: string
                        description: Restaurant unique identifier
                        examples:
                          - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                          - 01HQ0PV32FMRA1XGT609QFV2VJ
                      vendor_name:
                        type: object
                        description: locale based text objects
                        required:
                          - en-us
                        additionalProperties:
                          type: string
                          en-us:
                            type: string
                        examples:
                          - en-us: English based text
                            ar-sa: جملة عربية
                      vendor_oid:
                        type: string
                        description: unique order identifier
                        examples:
                          - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                          - 01HQ0PV32FMRA1XGT609QFV2VJ
                      vendor_sid:
                        type: string
                        description: unique short readable identifier
                        examples:
                          - 15EEDFRG
                      vendor_bid:
                        type: string
                        description: unique restaurant branch identifier
                        examples:
                          - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                          - 01HQ0PV32FMRA1XGT609QFV2VJ
                      media_url:
                        type: object
                        description: media urls for any photos/videos taken by the driver upon delivery
                        additionalProperties:
                          type: string
                        examples:
                          - "1": https://picsum.photos/200/300
                            "2": https://picsum.photos/200/400
                      status:
                        type: array
                        items:
                          type: object
                          properties:
                            status:
                              type: string
                              description: status of a dispatch
                              enum:
                                - accepted
                                - new
                                - picked_up
                                - assigned
                                - ready_for_pickup
                                - dispatch_rejected
                                - dispatch_accepted
                                - cancelled
                                - qa_qc
                                - delivered
                            status_captured_time:
                              type: string
                              description: timestamp of when the dispatch was updated
                              examples:
                                - "2024-02-28 12:05:24.992"
                            ref_id:
                              type: string
                              description: unique identifier represented by ref_type
                              examples:
                                - 01HQ0PV32FMRA1XGT609QFV2VJ
                            ref_type:
                              type: string
                              description: actor/resource type
                              examples:
                                - user
        "401":
          description: Unauthorized if incorrect api_key is given
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
        "500":
          description: any other errors from the server
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
      security:
        - api_key: []
  /ext/dispatch/{id}/status:
    post:
      tags:
        - Dispatch
      summary: Cancel a dispatch
      description: cancel an existing dispatch
      operationId: cancelDispatch
      parameters:
        - name: id
          in: path
          description: ID of the dispatch to use
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  description: cancelled status input
                  enum:
                    - cancelled
                ref_id:
                  type: string
                  description: unique identifier of the user cancelling a dispatch
                  examples:
                    - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                    - 01HQ0PV32FMRA1XGT609QFV2VJ
                ref_type:
                  type: string
                  enum:
                    - user
      responses:
        "204":
          description: successful operation
        "401":
          description: Unauthorized if incorrect api_key is given
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
        "404":
          description: if the dispatch id is not found in the system
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
        "500":
          description: any other errors from the server
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
      security:
        - api_key: []
  /ext/dispatch/{id}/pickup:
    patch:
      tags:
        - Dispatch
      summary: Update pickup address
      description: update pickup address of an existing dispatch
      operationId: updateDispatchPickup
      parameters:
        - name: id
          in: path
          description: ID of the dispatch to use
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - lat
                - lng
              properties:
                ref_id:
                  type: string
                  description: Unique identifier for an address
                  examples:
                    - b93d16aa-e34d-4c65-b6ef-acdcca470615
                lat:
                  type: number
                  format: double
                  examples:
                    - 24.712181
                lng:
                  type: number
                  format: double
                  examples:
                    - 46.679747
                address_line:
                  type: string
                  examples:
                    - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
      responses:
        "204":
          description: successful operation
        "401":
          description: Unauthorized if incorrect api_key is given
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
        "404":
          description: if the dispatch id is not found in the system
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
        "500":
          description: any other errors from the server
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
      security:
        - api_key: []
  /ext/dispatch/{id}/destination:
    patch:
      tags:
        - Dispatch
      summary: Update destination address
      description: update destination address of an existing dispatch
      operationId: updateDispatchDestination
      parameters:
        - name: id
          in: path
          description: ID of the dispatch to use
          required: true
          schema:
            type: string
      requestBody:
        content:
          application/json:
            schema:
              type: object
              required:
                - lat
                - lng
              properties:
                ref_id:
                  type: string
                  description: Unique identifier for an address
                  examples:
                    - b93d16aa-e34d-4c65-b6ef-acdcca470615
                lat:
                  type: number
                  format: double
                  examples:
                    - 24.712181
                lng:
                  type: number
                  format: double
                  examples:
                    - 46.679747
                address_line:
                  type: string
                  examples:
                    - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
      responses:
        "204":
          description: successful operation
        "401":
          description: Unauthorized if incorrect api_key is given
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
        "404":
          description: if the dispatch id is not found in the system
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
        "500":
          description: any other errors from the server
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
      security:
        - api_key: []
  /ext/estimate:
    post:
      tags:
        - Dispatch
      summary: Request delivery estimates
      description: request delivery estimates for a new dispatch
      operationId: estimateDispatch
      requestBody:
        description: to fetch estimated wait times and delivery prices
        content:
          application/json:
            schema:
              type: object
              required:
                - pickup
                - destination
              properties:
                pickup:
                  type: object
                  required:
                    - lat
                    - lng
                  properties:
                    ref_id:
                      type: string
                      description: Unique identifier for an address
                      examples:
                        - b93d16aa-e34d-4c65-b6ef-acdcca470615
                    lat:
                      type: number
                      format: double
                      examples:
                        - 24.712181
                    lng:
                      type: number
                      format: double
                      examples:
                        - 46.679747
                    address_line:
                      type: string
                      examples:
                        - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
                destination:
                  type: object
                  required:
                    - lat
                    - lng
                  properties:
                    ref_id:
                      type: string
                      description: Unique identifier for an address
                      examples:
                        - b93d16aa-e34d-4c65-b6ef-acdcca470615
                    lat:
                      type: number
                      format: double
                      examples:
                        - 24.712181
                    lng:
                      type: number
                      format: double
                      examples:
                        - 46.679747
                    address_line:
                      type: string
                      examples:
                        - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
                pickup_wait_time:
                  type: integer
                  description: wait time of a restaurant in minutes
                  examples:
                    - 20
                    - 25
        required: true
      responses:
        "200":
          description: Successful operation
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      pickup_estimated_time:
                        type: integer
                        description: estimated time to a restaurant in minutes
                        examples:
                          - 20
                          - 25
                      destination_estimated_time:
                        type: integer
                        description: estimated time from pickup tp destination in minutes
                        examples:
                          - 20
                          - 25
                      total_estimated_time:
                        type: integer
                        description: total estimated time including pickup wait time in minutes
                        examples:
                          - 20
                          - 25
                      delivery_price:
                        type: number
                        format: float
                      delivery_price_text:
                        type: string
                        description: delivery price including the currency symbol
                      vat_price:
                        type: number
                        format: float
                      vat_price_text:
                        type: string
                        description: vat price including the currency symbol
        "401":
          description: Unauthorized if incorrect api_key is given
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
        "500":
          description: any other errors from the server
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: generic information about the error
                    examples:
                      - generic error
                  error_desc:
                    type: string
                    description: error information for the developer
                    examples:
                      - identifier 45 not found
      security:
        - api_key: []
  /ext/webhook:
    post:
      tags:
        - RegisterWebhook
      summary: Register a webhook
      description: register a webhook to get updates from dispatch or ETAs
      operationId: registerWebhook
      requestBody:
        description: to register a webhook url
        content:
          application/json:
            schema:
              type: object
              properties:
                webhook:
                  type: string
                  description: webhook url to register. This url must be active and should send back a 200 status code
                  examples:
                    - "https://host.com/webhook"
        required: true
      responses:
        '204':
          description: Successful operation
        '401':
          description: Unauthorized if incorrect api_key is given
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '400':
          description: bad request if the url is invalid or will not respond with a 200 status code. 
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: any other errors from the server
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - api_key: []

webhooks:
  statusUpdates:
    post:
      tags:
        - StatusUpdates
      requestBody:
        description: status updates for a dispatch id
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DispatchPayload'
      responses:
        "200":
          description: Return a 200 status to indicate that the data was received successfully
components:
  schemas:
    LocaleTextObject:
      type: object
      description: locale based text objects
      required:
        - en-us
      additionalProperties:
        type: string
        en-us:
          type: string
      examples:
        - en-us: English based text
          ar-sa: جملة عربية
    Address:
      type: object
      required:
        - lat
        - lng
      properties:
        ref_id:
          type: string
          description: Unique identifier for an address
          examples:
            - b93d16aa-e34d-4c65-b6ef-acdcca470615
        lat:
          type: number
          format: double
          examples:
            - 24.712181
        lng:
          type: number
          format: double
          examples:
            - 46.679747
        address_line:
          type: string
          examples:
            - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
    User:
      type: object
      required:
        - id
        - email
        - phone
      properties:
        id:
          type: string
          description: unique identifier for a user
          examples:
            - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
        username:
          type: string
          examples:
            - theUser
        firstName:
          type: string
          examples:
            - John
        lastName:
          type: string
          examples:
            - James
        email:
          type: string
          examples:
            - john@email.com
        phone:
          type: string
          examples:
            - +9669876654321
    VendorPayload:
      type: object
      properties:
        pickup_wait_time:
          type: integer
          description: wait time at the pickup/restaurant
          examples:
            - 20
        order_price:
          type: number
          format: float
          examples:
            - 123.65
    DispatchRequest:
      type: object
      required:
        - pickup
        - destination
        - user_metadata
        - vendor_id
        - vendor_name
        - vendor_oid
        - vendor_bid
      properties:
        pickup:
          type: object
          required:
            - lat
            - lng
          properties:
            ref_id:
              type: string
              description: Unique identifier for an address
              examples:
                - b93d16aa-e34d-4c65-b6ef-acdcca470615
            lat:
              type: number
              format: double
              examples:
                - 24.712181
            lng:
              type: number
              format: double
              examples:
                - 46.679747
            address_line:
              type: string
              examples:
                - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
        destination:
          type: object
          required:
            - lat
            - lng
          properties:
            ref_id:
              type: string
              description: Unique identifier for an address
              examples:
                - b93d16aa-e34d-4c65-b6ef-acdcca470615
            lat:
              type: number
              format: double
              examples:
                - 24.712181
            lng:
              type: number
              format: double
              examples:
                - 46.679747
            address_line:
              type: string
              examples:
                - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
        user_metadata:
          type: object
          required:
            - id
            - email
            - phone
          properties:
            id:
              type: string
              description: unique identifier for a user
              examples:
                - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
            username:
              type: string
              examples:
                - theUser
            firstName:
              type: string
              examples:
                - John
            lastName:
              type: string
              examples:
                - James
            email:
              type: string
              examples:
                - john@email.com
            phone:
              type: string
              examples:
                - +9669876654321
        vendor_logo_url:
          type: string
          description: restaurant logo url
          examples:
            - https://picsum.photos/200/300
        vendor_id:
          type: string
          description: Restaurant unique identifier
          examples:
            - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
        vendor_name:
          type: object
          description: locale based text objects
          required:
            - en-us
          additionalProperties:
            type: string
            en-us:
              type: string
          examples:
            - en-us: English based text
              ar-sa: جملة عربية
        vendor_oid:
          type: string
          description: unique order identifier
          examples:
            - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
        vendor_sid:
          type: string
          description: unique short readable identifier
          examples:
            - 15EEDFRG
        vendor_bid:
          type: string
          description: unique restaurant branch identifier
          examples:
            - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
        vendor_payload:
          type: object
          properties:
            pickup_wait_time:
              type: integer
              description: wait time at the pickup/restaurant
              examples:
                - 20
            order_price:
              type: number
              format: float
              examples:
                - 123.65
    DispatchResponse:
      type: object
      properties:
        id:
          type: string
          description: unique identifier of a dispatch
          examples:
            - 01HQ0PV32FMRA1XGT609QFV2VJ
    ErrorResponse:
      type: object
      properties:
        error:
          type: string
          description: generic information about the error
          examples:
            - generic error
        error_desc:
          type: string
          description: error information for the developer
          examples:
            - identifier 45 not found
    DispatchUnit:
      type: object
      properties:
        id:
          type: string
          description: uniques identifier for a dispatch
          examples:
            - 01HQ0PV32FMRA1XGT609QFV2VJ
        created_at:
          type: string
          description: dispatch created at timestamp
        modified_at:
          type: string
          description: dispatch modified at timestamp
        r_id:
          type: string
          description: short/readable identifier for a dispatch
          examples:
            - DYJ7XZ7
        assigned_driver_id:
          type: string
          description: unique identifier of a driver assigned to a dispatch
          examples:
            - 01HQ0PV32FMRA1XGT609QFV2VJ
        pickup:
          type: object
          required:
            - lat
            - lng
          properties:
            ref_id:
              type: string
              description: Unique identifier for an address
              examples:
                - b93d16aa-e34d-4c65-b6ef-acdcca470615
            lat:
              type: number
              format: double
              examples:
                - 24.712181
            lng:
              type: number
              format: double
              examples:
                - 46.679747
            address_line:
              type: string
              examples:
                - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
        destination:
          type: object
          required:
            - lat
            - lng
          properties:
            ref_id:
              type: string
              description: Unique identifier for an address
              examples:
                - b93d16aa-e34d-4c65-b6ef-acdcca470615
            lat:
              type: number
              format: double
              examples:
                - 24.712181
            lng:
              type: number
              format: double
              examples:
                - 46.679747
            address_line:
              type: string
              examples:
                - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
        user_metadata:
          type: object
          required:
            - id
            - email
            - phone
          properties:
            id:
              type: string
              description: unique identifier for a user
              examples:
                - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
            username:
              type: string
              examples:
                - theUser
            firstName:
              type: string
              examples:
                - John
            lastName:
              type: string
              examples:
                - James
            email:
              type: string
              examples:
                - john@email.com
            phone:
              type: string
              examples:
                - +9669876654321
        vendor_logo_url:
          type: string
          description: restaurant logo url
          examples:
            - https://picsum.photos/200/300
        vendor_id:
          type: string
          description: Restaurant unique identifier
          examples:
            - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
            - 01HQ0PV32FMRA1XGT609QFV2VJ
        vendor_name:
          type: object
          description: locale based text objects
          required:
            - en-us
          additionalProperties:
            type: string
            en-us:
              type: string
          examples:
            - en-us: English based text
              ar-sa: جملة عربية
        vendor_oid:
          type: string
          description: unique order identifier
          examples:
            - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
            - 01HQ0PV32FMRA1XGT609QFV2VJ
        vendor_sid:
          type: string
          description: unique short readable identifier
          examples:
            - 15EEDFRG
        vendor_bid:
          type: string
          description: unique restaurant branch identifier
          examples:
            - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
            - 01HQ0PV32FMRA1XGT609QFV2VJ
        media_url:
          type: object
          description: media urls for any photos/videos taken by the driver upon delivery
          additionalProperties:
            type: string
          examples:
            - "1": https://picsum.photos/200/300
              "2": https://picsum.photos/200/400
        status:
          type: array
          items:
            type: object
            properties:
              status:
                type: string
                description: status of a dispatch
                enum:
                  - accepted
                  - new
                  - picked_up
                  - assigned
                  - ready_for_pickup
                  - dispatch_rejected
                  - dispatch_accepted
                  - cancelled
                  - qa_qc
                  - delivered
              status_captured_time:
                type: string
                description: timestamp of when the dispatch was updated
                examples:
                  - "2024-02-28 12:05:24.992"
              ref_id:
                type: string
                description: unique identifier represented by ref_type
                examples:
                  - 01HQ0PV32FMRA1XGT609QFV2VJ
              ref_type:
                type: string
                description: actor/resource type
                examples:
                  - user
    DispatchStatus:
      type: object
      properties:
        status:
          type: string
          description: status of a dispatch
          enum:
            - accepted
            - new
            - picked_up
            - assigned
            - ready_for_pickup
            - dispatch_rejected
            - dispatch_accepted
            - cancelled
            - qa_qc
            - delivered
        status_captured_time:
          type: string
          description: timestamp of when the dispatch was updated
          examples:
            - "2024-02-28 12:05:24.992"
        ref_id:
          type: string
          description: unique identifier represented by ref_type
          examples:
            - 01HQ0PV32FMRA1XGT609QFV2VJ
        ref_type:
          type: string
          description: actor/resource type
          examples:
            - user
    CancelDispatch:
      type: object
      properties:
        status:
          type: string
          description: cancelled status input
          enum:
            - cancelled
        ref_id:
          type: string
          description: unique identifier of the user cancelling a dispatch
          examples:
            - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
            - 01HQ0PV32FMRA1XGT609QFV2VJ
        ref_type:
          type: string
          enum:
            - user
    EstimateRequest:
      type: object
      required:
        - pickup
        - destination
      properties:
        pickup:
          type: object
          required:
            - lat
            - lng
          properties:
            ref_id:
              type: string
              description: Unique identifier for an address
              examples:
                - b93d16aa-e34d-4c65-b6ef-acdcca470615
            lat:
              type: number
              format: double
              examples:
                - 24.712181
            lng:
              type: number
              format: double
              examples:
                - 46.679747
            address_line:
              type: string
              examples:
                - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
        destination:
          type: object
          required:
            - lat
            - lng
          properties:
            ref_id:
              type: string
              description: Unique identifier for an address
              examples:
                - b93d16aa-e34d-4c65-b6ef-acdcca470615
            lat:
              type: number
              format: double
              examples:
                - 24.712181
            lng:
              type: number
              format: double
              examples:
                - 46.679747
            address_line:
              type: string
              examples:
                - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
        pickup_wait_time:
          type: integer
          description: wait time of a restaurant in minutes
          examples:
            - 20
            - 25
    EstimateResponse:
      type: object
      properties:
        pickup_estimated_time:
          type: integer
          description: estimated time to a restaurant in minutes
          examples:
            - 20
            - 25
        destination_estimated_time:
          type: integer
          description: estimated time from pickup tp destination in minutes
          examples:
            - 20
            - 25
        total_estimated_time:
          type: integer
          description: total estimated time including pickup wait time in minutes
          examples:
            - 20
            - 25
        delivery_price:
          type: number
          format: float
        delivery_price_text:
          type: string
          description: delivery price including the currency symbol
        vat_price:
          type: number
          format: float
        vat_price_text:
          type: string
          description: vat price including the currency symbol
    DispatchPayload:
      type: object
      properties:
        payload_type:
          type: string
          description: type of payload received
          enum:
            - status_update
        payload:
          type: object
          properties:
            id:
              type: string
              description: uniques identifier for a dispatch
              examples:
                - 01HQ0PV32FMRA1XGT609QFV2VJ
            status:
              type: string
              description: status of a dispatch
              enum:
                - accepted
                - new
                - picked_up
                - assigned
                - ready_for_pickup
                - dispatch_rejected
                - dispatch_accepted
                - cancelled
                - qa_qc
                - delivered
            status_captured_time:
              type: string
              description: timestamp of when the dispatch was updated
              examples:
                - "2024-02-28 12:05:24.992"
            ref_id:
              type: string
              description: unique identifier represented by ref_type
              examples:
                - 01HQ0PV32FMRA1XGT609QFV2VJ
            ref_type:
              type: string
              description: actor/resource type
              examples:
                - user
            vendor_oid:
              type: string
              description: unique order identifier
              examples:
                - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                - 01HQ0PV32FMRA1XGT609QFV2VJ
            vendor_sid:
              type: string
              description: unique short readable identifier
              examples:
                - 15EEDFRG
            vendor_id:
              type: string
              description: Restaurant unique identifier
              examples:
                - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                - 01HQ0PV32FMRA1XGT609QFV2VJ
  requestBodies:
    Dispatch:
      description: Dispatch object
      content:
        application/json:
          schema:
            type: object
            required:
              - pickup
              - destination
              - user_metadata
              - vendor_id
              - vendor_name
              - vendor_oid
              - vendor_bid
            properties:
              pickup:
                type: object
                required:
                  - lat
                  - lng
                properties:
                  ref_id:
                    type: string
                    description: Unique identifier for an address
                    examples:
                      - b93d16aa-e34d-4c65-b6ef-acdcca470615
                  lat:
                    type: number
                    format: double
                    examples:
                      - 24.712181
                  lng:
                    type: number
                    format: double
                    examples:
                      - 46.679747
                  address_line:
                    type: string
                    examples:
                      - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
              destination:
                type: object
                required:
                  - lat
                  - lng
                properties:
                  ref_id:
                    type: string
                    description: Unique identifier for an address
                    examples:
                      - b93d16aa-e34d-4c65-b6ef-acdcca470615
                  lat:
                    type: number
                    format: double
                    examples:
                      - 24.712181
                  lng:
                    type: number
                    format: double
                    examples:
                      - 46.679747
                  address_line:
                    type: string
                    examples:
                      - "ابي البدر الموسوي, As Sulimaniyah, Riyadh 12244, Saudi Arabia"
              user_metadata:
                type: object
                required:
                  - id
                  - email
                  - phone
                properties:
                  id:
                    type: string
                    description: unique identifier for a user
                    examples:
                      - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
                  username:
                    type: string
                    examples:
                      - theUser
                  firstName:
                    type: string
                    examples:
                      - John
                  lastName:
                    type: string
                    examples:
                      - James
                  email:
                    type: string
                    examples:
                      - john@email.com
                  phone:
                    type: string
                    examples:
                      - +9669876654321
              vendor_logo_url:
                type: string
                description: restaurant logo url
                examples:
                  - https://picsum.photos/200/300
              vendor_id:
                type: string
                description: Restaurant unique identifier
                examples:
                  - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
              vendor_name:
                type: object
                description: locale based text objects
                required:
                  - en-us
                additionalProperties:
                  type: string
                  en-us:
                    type: string
                examples:
                  - en-us: English based text
                    ar-sa: جملة عربية
              vendor_oid:
                type: string
                description: unique order identifier
                examples:
                  - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
              vendor_sid:
                type: string
                description: unique short readable identifier
                examples:
                  - 15EEDFRG
              vendor_bid:
                type: string
                description: unique restaurant branch identifier
                examples:
                  - 15ed2668-f118-40c3-a52c-8ad90fe11ed7
              vendor_payload:
                type: object
                properties:
                  pickup_wait_time:
                    type: integer
                    description: wait time at the pickup/restaurant
                    examples:
                      - 20
                  order_price:
                    type: number
                    format: float
                    examples:
                      - 123.65
  securitySchemes:
    api_key:
      type: apiKey
      name: api_key
      in: query

tags:
  - name: Dispatch
    description: Everything related to Dispatch/Delivery APIs
  - name: RegisterWebhook
    description: API related to the registration of webhook url for status updates
  - name: StatusUpdates
    description: Webhook payload received for dispatch status updates
OpenAPI 3.1 Validator & Linter (0 findings) ✓ Specification is valid OpenAPI 3.1.0
No validation errors or warnings found.