# API the Wakilni offers an API to help create and manage orders from third-party applications. Developers can use this API to integrate Wakilni into their custom applications. Below are steps required, along with detailed documentation on the API. ### Testing environment For `Testing` use the data below instead of the data in the [Production Environment](#production-environment) section `URL` -> ### Setup You need to register as a new client in [`https://dev.wakilni.com/sign-up`](https://dev.wakilni.com/sign-up) and complete the integration as followed in the documentation. ### Production environment If everything went right, please find the `Production` data (use data below instead of the data in the [Testing Environment](#testing-environment) section) `URL` -> `JORDAN URL` -> ### **Integration with Wakilni steps:** 1. Each client will be able to generate an access token that is attached to your account to be used in the API. 1. Login to customer back office 2. Go to Settings 3. Open tab “Api Tokens” 4. Click “Link to your custom app” 5. Enter your shop name/label. 6. Click create 7. A key/secret combination will be created for this client. 8. Copy these credentials and pass them to the request of the auth api. 9. A token will be generated, which you can pas as a bearer token in the other apis. ### **Order flow** * Bulk process is divided into 2 flows: pickup bulk and delivery bulk * Pickup bulk: driver pickups the product from the vendor * Delivery bulk: driver delivers the product to the recipient * Shipping price: Wakilni has default delivery prices based on pickup/delivery locations. Also, each customer can have his own customized prices. * Api process: * Start bulk: creates pickup bulk order (multiple bulks can be created) * Add delivery: creates delivery order related to pickup bulk (multiple deliveries can be created) * End bulk: orders become active and are sent to portal for shipping * Show order status: shows order status based on the flow update\ Status/ Status Code: * PENDING = 1 * CONFIRMED = 2 * DECLINED = 6 * CANCELED = 7 * PROCESSING = 3 * SUCCESS = 4 * FAILED = 5 * CLOSED\_FAILED = 8 * POSTPONED = 9 * PENDING\_CANCELLATION = 10 * SUCCESS, REJECTED = 4 * When the order is delivered but the client rejected it ### **Authentication** **API**: [https://api.wakilni.com/api/v2/third\_party/auth\_token](#testing-environment) **Method**: GET **Body**: ``` { "key": string, "secret": string } ``` * `key`: App key * `secret`: App secret **Response** ``` { "message": "Auth token retrieved successfully", "token": "*****" } ``` ### **Start bulk** **API**: [https://api.wakilni.com/api/v2/clients/start\_bulk](#testing-environment) **Method**: POST **Header**: **Authorization**: Bearer {token} **Body**: ``` { "location_id": number, "longitude": number, "latitude": number, "floor": number, "area": string, } ``` * `location_id`: customer’s location id reference from your app * `longitude`: customer’s location’s longitude * `latitude`: customer’s location’s latitude * `floor`: customer’s location’s floor * `area`: it is preferable to send us the area name from the list provided from get area’s list **Response** ``` { "message": "Bulk order opened", "bulk_id" } ``` ### **Add delivery** **API**: [https://api.wakilni.com/api/](#testing-environment)[v2/](#testing-environment)[clients/add\_delivery/{bulk\_id}](#testing-environment) **Method**: POST **Header**: **Authorization**: Bearer {token} **Body**: ``` { "get_order_details": boolean, "get_barcode": boolean, "waybill": number, "receiver_id": number, "receiver_first_name": string, "receiver_last_name": string, "receiver_phone_number": string, "receiver_gender": string, "receiver_email": string, "receiver_secondary_phone_number": string, "receiver_location_id *": number, "receiver_longitude": number, "receiver_latitude": number, "receiver_building": string, "receiver_floor": number, "receiver_directions": string, "receiver_area": string, "currency": number, "cash_collection_type_id": number, "collection_amount": double, "note: string, "car_needed": bool, "packages": [ { "quantity": number, "type_id": number, "name": string, "sku": string },.. ] } ``` * `get_order_details`: Set to true if you want to display order details after creating order * `get_barcode`: Set to true if you want the barcode label returned * `waybill`: To reference or identify your order * `receiver_id`: The recipient’s unique reference id from your app or system * For example: your recipient's id in your system is 123, then `"receiver_id" : 123` * `receiver_first_name`: Recipient’s first name * `receiver_last_name`: Recipient’s last name * `receiver_phone_number`: Recipient’s phone number * `receiver_gender`: Recipient’s gender (1 -> male, 2 -> female) * `receiver_email`: Recipient’s email * `receiver_secondary_phone_number`: Recipient’s secondary phone number * `receiver_location_id *`*:* The recipient’s location's unique reference id from your app or system * For example, your recipients shipping address location id is 123, then\ `"receiver_location_id" : 123` * `receiver_longitude`: Customer’s location’s longitude * `receiver_latitude`: Customer’s location’s latitude * `receiver_building`: Customer’s location’s building * `receiver_floor`: Customer’s location’s floor * `receiver_directions`: Customer’s location’s directions * `receiver_area`: It is preferable to send us the area name from the list provided from get area’s list * `currency`: 1 -> USD, 2 -> LBP * `cash_collection_type_id`: (paid: 54, on delivery: 52) * `type_id`: (paper: 57, regular box: 58, small box: 59, large box: 60, very large box: 61) **Response:** ``` { "message": "Delivery order added", "delivery_id", "tracking_url", "tracking_id", "barcode_label", "order_details" } ``` **Note**: for use of barcode label to display barcode image, add the blob value to the image src as follows: ``` barcode ``` ### **End bulk** **API**: [https://api.wakilni.com/api/](#testing-environment)[v2/](#testing-environment)[clients/end\_bulk/{bulk\_id}](#testing-environment) **Method**: POST **Header**: **Authorization**: Bearer {token} **Response:** ``` { "message": "Closed Bulk order", "bulk_id" } ``` ### **Show order status** **API**: [https://api.wakilni.com/api/](#testing-environment)[v2/](#testing-environment)[clients/orders/{id}](#testing-environment) **Method**: POST **Header**: **Authorization**: Bearer {token} **Response:** ``` { "status" "status_code" "completed_on" } ``` ### **Show order status from tracking id** **API**: [https://api.wakilni.com/api/](#testing-environment)[v2/](#testing-environment)[clients/tracking/orders/{tracking\_id}](#testing-environment) **Method**: POST **Header**: **Authorization**: Bearer {token} **Response:** ``` { "status" "status_code" "completed_on" } ``` ### **Cancel order** **API**: [https://api.wakilni.com/api](#testing-environment)[/v2/clients/orders/{id}/cancel](https://api.wakilni.com/api/v2/clients/orders/%7Bid%7D/cancel%60) **Method**: PUT **Header**: **Authorization**: Bearer {token} **Body**: ``` { "reason": string, } ``` * `reason`: Reason for canceling the order **Response:** ``` { "message": string, "delivery_id": number } ``` **Note**: You are able to cancel an order only if the status is pending ### **Get areas** **API**: [https://api.wakilni.com/api/v2/areas](#testing-environment) **Method**: GET **Header: Authorization:** Bearer {token} **Pagination:** [https://api.wakilni.com/api/v2/areas?with\_pagination=true\&page=2](#testing-environment) **Filter:** [https://api.wakilni.com/api/](#testing-environment)[v2/](#testing-environment)[areas?search=name:beirut\&searchJoin=and\&with\_filter=true](#testing-environment) **Pagination and Filter:** [https://api.wakilni.com/api/](#testing-environment)[v2/](#testing-environment)[areas?search=name:beirut\&searchJoin=and\&with\_filter=true\&with\_pagination=true\&page =2](#testing-environment) ### Get order status **API**: **Note:** You may use either the tracking\_id or the order\_id based on your preference **Method**: GET **Header: Authorization:** Bearer {token} **Response:** ``` { "success": true, "data": { "tracking_id": string, "comments": array of strings, "logs": [ { "status": string, "status_code": number, "created_at": string }, ] } } ``` **Example response:** ``` { "success": true, "data": { "tracking_id": "WK2312120840222729128YIbYK", "comments": [ "Call before delivery", "No answer", "Not available", "Order rejected" ], "logs": [ { "status": "Success", "status_code": 4, "created_at": "2023-12-12 11:22:24" }, { "status": "Success, Rejected", "status_code": 4, "created_at": "2023-12-12 11:22:24" }, { "status": "Processing", "status_code": 3, "created_at": "2023-12-12 10:58:49" }, { "status": "Closed Failed", "status_code": 8, "created_at": "2023-12-12 10:50:39" }, { "status": "Processing", "status_code": 3, "created_at": "2023-12-12 10:47:37" }, { "status": "Canceled", "status_code": 7, "created_at": "2023-12-12 10:40:37" }, { "status": "Confirmed", "status_code": 2, "created_at": "2023-12-12 10:40:22" }, { "status": "Pending", "status_code": 1, "created_at": "2023-12-12 10:40:22" } ] } } ```