# 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