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:

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"
            }
        ]
    }
}

PreviousWooCommerce NextShopify

Last updated 6 months ago