From 1b48a79e72baec0155d1557b8261b0cbb599e3e9 Mon Sep 17 00:00:00 2001 From: Ben Ashton Date: Fri, 23 Apr 2021 15:25:33 -0700 Subject: [PATCH] Created documentation for order API --- order_api.md | 151 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 151 insertions(+) create mode 100644 order_api.md diff --git a/order_api.md b/order_api.md new file mode 100644 index 0000000..50e2118 --- /dev/null +++ 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 | ✓ | 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. + +```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 | ✓ | 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 +© DispatchNinja