Created documentation for order API

3 years ago · 1b48a79e72
1 changed files with 151 additions and 0 deletions
--- a/order_api.md
+++ b/order_api.md
@ -0,0 +1,151 @@
+# 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](mailto: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      | &check;  | Name of **organization** or **person** at pickup address |
+| client_address   | &check;  | Pickup address |
+| customer_name    | &check;  | Name of **person** or **organization** at delivery address |
+| customer_address | &check;  | Delivery address |
+| customer_email   | &cross;  | Email for **person** or **organization** at delivery address |
+| customer_phone   | &cross;  | Phone for **person** or **organization** at delivery address |
+| comments         | &cross;  | 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.
+
+```json
+{
+  "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 | &check;  | 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`.
+
+```json
+{
+  "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
+&copy; DispatchNinja