Add docs for order confirmation endpoint

documentation/order-api.md

@@ -87,7 +87,7 @@ Each order has metadata such as delivery date and order items.
 ### Response Properties
 
 * `customer_account_no` is the account number for customer within the supplier system, this can be setup in REKKI supplier app ( https://tulip.rekki.com ). 
-* `confirmed_at` the time at which the supplier confirmed the order (via email or from the REKKI supplier app)
+* `confirmed_at` the time at which the supplier confirmed the order (via email, or via the REKKI supplier app, or via the REKKI API)
 * `contact_info` the phone number or email address for the person who placed the order
 * `contact_name` the full name of the person who placed the order
 * `location_name` the name of the location that placed the order, can be NULL
@@ -164,3 +164,120 @@ const poll = async function(token, last_rekki_order_time) {
 
 poll("XXXXXXX-XXXX-XXXX-XXXXX-XXXXXXXXXXXX", parseInt((+new Date() /1000) - 3600 * 24 * 30));
 ```
+
+---
+
+## CONFIRM ORDER
+### `POST /api/integration/v1/orders/:reference/confirm`
+<!-- <details><summary>Show details</summary> -->
+
+Confirm a pending order by its reference code.
+
+Notifies the buyer that the order has been acknowledged.
+
+### Parameters
+
+- **`reference`**  <span style="font-size: 12px; font-weight: 500;">required (query parameter)</span>  
+  Reference of the order to confirm. Order refs are discoverable when [listing orders](#list-orders).
+
+### Response
+
+Status: `200 OK`  
+Body: JSON object of the confirmed order
+
+- **`reference`**  
+  REKKI's order reference to uniquely identify the order.
+- **`notes`**  
+  Notes from the customer at the time of placing the order. Typically refers to that specific order (e.g. "send fresh tomatoes").  
+  Can be NULL.
+- **`supplier_notes`**  
+  Notes from the customer for the supplier. Typically refer to orders in general (e.g. "use back entrance for delivery").  
+  Can be NULL.
+- **`location_name`**  
+  Name of the customer's location that placed the order.  
+  Can be NULL.
+- **`delivery_on`**  
+  Expected delivery date. When customers place orders, they specify for which day it is supposed to be delivered.
+- **`delivery_address`**  
+  Delivery address for this specific order (address, postcode).
+- **`customer_account_no`**  
+  The account number for the customer within the supplier system. Set this up in the REKKI supplier app (https://tulip.rekki.com). 
+- **`created_at`**  
+  Datetime when the order was created by the customer on REKKI.  
+  In [ISO 8601][] UTC format `YYYY-MM-DDTHH:MM:SSZ`.
+- **`contact_name`**  
+  The full name of the person who placed the order.
+- **`contact_info`**  
+  The phone number or email address of the customer who placed the order.
+- **`confirmed_at`**  
+  The time at which the supplier confirmed the order.  
+  In [ISO 8601][] UTC format `YYYY-MM-DDTHH:MM:SSZ`.
+- **`items`**  
+  List of product items that the customer added to the order.  
+- **`items.id`**  
+  REKKI's item id. For REKKI internal reference.
+- **`items.product_code`**  
+  Product code of the item. Maps to the supplier's catalog.  
+  Suppliers can modify the product code on the REKKI supplier app (https://tulip.rekki.com) for future orders from this customer.
+- **`items.name`**  
+  Name of the item as defined by the customer on their product list.
+- **`items.units`**  
+  Unit of the item as defined by the customer on their product list.
+- **`items.quantity`**  
+  The customer's requested quantity of the item (in the requested unit).
+- **`items.spec`**  
+  Details or notes provided by the supplier for the item.  
+  Can be NULL. 
+- **`items.price`**  
+  The item price as set in REKKI.  
+  Can be NULL.
+
+Status: `409 Conflict`  
+Body: `{"error":"Order already confirmed"}`
+
+Status: `404 Not Found`  
+Body: `{"error":"Order not found"}`
+
+### Example Request
+
+```bash
+curl -X POST "https://backend.live.rekki.com/api/integration/v1/orders/W2978351/confirm" \
+     -H "Authorization: Bearer $API_TOKEN" \
+     -H "X-REKKI-Authorization-Type: supplier_api_token" \
+     -H "Content-Type: application/json"
+```
+
+### Example Response
+
+```json
+{
+  "reference": "W2978341",
+  "notes": "Deliver to back door",
+  "supplier_notes": null,
+  "location_name": "Flour Power Pizza",
+  "delivery_on": "2020-02-01",
+  "delivery_address": "Borehamwood, WD6 1GP",
+  "customer_account_no": "R8813",
+  "created_at": "2020-01-31T18:08:05Z",
+  "contact_name": "Jane Doe",
+  "contact_info": "+447123456789",
+  "confirmed_at": "2020-01-31T18:12:55.260701Z",
+  "items": [
+    {
+      "id": "b285af6ba51010750bba1e955996b0ad",
+      "product_code": "APL31",
+      "name": "Granny Smith Apples",
+      "units": "each",
+      "quantity": 50,
+      "spec": "customer requested apples with leaf on stem",
+      "price": null
+    }
+  ]
+}
+```
+
+<sup><a href="#">Back to top ↰</a></sup>
+
+
+[ISO 4217]: https://en.wikipedia.org/wiki/ISO_4217
+[ISO 8601]: https://en.wikipedia.org/wiki/ISO_8601