Introduction

RiderKo's Corporate Delivery API will allow corporate partners to compute, book, inquire and cancel point to point or multi-point deliveries. Our team is available to support you for inquiries regarding the integration.

Availability

RiderKo's Corporate Delivery API allows point to point and multi-point deliveries within the Philippines.

URL's

Environment	URL
sandbox	https://corp-staging.riderko.com/api/
production	TBD

Authentication

To request for your token, use the following code:

curl --location --request POST 'https://corp-staging.riderko.com/api/corporateToken' \
--header 'Accept: application/json' \
--form 'client_id="YOUR_CLIENT_ID"' \
--form 'client_secret="YOUR_CLIENT_SECRET"'

Make sure to replace YOUR_CLIENT_ID with your client_id and THIS_IS_YOUR_SECRET with your client_secret.

In order to call RiderKo's endpoints, the partner is required to request for a token.

This endpoint requests for a token.

HTTP Request

POST https://corp-staging.riderko.com/api/corporateToken

Request Parameters

Parameter	Type	Required	Description
client_id	string	yes	Your `client_id`.
client_secret	string	yes	Your `client_secret`.

All other endpoints require for the token to be included in the header of the requests, that looks like the following:

Authorization: Bearer token

Delivery

Compute Delivery

curl --location --request POST 'https://corp-staging.riderko.com/api/computeDelivery' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--form 'pickup_longitude="121.123456"' \
--form 'pickup_latitude="14.123456"' \
--form 'destinations="{
   \"destinations\":[
      {
         \"destination_longitude\":\"121.123456\",
         \"destination_latutude\":\"14.123456\",
         \"destination_address\":\"\"
      }
   ]
}"'

The above command returns JSON structured like this:

{
    "success": true,
    "data": {
        "destinations": [
            {
                "distance_text": "35.9 km",
                "distance_fee": "265.00"
            }
        ],
        "distance_text": "35.9 km",
        "distance_fee": "265.00",
        "estimated_arrival_seconds": 5274,
        "corporate_surcharge": "0.00",
        "corporate_holiday_surcharge": "0.00",
        "outside_ncr_charge": "132.50",
        "total_fee": "397.50",
    },
    "message": "Rates computed."
}

This endpoint computes a Delivery request.

HTTP Request

POST https://corp-staging.riderko.com/api/computeDelivery

Header Parameters

Parameter	Type	Required	Description
Accept	string	yes	Set to application/json.
Authorization	string	yes	Set to Bearer `token`.

Request Parameters

Parameter	Type	Required	Description
pickup_longitude	decimal	yes	Longitude of the pickup location
pickup_latutude	decimal	yes	Latitude of the pickup location
destinations	json array	yes	JSON array of the destinations/drop offs

Destinations

Parameter	Type	Required	Description
destination_longitude	decimal	yes	Longitude of a dropoff location
destination_latutude	decimal	yes	Latitude of the dropoff location
parcel_dimensions	json array	no	JSON array of the parcels dimensions
cash_on_delivery_amount	decimal	no	Amount that will be collected from receipient ex 150.00

Parcel Dimensions

Parameter	Type	Required	Description
height	integer	no	Height of the parcel in cm ex 15
width	integer	no	Width of the parcel in cm ex 15
depth	integer	no	Depth of the parcel in cm ex 15
weight	integer	no	Weight of the parcel in grams ex 1500

Book Delivery

curl --location --request POST 'https://corp-staging.riderko.com/api/bookDelivery' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--form 'pickup_longitude="121.12345678"' \
--form 'pickup_latutude="14.12345678"' \
--form 'pickup_name="Tester One"' \
--form 'pickup_contact_number="9987654321"' \
--form 'pickup_landmark=""' \
--form 'destinations="{
   \"destinations\":[
      {
          \"destination_longitude\":\"120.12345678\",
         \"destination_latutude\":\"14.12345678\",
         \"destination_name\":\"Tester\",
         \"destination_contact_number\":\"9987654321\",
         \"destination_landmark\":\"\",
         \"package_type\":\"Document\"
      }
   ]
}"' \
--form 'scheduled_at="2022-01-27 14:30:00"'

The above command returns JSON structured like this:

{
    "success": true,
    "data": {
        "destinations": [
            {
                "distance_text": "20.0 km",
                "distance_fee": "169.00",
                "package_type": "Document"
            }
        ],
        "distance_text": "20.0 km",
        "distance_fee": "169.00",
        "estimated_arrival_seconds": 2635,
        "corporate_surcharge": "70.00",
        "corporate_holiday_surcharge": "0.00",
        "outside_ncr_charge": "0.00",
        "total_fee": "239.00",
        "reference_number": "200008154",
        "pickup_longitude": "121.0786206",
        "pickup_latutude": "14.5784464",
        "job_type": "P2P",
        "payment_collection": "sender",
        "destination_longitude": "120.9728776",
        "destination_latutude": "14.6604517",
        "pickup_address": "173 B A Sgt P Bernardo, Pasig, Metro Manila, Philippines",
        "destination_address": "228 Bisig Ng Kabataan, Sangandaan, Caloocan, 1400 Kalakhang Maynila, Philippines"
    },
    "message": "Booking successful, finding you a rider."
}

This endpoint sends a request for delivery.

HTTP Request

POST https://corp-staging.riderko.com/api/bookDelivery

Header Parameters

Parameter	Type	Required	Description
Accept	string	yes	Set to application/json.
Authorization	string	yes	Set to Bearer `token`.

Request Parameters

Parameter	Type	Required	Description
pickup_longitude	decimal	yes	Longitude of the pickup location
pickup_latutude	decimal	yes	Latitude of the pickup location
pickup_name	string	yes	Name of the person to pickup the package from
pickup_contact_number	int	yes	10 digit format (ex 9276666666) of the mobile number of the person to pickup the package from
pickup_landmark	string	no	Landmark of the pickup location or notes to rider
scheduled_at	datetime	no	Date and time for scheduled pickup in YYYY-MM-DD HH:MM:SS format (ex 2022-01-27 14:30:00). Should be within 48 hours of current date and time
destinations	json array	yes	JSON array of the destinations/drop offs
partner_tracking_number	string	no	Tracking number of corporate partner

Destinations

Parameter	Type	Required	Description
destination_longitude	decimal	yes	Longitude of a dropoff location
destination_latutude	decimal	yes	Latitude of the dropoff location
destination_name	string	yes	Name of the person to dropoff a package to
destination_contact_number	int	yes	10 digit format (ex 9276666666) of the mobile number of the person to dropoff a package to
destination_landmark	string	no	Landmark of a dropoff location or notes to rider
package_type	string	yes	One of the following: Clothing, Electronics, Food, Documents, Fragile Item, Boxed Item, Medicine, Flowers, Groceries
parcel_dimensions	json array	no	JSON array of the parcels dimensions
cash_on_delivery_amount	decimal	no	Amount that will be collected from receipient ex 150.00

Parcel Dimensions

Parameter	Type	Required	Description
height	integer	no	Height of the parcel in cm ex 15
width	integer	no	Width of the parcel in cm ex 15
depth	integer	no	Depth of the parcel in cm ex 15
weight	integer	no	Weight of the parcel in grams ex 1500

Get a Specific Delivery

curl --location --request GET 'https://corp-staging.riderko.com/api/getDelivery?reference_number=200123456' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'

The above command returns JSON structured like this:

{
    "success": true,
    "data": {
        "reference_number": "200008159",
        "is_corporate": "1",
        "scheduled_at": null,
        "status": "pending",
        "created_at": "2022-10-20T02:06:26.000000Z",
        "updated_at": "2022-10-20T02:06:26.000000Z",
        "details": [
            {
                "job_number": 1,
                "pickup_longitude": "121.0786206",
                "pickup_latutude": "14.5784464",
                "pickup_address": "173 B A Sgt P Bernardo, Pasig, Metro Manila, Philippines",
                "pickup_name": "Tester One",
                "pickup_contact_number": "9276180627",
                "pickup_landmark": "",
                "pickup_image": "",
                "destination_longitude": "120.9728776",
                "destination_latutude": "14.6604517",
                "destination_address": "228 Bisig Ng Kabataan, Sangandaan, Caloocan, 1400 Kalakhang Maynila, Philippines",
                "destination_name": "Test",
                "destination_contact_number": "9276180627",
                "destination_landmark": "",
                "destination_image": null,
                "distance": "19.96 km",
                "distance_fee": "169.00",
                "package_type": "Document",
                "payment_collection": "sender",
                "payment_method": "cash",
                "status": "pending",
                "created_at": "2022-10-20T02:06:26.000000Z",
                "updated_at": "2022-10-20T02:06:26.000000Z",
                "total_amount": "169.00"
            }
        ],
        "distance": "19.96 km",
        "distance_fee": 169,
        "payment_option": "Cash Payment by Sender",
        "payment_collection": "Sender",
        "total_amount": "169.00",
        "rider_account_number": "",
        "rider_name": "",
        "rider_mobile": "",
        "service_vehicle": "Motorcycle",
        "rider_vehicle_details": [],
        "rider_rating": 0
    },
    "message": "Job found."
}

This endpoint retrieves a specific deliveries details.

HTTP Request

GET https://corp-staging.riderko.com/api/getDelivery?reference_number=<reference_number>

Header Parameters

Parameter	Type	Required	Description
Accept	string	yes	Set to application/json.
Authorization	string	yes	Set to Bearer `token`.

Query Parameters

Parameter	Type	Required	Description
reference_number	integer	yes	Reference number of the delivery

Get a set of Deliveries

curl --location --request GET 'https://corp-staging.riderko.com/api/getDeliveries?status=all&page=100' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'

The above command returns JSON structured like this:

{
    "success": true,
    "data": {
        "result": [
            {
                "reference_number": "400007801",
                "is_corporate": "1",
                "scheduled_at": null,
                "status": "cancelled",
                "created_at": "2022-10-12T10:00:45.000000Z",
                "updated_at": "2022-10-12T10:02:44.000000Z",
                "details": [
                    {
                        "job_number": 1,
                        "pickup_longitude": "121.0598378973456",
                        "pickup_latutude": "14.591299777236681",
                        "pickup_address": "503 Ortigas Ave, Ortigas Center, Pasig, 1605 Metro Manila, Philippines",
                        "pickup_name": "",
                        "pickup_contact_number": "",
                        "pickup_landmark": "",
                        "pickup_image": "",
                        "destination_longitude": "121.05888413049004",
                        "destination_latutude": "14.58203125",
                        "destination_address": "Ortigas Center, Pasig, Metro Manila, Philippines",
                        "destination_name": "FB Test Dos",
                        "destination_contact_number": "9917757881",
                        "destination_landmark": "",
                        "destination_image": "",
                        "distance": "2.07 km",
                        "distance_fee": "62.00",
                        "package_type": "RiderKo Mart",
                        "payment_collection": "recipient",
                        "payment_method": "cash",
                        "status": "cancelled",
                        "created_at": "2022-10-12T10:00:45.000000Z",
                        "updated_at": "2022-10-12T10:02:44.000000Z",
                        "total_amount": "192.00"
                    }
                ],
                "distance": "2.07 km",
                "distance_fee": 62,
                "payment_option": "Cash Payment by Receiver",
                "payment_collection": "Recipient",
                "total_amount": "192.00",
                "rider_account_number": "",
                "rider_name": "",
                "rider_mobile": "",
                "service_vehicle": "Motorcycle",
                "rider_vehicle_details": [],
                "rider_rating": 0
            },
            {
                "reference_number": "400007800",
                "is_corporate": "1",
                "scheduled_at": null,
                "status": "cancelled",
                "created_at": "2022-10-12T09:54:05.000000Z",
                "updated_at": "2022-10-12T09:54:28.000000Z",
                "details": [
                    {
                        "job_number": 1,
                        "pickup_longitude": "121.0598378973456",
                        "pickup_latutude": "14.591299777236681",
                        "pickup_address": "503 Ortigas Ave, Ortigas Center, Pasig, 1605 Metro Manila, Philippines",
                        "pickup_name": "",
                        "pickup_contact_number": "",
                        "pickup_landmark": "",
                        "pickup_image": "",
                        "destination_longitude": "121.05873589643936",
                        "destination_latutude": "14.582023620605469",
                        "destination_address": "Ortigas Center, Pasig, Metro Manila, Philippines",
                        "destination_name": "FB Test Dos",
                        "destination_contact_number": "9917757881",
                        "destination_landmark": "",
                        "destination_image": "",
                        "distance": "2.07 km",
                        "distance_fee": "62.00",
                        "package_type": "RiderKo Mart",
                        "payment_collection": "recipient",
                        "payment_method": "cash",
                        "status": "cancelled",
                        "created_at": "2022-10-12T09:54:05.000000Z",
                        "updated_at": "2022-10-12T09:54:28.000000Z",
                        "total_amount": "192.00"
                    }
                ],
                "distance": "2.07 km",
                "distance_fee": 62,
                "payment_option": "Cash Payment by Receiver",
                "payment_collection": "Recipient",
                "total_amount": "192.00",
                "rider_account_number": "",
                "rider_name": "",
                "rider_mobile": "",
                "service_vehicle": "Motorcycle",
                "rider_vehicle_details": [],
                "rider_rating": 0
            }
        ]
    },
    "message": "Job History."
}

This endpoint retrieves a group of delivery details.

HTTP Request

GET https://corp-staging.riderko.com/api/getDeliveries?status=<status>&page=<page>

Header Parameters

Parameter	Type	Required	Description
Accept	string	yes	Set to application/json.
Authorization	string	yes	Set to Bearer `token`.

Query Parameters

Parameter	Type	Required	Description
status	string	no	Status of transactions to fetch: all, on-going, completed or cancelled
page	integer	no	Page of the transactions to fetch (if not sent, retreives all records). Records are paginated by 10.

Cancel Delivery

curl --location --request POST 'https://corp-staging.riderko.com/api/cancelDelivery' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token' \
--form 'reference_number="200008159"' \
--form 'cancellation_reason="I waited too long"'

The above command returns JSON structured like this:

{
    "success": true,
    "data": {
        "reference_number": "200008159",
        "cancellation_reason": "I waited too long"
    },
    "message": "Job cancelled."
}

This endpoint cancels a Delivery request.

HTTP Request

POST https://corp-staging.riderko.com/api/cancelDelivery

Header Parameters

Parameter	Type	Required	Description
Accept	string	yes	Set to application/json.
Authorization	string	yes	Set to Bearer `token`.

Request Parameters

Parameter	Type	Required	Description
reference_number	integer	yes	Longitude of the pickup location
cancellation_reason	string	yes	Reason of the cancellation, One of the following: "I waited too long", "I've changed my mind", "I entered wrong information", "Other reasons"

WebHook/Postback

Sample Postback Payload:

{
    "data": {
        "reference_number": "200008159",
        "is_corporate": "1",
        "scheduled_at": null,
        "status": "cancelled",
        "created_at": "2022-10-20T02:06:26.000000Z",
        "updated_at": "2022-10-20T04:02:40.000000Z",
        "details": [
            {
                "job_number": 1,
                "pickup_longitude": "121.0786206",
                "pickup_latutude": "14.5784464",
                "pickup_address": "173 B A Sgt P Bernardo, Pasig, Metro Manila, Philippines",
                "pickup_name": "Tester One",
                "pickup_contact_number": "9276180627",
                "pickup_landmark": "",
                "pickup_image": "",
                "destination_longitude": "120.9728776",
                "destination_latutude": "14.6604517",
                "destination_address": "228 Bisig Ng Kabataan, Sangandaan, Caloocan, 1400 Kalakhang Maynila, Philippines",
                "destination_name": "Test",
                "destination_contact_number": "9276180627",
                "destination_landmark": "",
                "destination_image": null,
                "distance": "19.96 km",
                "distance_fee": "169.00",
                "package_type": "Document",
                "payment_collection": "sender",
                "payment_method": "cash",
                "status": "cancelled",
                "created_at": "2022-10-20T02:06:26.000000Z",
                "updated_at": "2022-10-20T04:02:40.000000Z",
                "total_amount": "169.00"
            }
        ],
        "distance": "19.96 km",
        "distance_fee": 169,
        "payment_option": "Cash Payment by Sender",
        "payment_collection": "Sender",
        "total_amount": "169.00",
        "rider_account_number": "",
        "rider_name": "",
        "rider_mobile": "",
        "service_vehicle": "Motorcycle",
        "rider_vehicle_details": [],
        "rider_rating": 0
    },
    "digest": "bTeuIkDvKuQakWEgFS9JhOf4FF4UAHmUWNw47JZN"
}

Digest Generation Sample Code

public function generate_digest($params, $client_id)
{
    $params = $params['reference_number'] . $params['status'];
    return hash_hmac('sha256', $params, $client_id, false); //Compute hash value
}

For every status change a postback will be sent to the corporate partners provided WebHook/Postback URL. The partner has the option of verifying the Postback with the provided digest.

Make sure that your WebHook/Postback server responds with a HTTP code 200 and the the ff in JSON format {"success": true}

Errors

The RiderKo Corporate API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is invalid.
401	Unauthorized -- Your API key is wrong.
403	Forbidden
404	Not Found
405	Method Not Allowed
406	Not Acceptable -- You requested a format that isn't json.
429	Too Many Requests
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.