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 section

URL -> https://api-dev.wakilni.com

Setup

You need to register as a new client in 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 section)

URL -> https://api.wakilni.com

JORDAN URL -> https://jordan-api.wakilni.com

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

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

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/v2/clients/add_delivery/{bulk_id}

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:

<img src="data:image/png;base64,{{barcode_label)}}" alt="barcode"/>

End bulk

API: https://api.wakilni.com/api/v2/clients/end_bulk/{bulk_id}

Method: POST

Header: Authorization: Bearer {token}

Response:

{
    "message": "Closed Bulk order",
    "bulk_id"
}

Show order status

API: https://api.wakilni.com/api/v2/clients/orders/{id}

Method: POST

Header: Authorization: Bearer {token}

Response:

{
    "status"
    "status_code"
    "completed_on"
}

Show order status from tracking id

API: https://api.wakilni.com/api/v2/clients/tracking/orders/{tracking_id}

Method: POST

Header: Authorization: Bearer {token}

Response:

{
    "status"
    "status_code"
    "completed_on"
}

Cancel order

API: https://api.wakilni.com/api/v2/clients/orders/{id}/cancel

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

Method: GET

Header: Authorization: Bearer {token}

Pagination: https://api.wakilni.com/api/v2/areas?with_pagination=true&page=2

Filter: https://api.wakilni.com/api/v2/areas?search=name:beirut&searchJoin=and&with_filter=true

Pagination and Filter: https://api.wakilni.com/api/v2/areas?search=name:beirut&searchJoin=and&with_filter=true&with_pagination=true&page =2

Get order status

API: https://api.wakilni.com/api/v2/clients/orders/status?tracking_id={tracking_id}

Method: GET

Header: Authorization: Bearer {token}

Response:

{
    "success": true,
    "data": {
        "tracking_id": string,
        "logs": [
            {
                "status": string,
                "status_code": number,
                "created_at": string
            },
        ]
    }
}

Example response:

{
    "success": true,
    "data": {
        "tracking_id": "WK2312120840222729128YIbYK",
        "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"
            }
        ]
    }
}