Zeek Technology

# Merchant management

# API-3.2.4 Get supported merchants

POST /order/takeaway/merchants/supported
API type Request API
Usage - According to user location, get merchants who support delivery.
- Please refer to How to use merchant assignment APIs

# Request

Name Type Mandatory Default Description Remarks
profile string N "" Brand profile - Only applicable for customized integration.
- Zeek provides the value if needed.
user_address string（255） N * - User address Please refer to How to pass user address and location
user_location string Y * - User location coordinates Please refer to How to pass user address and location

Example：

{
    "auth": {
        // Authentication
    },
    "data": {
        "meta":{
            // Language and region settings
        },
        "profile" : "abc-brand",
        "user_location": "22.3902837102,114.0042115195"
    }
}

# Response

Name Type Description Remarks
merchants array Merchants Return one to many merchants. When there is no merchant, return empty array []
merchants[].merchant_id int Merchant ID in Zeek platform
merchants[].client_merchant_id string Merchant ID in client system
merchants[].prediction.quote_time int Predicted quote time Unit : minute
merchants[].prediction.quote_time_range string Predicted quote time range - Example: "30-40"
status int Search merchant result status 0 : Supported merchants are returned successfully
101 : No merchant is available
102 : No merchant at user's current location
103 : It is at merchant business end buffer time, cannot deliver
104 : It exceeds the maximum predicted quote time, cannot deliver

Example:

{
  "error": 0,
  "data": {
    "merchants" : [
      {
        "merchant_id" : 123,
        "client_merchant_id" : "STORE-123",
        "prediction" : {
          "quote_time": 90,
          "quote_time_range": "90-120"
        }
      }
    ],
    "status": 0
  }
}

# API-3.1.4 Update merchant status

POST /order/takeaway/merchants/status
API type Request API
Usage - Update merchant's status, eg. business hour, shop opening status etc.
- System takes merchant status into account in API-3.2.4 and API-3.2.1 only.
- While using API-3.3.1, order can be created no matter what merchant status is.
- Please refer to How to use merchant assignment APIs

# Request

Name Type Mandatory Default Description Remarks
client_merchant_id string Y - Store ID in client system
update_type string Y - Update type One of the update types:

business_regular_time : The regular business hour of merchant.
business_temporary_time : The temporary business hour of merchant.
business_status : The opening status of merchant.
business_regular_time array N - Regular business hour Only applicable when update_type = business_regular_time
business_temporary_time array N - Temporary business hour Only applicable when update_type = business_temporary_time
business_status int N - Store opening status Only applicable when update_type = business_status .
0 : Shop closed.
1 : Shop opens
(No default value, 0 or 1 must be input)

The format of business_regular_time :

Name Type Mandatory Default Description Remarks
day_of_week int Y - Day of week It must be either one of：
1 : Sunday
2 : Monday
3 : Tuesday
4 : Wednesday
5 : Thursday
6 : Friday
7 : Saturday
whole_day_status string N "" The business status of the whole day open: Open for whole day
close : Closed for whole day
start_time string N* - Start time - It is mandatory When whole_day_status is not passed.
- For example: "09:30"
end_time string N* - End time - It is mandatory When whole_day_status is not passed.
- For example: "09:30"

The format of business_temporary_time :

Name Type Mandatory Default Description Remarks
start_time string Y - Start time - Format: 24 hours
- For example: "09:30"
end_time string Y - End time - Format: 24 hours
- For example: "09:30"

Example：

{
    "auth": {
        // Authentication
    },
    "data": {
        "meta":{
            // Language and region settings
        },
        "client_merchant_id": "STORE-123",
        "update_type" : "business_temporary_time",
        "business_temporary_time": [
            {
                "start_time" : "2019-01-01 10:00",
                "end_time": "2019-01-01 22:00"
            },
            {
                "start_time" : "2019-01-02 10:00",
                "end_time": "2019-01-02 15:00"
            }
        ],
        "business_status": 1
    }
}

# Request examples

# Update business status

Update the merchant's opening status to "closed":

{
    "auth": {
        // Authentication
    },
    "data": {
        "meta":{
            // Language and region settings
        },
        "client_merchant_id": "STORE-123",
        "update_type" : "business_status",
        "business_status": 0
    }
}
# Update regular business hour

The update of business_regular_time will replace the business hours from Monday to Sundays. Reminder: Developer must input all values from Monday to Sunday.

For example, if the request is：

{
    "auth": {
       // Authentication
    },
    "data": {
        "meta":{
            // Language and region settings
        },
        "client_merchant_id": "STORE-123",
        "update_type" : "business_regular_time",
        "business_regular_time" : [
            {
                "day_of_week" : 1,
                "whole_day_status" : "open"
            },
            {
                "day_of_week" : 2,
                "start_time" : "09:00",
                "end_time" : "23:59"
            },
            {
                "day_of_week" : 3,
                "start_time" : "00:00",
                "end_time" : "01:00"
            },
            {
                "day_of_week" : 3,
                "start_time" : "09:00",
                "end_time" : "21:00"
            },
            {
                "day_of_week" : 4,
                "whole_day_status" : "close"
            },
            {
                "day_of_week" : 5,
                "whole_day_status" : "close"
            },
            {
                "day_of_week" : 6,
                "whole_day_status" : "close"
            },
            {
                "day_of_week" : 7,
                "whole_day_status" : "close"
            },
        ]
    }
}

Therefore, the business hour of the merchant will be updated as below until the next update.

Sunday : Whole day
Monday : 09:00 - 23:59
Tuesday : 00:00 - 01:00, 09:00 - 21:00
Wednesday : Closed
Thursday : Closed
Friday : Closed
Saturday : Closed

# Update regular business hour to close stores

In exceptional cases, if it needs to make the store closed for whole week, we need to set whole_day_status to be "close". Reminder: Developer must input all values from Monday to Sunday.

Therefore, the request is：

{
    "auth": {
        // Authentication
    },
    "data": {
        "meta":{
            // Language and region settings
        },
        "client_merchant_id": "STORE-123",
        "update_type" : "business_regular_time",
        "business_regular_time" : [
            {
                "day_of_week" : 1,
                "whole_day_status" : "close"
            },
            {
                "day_of_week" : 2,
                "whole_day_status" : "close"
            },
            {
                "day_of_week" : 3,
                "whole_day_status" : "close"
            },
            {
                "day_of_week" : 4,
                "whole_day_status" : "close"
            },
            {
                "day_of_week" : 5,
                "whole_day_status" : "close"
            },
            {
                "day_of_week" : 6,
                "whole_day_status" : "close"
            },
            {
                "day_of_week" : 7,
                "whole_day_status" : "close"
            },
        ]
    }
}
# Update temporary business hour

Please input business_temporary_time in array. The original business time settings of those days will be replaced by the input of this API.

For example, the origin business hour is "9am to 9pm". If we input the business_temporary_time as:

{
    "auth": {
        // Authentication
    },
    "data": {
        "meta":{
            // Language and region settings
        },
        "client_merchant_id": "STORE-123",
        "update_type" : "business_temporary_time",
        "business_temporary_time" : [
            {
                "start_time" : "2019-02-14 10:00", // 2019-02-14 10am to midnight
                "end_time" : "2019-02-14 23:00"
            }
        ]
    }
}

Then the business hour on the day of 2019-02-14 will be replaced to "10am to 11pm".

Important: cross-day time range is not supported. The start and end time should be in the same day.

Therefore, in the above example, if we are going to change the 2019-02-15 business hour to be "10am to 1am", we need to input all business hour time ranges of 2019-02-16. That is:


{
    "auth": {
        // Authentication
    },
    "data": {
        "meta":{
            // Language and region settings
        },
        "client_merchant_id": "STORE-123",
        "update_type" : "business_temporary_time",
        "business_temporary_time" : [
            {
                "start_time" : "2019-02-15 10:00", // 2019-02-15 10am to midnight
                "end_time" : "2019-02-15 23:59"
            },
            {
                "start_time" : "2019-02-16 00:00", // 2019-02-16 12am to 1am
                "end_time" : "2019-02-16 00:59"
            },
            {
                "start_time" : "2019-02-16 09:00", // Original time range of 2019-02-16
                "end_time" : "2019-02-16 08:59"
            }
        ]
    }
}

If we do not input the time range from 2019-02-16 09:00to 2019-02-16 08:59, the business hour of 2019-02-16 will be 12am to 1am only.

# Response

{
  "error": 0
}

# API-3.1.5 Update all merchants business buffer time

POST /order/takeaway/merchants/business_buffer_time
API type Request API
Usage - Update business buffer time of all merchants.
- Please refer to How to use merchant assignment APIs

The buffer time in this endpoint affects the time constraint of API-3.2.4 Get supported merchants. For example, the business hour of a merchant is 10am - 10pm, while the end_buffer_time input in API-3.1 .5 is 30 (minutes). Then, when API-3.2.4 is called in the time range of 10am - 9:30pm, this merchant will be returned. On the other hand, the merchant will not be returned after 9:30pm. In other words, if API-3.2.4 is called after 9:30pm, no merchan will be returned.

# Request

Name Type Mandatory Default Description Remarks
end_buffer_time int Y - The buffer time before the business end time Unit: minutes

Example：

{
    "auth": {
        // Authentication
    },
    "data": {
        "meta":{
            // Language and region settings
        },
        "end_buffer_time": 30
    }
}

# Response

{
  "error": 0
}

# API-3.2.1 Check merchant is supported

POST /order/takeaway/isdistributable
API type Request API
Usage - Check whether the merchant can deliver to the user.
- Please refer to How to use merchant assignment APIs

# Request

Name Type Mandatory Default Description Remarks
client_merchant_id string Y - Store ID in client system
user_address string（255） N * - User address Please refer to How to pass user address and location
user_location string Y * - User location coordinates Please refer to How to pass user address and location

Example：

{
    "auth": {
        // Authentication
    },
    "data": {
        "meta":{
            // Language and region settings
        },
        "profile":"abc-brand",
        "client_merchant_id": "STORE-123",
        "user_location": "22.3902837102,114.0042115195"
    }
}

# Response

Name Type Description Remarks
distributable int Whether the merchant is supported in delivery 1 : Delivery is supported
0 : Delivery is not supported

Example:

{
    "error": 0,
    "data": {
        "distributable": 1
    }
}

← Delivery order →