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 | Will be provided |
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 andTHIS_IS_YOUR_SECRET
with your client_secret.The above command returns JSON structured like this:
{
"success": true,
"data": {
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJhdWQiOiIxIiwianRpIjoiMTMxYTJjMjlkZmY5ZjBjZjIzMTI4MTllOTcwNWNmOTFmMmE0ZDE2MGNkZjE2MWZhYjI0MWQ3ZjU4ODBkYjkwNjAyYWE0YjE4MTNhMDAxZDEiLCJpYXQiOjE3MTU2ODk4MTYuOTUxNTQ4LCJuYmYiOjE3MTU2ODk4MTYuOTUxNTUxLCJleHAiOjE3NDcyMjU4MTYuOTQyNzY3LCJzdWIiOiI0Iiwic2NvcGVzIjpbImNvcnBvcmF0ZSJdfQ.iKbUYDtMkBfYgwC-7wDeZYsHc-TEO5H-6M1E86EOH3Gd2AZB7MzJtsc4P3WpYaQEsULQjpOLTHsvcQeXrdmG3J08kXunXvVeYt0vrYSUjTH4cC3bJuloSWPnq-uHFBnMhQCgozMy-hVMZfwGAYGCynTDaPOc4wZ8FabrpK4Og1pWARSNe_C3-o-rpwuCEqE7BrPTGlhqUmSP-WF-y7HfBAtwmyoROgO2f1wnlW_GXy9jN8g0ICh96YJLpGjNuj5M4LLM3FT5t3UrDDuRY9VgNAS88mniuoXmCOUyUh8tK1NSZi584pJMuyGzofl4KcLAryN8fCUlvoFyJhQstjM_RpIXljdIxMtSFL_YH7FejLm8XsEs9fpSEmzB-Acyegp4FxaTDnSL1tQkoIBm_feLaFo2h2g_4On7EqDGoe3LCYwGT9rY-xt36rQ2rm29WfRbnHbTQPgwswvF2j4cnF7KzbwDe20VgGM6kpI4AQLIN3cTvxPdfK6HbFgEqLCWXmEK231HodiBmrBy8SF2mXXMTUpy6lk40B18NkA-G49NdXLYxHbJYvZMg5wt-KsVAshpnd8gWKkTcfVk6UteFSUI4nZFnD7js00wQ_T7Uh4T6DWjtU3Fxm-YMt_HXZq2b0AbLJ62F0a06JwgCqdMSdrKnwHlUibK3uo46pW9KxM-qtM",
"name": "Corporate Partner"
},
"message": "Corporate token provided."
}
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": "38.13 km",
"distance_fee": "292.00",
"cash_on_delivery_amount": "850.00",
"outside_5km": "0.00",
"outside_10km": "0.00"
}
],
"distance_text": "38.1 km",
"distance_fee": "292.00",
"estimated_arrival_seconds": 5493,
"cash_on_delivery_amount": "850.00",
"morning_surcharge": "0.00",
"evening_surcharge": "0.00",
"corporate_surcharge": "0.00",
"corporate_holiday_surcharge": "0.00",
"outside_ncr_charge": "0.00",
"total_fee": "292.00"
},
"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": "15.97 km",
"distance_fee": "160.00",
"cash_on_delivery_amount": "850.00",
"outside_5km": "0.00",
"outside_10km": "0.00",
"package_type": "Document"
}
],
"distance_text": "16.0 km",
"distance_fee": "160.00",
"estimated_arrival_seconds": 2132,
"cash_on_delivery_amount": "850.00",
"morning_surcharge": "0.00",
"evening_surcharge": "0.00",
"corporate_surcharge": "0.00",
"corporate_holiday_surcharge": "0.00",
"outside_ncr_charge": "0.00",
"total_fee": "160.00",
"reference_number": "200016921",
"pickup_longitude": "121.060354",
"pickup_latutude": "14.582202",
"payment_collection": "sender",
"destination_longitude": "120.9728776",
"destination_latutude": "14.6604517",
"pickup_address": "Market Innovators Inc, 사무실 옥타곤 Octagon Center, San Miguel Avenue, Ortigas Center, 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=200010543' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer token'
The above command returns JSON structured like this:
{
"success": true,
"data": {
"reference_number": "200010543",
"scheduled_at": null,
"status": "delivered",
"created_at": "2023-05-05T01:24:39.000000Z",
"updated_at": "2023-05-05T01:50:55.000000Z",
"partner_tracking_number": null,
"method": "delivery",
"details": [
{
"job_number": 1,
"pickup_longitude": "121.060354",
"pickup_latutude": "14.582202",
"pickup_address": "17th Floor, Octagon Building, Octagon Center, San Miguel Avenue, Ortigas Center, Pasig, Metro Manila, Philippines",
"pickup_name": "Tester One",
"pickup_contact_number": "9276180627",
"pickup_landmark": "",
"pickup_image": "200010543-pickup_image.jpg",
"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": "200010543-delivery_image.jpg",
"distance": "15.98 km",
"distance_fee": "160.00",
"package_type": "Document",
"payment_collection": "sender",
"payment_method": "cash",
"status": "delivered",
"created_at": "2023-05-05T01:24:39.000000Z",
"updated_at": "2023-05-05T01:50:57.000000Z",
"cash_on_delivery_amount": "850.00",
"total_amount": "160.00"
}
],
"distance": "15.98 km",
"distance_fee": 160,
"cash_on_delivery_amount": 850,
"payment_option": "Dingdong Wallet",
"payment_collection": "Sender",
"total_amount": "160.00",
"rider_account_number": "R00000037",
"rider_name": "Account, Hassan Test",
"rider_mobile": "9276180627",
"service_vehicle": "Motorcycle",
"rider_vehicle_details": {
"type": "motorcycle",
"make": "Honda",
"model": "Beat",
"plate": "123456",
"color": "Gray"
},
"rider_rating": "4.9",
"rider_longitude": null,
"rider_latitude": null,
"tracking_screen_link": "https://tracking-staging.riderko.com/tracking_code=MjAwMDEwNTQz?for_mobile=yes",
"waybill_link": "https://api-staging.riderko.com/api/jobWaybill?reference_number=MjAwMDEwNTQz"
},
"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": "200010543",
"scheduled_at": null,
"status": "delivered",
"created_at": "2023-05-05T01:24:39.000000Z",
"updated_at": "2023-05-05T01:50:55.000000Z",
"partner_tracking_number": null,
"method": "delivery",
"details": [
{
"job_number": 1,
"pickup_longitude": "121.060354",
"pickup_latutude": "14.582202",
"pickup_address": "17th Floor, Octagon Building, Octagon Center, San Miguel Avenue, Ortigas Center, Pasig, Metro Manila, Philippines",
"pickup_name": "Tester One",
"pickup_contact_number": "9276180627",
"pickup_landmark": "",
"pickup_image": "200010543-pickup_image.jpg",
"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": "200010543-delivery_image.jpg",
"distance": "15.98 km",
"distance_fee": "160.00",
"package_type": "Document",
"payment_collection": "sender",
"payment_method": "cash",
"status": "delivered",
"created_at": "2023-05-05T01:24:39.000000Z",
"updated_at": "2023-05-05T01:50:57.000000Z",
"cash_on_delivery_amount": "850.00",
"total_amount": "160.00"
}
],
"distance": "15.98 km",
"distance_fee": 160,
"cash_on_delivery_amount": 850,
"payment_option": "Dingdong Wallet",
"payment_collection": "Sender",
"total_amount": "160.00",
"rider_account_number": "R00000037",
"rider_name": "Account, Hassan Test",
"rider_mobile": "9276180627",
"service_vehicle": "Motorcycle",
"rider_vehicle_details": {
"type": "motorcycle",
"make": "Honda",
"model": "Beat",
"plate": "123456",
"color": "Gray"
},
"rider_rating": "4.9"
}
]
},
"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": "200016654",
"is_corporate": "1",
"scheduled_at": null,
"status": "cancelled",
"created_at": "2024-05-09T11:46:51.000000Z",
"updated_at": "2024-05-09T11:57:14.000000Z",
"partner_tracking_number": null,
"details": [
{
"job_number": 1,
"pickup_longitude": "121.066751",
"pickup_latutude": "14.5083543",
"pickup_address": "JGF Place, MRT Avenue, Taguig, Metro Manila, Philippines",
"pickup_name": "Delivery Warehouse 1",
"pickup_contact_number": "9156882821",
"pickup_landmark": "",
"pickup_image": null,
"destination_longitude": "121.0740637",
"destination_latutude": "14.515655",
"destination_address": "G38F+8JM, Taguig, Metro Manila, Philippines",
"destination_name": "Charm G",
"destination_contact_number": "9156882821",
"destination_landmark": "Sea Breeze Entrance",
"destination_image": null,
"distance": "1.82 km",
"distance_fee": "66.00",
"package_type": "Parcel",
"payment_collection": "sender",
"payment_method": "cash",
"status": "cancelled",
"created_at": "2024-05-09T11:46:51.000000Z",
"updated_at": "2024-05-09T11:57:14.000000Z",
"pickup_code": 246,
"delivery_code": 559,
"cash_on_delivery_amount": "0.00",
"total_amount": "66.00"
}
],
"distance": "1.82 km",
"distance_fee": 66,
"payment_option": "Dingdong Wallet",
"payment_collection": "Sender",
"total_amount": "66.00",
"rider_account_number": "",
"rider_name": "",
"rider_mobile": "",
"service_vehicle": "Motorcycle",
"rider_vehicle_details": [],
"rider_rating": "0"
},
"digest": "772e6ef64cb1360483445182909b5aebcc2af3154d46f33fd68bb5b118390bd6"
}
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. |