docs/order_api.md

NINJA Order API v1.1.0

The NINJA order API allows you to create and query orders on DispatchNINJA delivery installs.

Requirements

In order to use this API you must have a user account with the delivery install that you wish to push orders to, along with a public/private API key pair. Please contact: tech@dispatchninja.com if you have not been supplied with this information.

Endpoints

The API is accessed by making requests to endpoints that conform to the following format:

https://DOMAIN/dn_api/API_VERSION/APP/TASK

For example, to create an order on the development install, you would make a request to:

https://dev.dispatchninja.com/dn_api/1.1.0/orders/add

Authentication

To authenticate requests, you must pass your public API key in the X-API-KEY request header field.

POST Request Body

Post requests must contain URLencoded Form Data and include all of the required fields for a given task.

Creating an Order

Request

Orders are created by making a POST request to /orders/add containing the following fields:

Field	Required	Description
client_name	✓	Name of organization or person at pickup address
client_address	✓	Pickup address
customer_name	✓	Name of person or organization at delivery address
customer_address	✓	Delivery address
customer_email	✗	Email for person or organization at delivery address
customer_phone	✗	Phone for person or organization at delivery address
comments	✗	A description of the delivery contents and any other pertinent information

Response

The response is a JSON object containing the following fields indicating success or failure as well as the order_id. This value should be saved in order to query the delivery for status updates.

{
  "code": "200",
  "status": "200 success",
  "response": {
    "message": "Order Successfully Added. Use the Order ID to query or update this order.",
    "order_id": "1857",
    "order_count": 4
  }
}

Querying an Order

Request

You can query orders for delivery status updates by making POST requests to /orders/details containing the following fields:

Field	Required	Description
order_id	✓	The id of the order you wish to query

Response

The response is a JSON object containing the following fields indicating success or failure as well as various information pertaining to the delivery. Fields of note are: completed, canceled and status.

{
  "code": "200",
  "status": "200 success",
  "response": {
    "id": "1857",
    "created": "2021-04-23 15:12:44",
    "created_by": "192",
    "modified": "2021-04-23 15:12:45",
    "modified_by": "192",
    "canceled": null,
    "canceled_by": null,
    "completed": null,
    "completed_by": null,
    "trash": "0",
    "location": "21",
    "location_count": null,
    "dispatcher": null,
    "driver": null,
    "driver_name": null,
    "status_id": "1",
    "status": "Pending",
    "delivery_time_type": "asap",
    "delivery_time": "asap",
    "delivery_delay": null,
    "comment": "This is a test order",
    "payment_method": null,
    "payment_method_name": null,
    "paid": "0",
    "tip": "0.00",
    "delivery_fee": "0",
    "extra_delivery_fee": "0",
    "price": "0.00",
    "surcharge": null,
    "discount": "0.00",
    "coupon": "0",
    "tax": "0.00",
    "grand_total": "0.00",
    "client": "0",
    "client_name": "Test Store",
    "client_address": "145 Test st",
    "client_latitude": "43.1722028",
    "client_longitude": "-79.2522345",
    "customer": "8",
    "customer_name": "Test Customer",
    "customer_apt": null,
    "customer_address": "150 Test st",
    "customer_phone": "777 777 7777",
    "customer_email": "test@test.com",
    "customer_latitude": "42.1315155",
    "customer_longitude": "-80.090805",
    "estimated_distance": "211 km",
    "estimated_duration": "2 hours 13 mins",
    "actual_duration": null,
    "red_zone": null,
    "loss": null,
    "loss_amount": null,
    "opened": "1",
    "order_number": "4",
    "milestone_event_label": null,
    "milestone_event_value": null,
    "tracking_hash": "ere2u7evedypada2u9u3era6ezuhu6ur",
    "cancelled_reason": null,
    "pool_id": "177647",
    "pool_locked": null,
    "pre_auth_code": null
  }
}

Contributing

Please open an issue to discuss changes or problems.

License

© DispatchNinja