MyParcel Asia :: Delivering Expectations ::


MyParcelAsia API beta

This is documentation for public API to MyParcelAsia. It was meant to be used as client-facing endpoint to help other system integrator to integrate MyParcelAsia offering into their system. Current version is V.0.3.beta and still an ongoing development. Please contact admin for further assistant.

General Flow

As customer facing API, this integration was meant to be used in system that manage purchased item as fulfillment. In general, your system should have a listing or orders that need to be processed.

From there, your user can select items/orders that they like to generate consignment note and proceed with MyParcelAsia API.

  1. User select items to be processed by MyParcelAsia
  2. User key in postcode from & to and get list of quotes
  3. User select quotes they aggree with
  4. System verify that user has enough balance, if not, user has the option to topup their account balance
  5. If enough balance, user will need to fill in receiver details
  6. Done all details, user checkout to confirm balance reduction and get connotes to be downloaded
  7. End

Authentication

Each API call need api_key to sent in POST Parameter as means of authentication. User can retrieve API key from MyParcelAsia Dashboard under menu My Accounts > Api Keys tab

Testing / Demo Keys

For development and testing purpose, please register demo account at demo.myparcelasia.com and generate key like above guidance.

You also need to use https://demo.myparcelasia.com as endpoint.

All demo credit topup request will be auto approved and all shipment will have not-working fake number. Other than that, everything will be the same.

Type Endpoint Key
Dev / Demo https://demo.myparcelasia.com
  1. Register at https://demo.myparcelasia.com
  2. Generate Key at /account/api_keys
Production https://myparcelasia.com
  1. Register at https://myparcelasia.com
  2. Generate Key at /account/api_keys

Verification

Verification done via api_key match between sent api_key and api_key in our backend. Mismatch api_key will return error and endpoint will not be processed.

Please take note that api_key value need to be sent as POST Parameter along with other parameters. NOT in HTTP Authentication parameter.

General Guidelines

  1. ONLY POST request required. Other method is not available
  2. api_key parameter need to always be sent in POST parameter for verification
  3. Base url for PRODUCTION endpoint is https://myparcelasia.com/api/v1/{endpoint}
  4. Base url for DEVELOPMENT endpoint is https://demo.myparcelasia.com/api/v1/{endpoint}

Response Object

All endpoint call will return specific response object pattern in JSON format. Below are an example:

{
  "status":true,
  "message":"Order has been processed. Some shipment may not gone through. Please check returned shipment for successfully processed shipments only.",
  "data":{
    "order":{
      "id":"4118",
      "customer_name":"Izwan Wahab",
      "total_amount":"6.00",
      "currency_label":"RM",
      "currency_code":"MYR",
      "created_at":"2018-07-30 14:27:14"
    },
    "shipments":[
      {
        "id":"1008607",
        "shipment_id":"1008607",
        "api_key":"XXXDEMOKEYXXX",
        "scope":"international",
        .
        .
        .
        "tracking_no":"30344963515",
        "consignment_note":"https:\/\/myparcelasia.local\/dload\/label\/TVRBd09EWXdOdz09",
        "label_url":"https:\/\/myparcelasia.local\/dload\/label\/TVRBd09EWXdOdz09",
        "shipment_created":"true"
      }
    ]
  },
  "hash":"ecaf53684a2ff7ca9cc1b412fd47fb82",
  "meta":{
    "vendor":"myparcelasia.com",
    "version":"1.0",
    "api_key":"XXXDEMOKEYXXX",
    "endpoint":"api\/v1\/checkout",
    "currency_label":"RM",
    "currency_code":"MYR",
    "topup_balance":"3493.62",
    "topup_link":"https:\/\/myparcelasia.local\/api\/v1\/topup\/XXXDEMOKEYXXX",
    "timestamp":"2018-07-30 14:27:05"
  }
}

Response object has 5 separate section. Explanation as below:

ParamaterExplanation
status will only return TRUE or FALSE to indicate the status of call.
message will contain verbose response accompanying the status.
data will contain specific object that is a result of endpoint processing. It may differ from one endpoint to another.
hash contain a hash key of all the returned parameter exluding hash itself and meta. Optional for you to check the validity of the return object. Hash calculation will be presented below.
meta is miscelanious data that can help in developing the integration and can also be helpful in debugging integration errors.

Hash Calculation

Hash was generate by simple formula: an array with parameter for status, message and data IN THAT ORDER which then encoded as JSON string and concatenate with api_secret accompanying the api_key in usage. The string then get hash with md5 function to return a 32 character length hash result.

<?php
  $ret['status'] = $status;
  $ret['message'] = $msg;
  $ret['data'] = $data;
  $hash = md5(json_encode($ret).$api_secret);
?>

Endpoints

/get_product_types

ENDPOINT: https://myparcelasia.com/api/v1/get_product_types

USAGE: To get all product type id available to be used in /create_shipment parameters.

PARAMETERS:
Name Type Rules Remarks
api_key string Required Retrieve from MyParcelAsia account
POST Parameter Example
{
  "api_key":"XXXDEMOKEYXXX"

}
RESPONSE Example
{
  "status":true,
  "message":"success",
  "data":[
    {"id":"1","title":"Lifestyle & Home- Outdoors"},
    {"id":"2","title":"Others"},
    {"id":"3","title":"Letters & Papers"},
    {"id":"5","title":"Fashion & Apparel - General"},
    {"id":"6","title":"Fashion & Apparel - Sports"},
    {"id":"7","title":"Fashion & Apparel- Accessories"},
    {"id":"8","title":"Fashion & Apparel- Muslimah"},
    {"id":"9","title":"Health & Beauty"},
    {"id":"10","title":"Babies & Toys"},
    {"id":"11","title":"Electronic & Gadgets- General"},
    {"id":"12","title":"Electronic & Gadgets- Music"},
    {"id":"13","title":"Lifestyle & Home- Furniture"},
    {"id":"14","title":"Lifestyle & Home- Health and Fitness"}
  ],
  "hash":"",
  "meta":{}
}

/get_countries

ENDPOINT: https://myparcelasia.com/api/v1/get_countries

USAGE: To get all countries id available to be used in /get_quotes endpoint parameters.

PARAMETERS:
Name Type Rules Remarks
api_key string Required Retrieve from MyParcelAsia account
POST Parameter Example
{
  "api_key":"XXXDEMOKEYXXX"

}
RESPONSE Example
{
  "status":true,
  "message":"success",
  "data":[
    {"id":"1","name":"Afghanistan"},
    {"id":"3","name":"Albania"},
    {"id":"5","name":"American Samoa"},
    {"id":"6","name":"Andorra"},
    .
    .
    .
    {"id":"248","name":"Zambia"},
    {"id":"249","name":"Zimbabwe"},
    {"id":"250","name":"Northern Ireland"},
    {"id":"251","name":"Scotland"},
    {"id":"252","name":"Wales"}
  ],
  "hash":"",
  "meta":{}
}

/get_my_states

ENDPOINT: https://myparcelasia.com/api/v1/get_my_states

USAGE: To get all states id available in Malaysia to be used as a parameter in /create_shipment.

PARAMETERS:
Name Type Rules Remarks
api_key string Required Required
POST Parameter Example
{
  "api_key":"XXXDEMOKEYXXX"

}
RESPONSE Example
{
"status":true,
"message":"success",
"data":[
  {"id":"2","name":"Kuala Lumpur"},
  {"id":"3","name":"Labuan"},
  {"id":"4","name":"Putrajaya"},
  {"id":"5","name":"Johor"},
  {"id":"6","name":"Kedah"},
  {"id":"7","name":"Kelantan"},
  {"id":"8","name":"Melaka"},
  {"id":"9","name":"Negeri Sembilan"},
  {"id":"10","name":"Pahang"},
  {"id":"11","name":"Perak"},
  {"id":"12","name":"Perlis"},
  {"id":"13","name":"Penang"},
  {"id":"14","name":"Sabah"},
  {"id":"15","name":"Sarawak"},
  {"id":"16","name":"Selangor"},
  {"id":"17","name":"Terengganu"}
],
"hash":"",
"meta":{}
}

/get_quotes

ENDPOINT: https://myparcelasia.com/api/v1/get_quotes

USAGE: To get all available provider with its corresponding prices for specification of shipment.

PARAMETERS:
Name Type Rules Remarks
api_key string Required
scope either 'international' or 'domestic' Required
total_weight float Required unit: KG
from_postcode string Required
to_postcode string Required if scope = domestic
to_country_id string Required if scope = international Retrieve from /get_countries
POST Parameter Example
{
  "scope":"domestic",
  "total_weight":2,
  "from_postcode":60000,
  "to_postcode":68000,
  "to_country_id":null
}
RESPONSE Example
{
"status":true,
"message":"Success",
"data":[
  {
    "provider":"POS Laju",
    "provider_id":"1",
    "provider_logo":"https:\/\/myparcelasia.local\/assets\/images\/providers\/1.png?ts=1507007967",
    "provider_international_fuel_surchage_percent":0,
    "type":"document",
    "can_pickup":true,
    "can_walkin":true,
    "scope":"domestic",
    "available_pickup_date":{
      "0":"2018-07-31",
      "1":"2018-08-01",
      "2":"2018-08-02",
      "3":"2018-08-03",
      "6":"2018-08-06",
      "7":"2018-08-07",
      "8":"2018-08-08",
      "9":"2018-08-09",
      "10":"2018-08-10",
      "13":"2018-08-13"
    },
    "offdays":{
      "1":"2018-08-04",
      "2":"2018-08-05",
    },
    "price_type":"exclusive",
    "normal_price":"7.10",
    "exclusive_price":"6.00",
    "currency_code":"MYR","currency":"RM"
  },
  .
  .
  .
  {
    "provider":"Nationwide",
    "provider_id":"3",
    "provider_logo":"https:\/\/myparcelasia.local\/assets\/images\/providers\/3.png",
    "provider_international_fuel_surchage_percent":0,
    "type":"parcel",
    "can_pickup":true,
    "can_walkin":true,
    "scope":"domestic",
    "available_pickup_date":{
      "0":"2018-07-31",
      "1":"2018-08-01",
      "2":"2018-08-02",
      "3":"2018-08-03",
      "6":"2018-08-06",
      "7":"2018-08-07",
      "8":"2018-08-08",
      "9":"2018-08-09",
      "10":"2018-08-10",
      "13":"2018-08-13"
    },
    "offdays":{
      "1":"2018-08-04",
      "2":"2018-08-05",
    },
    "price_type":"exclusive",
    "normal_price":"7.10",
    "exclusive_price":"6.00",
    "currency_code":"MYR",
    "currency":"RM"
  }
],
"hash":"",
"meta":{}
}

/create_shipment

ENDPOINT: https://myparcelasia.com/api/v1/create_shipment

USAGE: To create shipment object in myparcelasia database given preliminary data from previous action (get_quotes).

PARAMETERS:
Name Type Rules Remarks
api_key string Required Retrieve from MyParcelAsia account
scope either 'international' or 'domestic' Required
from_postcode string Required
to_postcode string Required if scope = domestic
to_state_name string Optional
to_country_id string Required if scope = international Retrieve from /get_countries
total_weight string Required unit: KG
referrence_id string Optional for your referrence. Usually important id corresponding to the shipment
referrence_number string Optional Used as Ref Number to be displayed in the printed consignment note for easy of use by operation team.
referrence_data string Optional string of misc data that integrator like to store for this shipment.
send_type string either 'pickup' or 'walkin' Required
pickup_date datetime (YYYY-MM-DD) Required
price_id integer Required retrieve from /get_quotes
receiver_name string Required
receiver_phone string Required
receiver_email string Optional
receiver_address_line_1 string Required
receiver_address_line_2 string Required
receiver_address_line_3 string Optional
receiver_address_line_4 string Optional
receiver_company_name string Optional
receiver_city string Required
content_type_id integer Required retrieved from /get_content_type
content_value decimal Required
content_description string Required
hs_code string Optional Specific item code as used by Customs. Click here for more info.
parcel_length float Required unit: cm
parcel_width float Required unit: cm
parcel_height float Required unit: cm
sender_name string Required
sender_phone string Required
sender_email string Required
sender_address_line_1 string Required
sender_address_line_2 string Required
sender_address_line_3 string Optional
sender_address_line_4 string Optional
sender_city string Required
POST Parameter Example
{
  "api_key":"XXXDEMOKEYXXX"
  "scope": "domestic",
  "from_postcode": "60000",
  "to_postcode": "68000",
  "to_state_name": "Selangor",
  "to_country_id": null,
  "total_weight": 0.5,
  "referrence_id": "MPA-0019",
  "referrence_number": "MPA-0019",
  "referrence_data": null,
  "send_type": "pickup",
  "pickup_date": "2018-07-01",
  "price_id": 39,
  "receiver_name": "Izwan",
  "receiver_phone": "+6012383928",
  "receiver_email": "izwan@email.com",
  "receiver_address_line_1": "No 11-2, Jalan 15",
  "receiver_address_line_2": "Taman Maju Jaya",
  "receiver_address_line_3": null,
  "receiver_address_line_4": null,
  "receiver_company_name": null,
  "receiver_city": "Ampang",
  "content_type_id": 4,
  "content_value": 200,
  "content_description": "Kasut Joging",
  "hs_code": null,
  "parcel_length": 30,
  "parcel_width": 15,
  "parcel_height": 15,
  "sender_name": "Nadia",
  "sender_phone": "+6016928392",
  "sender_email": "nadia@email.com",
  "sender_address_line_1": "No 28, Lorong Maharaja Ampat",
  "sender_address_line_2": "Taman Istana Kuning",
  "sender_address_line_3": null,
  "sender_address_line_4": null,
  "sender_city: "Damansara",
}
RESPONSE Example
{
  "status":true,
  "message":"Success create shipment. Your shipment id is [1008684]",
  "data":{"shipment_id":1008684},
  "hash":"",
  "meta":{}
}

/get_cart_content

ENDPOINT: https://myparcelasia.com/api/v1/get_cart_content

USAGE: To get all shipment that has been created but not paid yet.

PARAMETERS:
Name Type Rules Remarks
api_key string Required
POST Parameter Example
{
  "api_key":"XXXDEMOKEYXXX"

}
RESPONSE Example
{
"status":true,
"message":"Success",
"data":[
  {
    "id":"1008684",
    "shipment_id":"1008684",
    "user_id":"1048",
    .
    .
    .
    "consignment_note":null,
    "label_url":null,
    "shipment_created":"false"
  },
  .
  .
  .
  {
    "id":"1008608",
    "shipment_id":"1008608",
    "user_id":"1048",
    .
    .
    .
    "consignment_note":null,
    "label_url":null,
    "shipment_created":"false"
  }
],
"hash":"",
"meta":{}
}

/checkout

ENDPOINT: https://myparcelasia.com/api/v1/checkout

USAGE: To pay and process selected shipment to get its corresponding consignment note and pickup notification to provider.

*TOPUP*: It is advisable for integrator to check for enough topup balance before proceed with checkout as a preleminary verfication. Current balance can be retrieve from all api call in meta section under 'topup_balance' variable.

A checkout is verified if current topup balance is more than checkout total amount.

If it was not enough, user can topup without login into MyParcelAsia account via public topup link available in meta section. The link is specific for the api user.


PARAMETERS:
Name Type Rules Remarks
api_key string Required
shipment_id array Required example: [1000192, 1000193] . If only one shipment for checkout: use [1000191]
POST Parameter Example
{
  "api_key":"XXXDEMOKEYXXX",
  "shipment_id":[1008607,1008608]
}
RESPONSE Example
{
"status":true,
"message":"Order has been processed. Some shipment may not gone through. Please check returned shipment for successfully processed shipments only.",
"data":{
  "order":{
    "id":"4119",
    "customer_name":"Izwan Wahab",
    "total_amount":"6.00",
    "currency_label":"RM",
    "currency_code":"MYR",
    "created_at":"2018-07-31 08:44:49"
  },
  "shipments":[
    {
      "id":"1008607",
      "shipment_id":"1008607",
      "user_id":"1048",
      .
      .
      .
      "shipment_code":"30344964753",
      "tracking_no":"30344964753",
      "consignment_note":"https:\/\/myparcelasia.com\/dload\/label\/TVRBd09EWXdOdz09",
      "label_url":"https:\/\/myparcelasia.com\/dload\/label\/TVRBd09EWXdOdz09",
      "shipment_created":"true"
    },
    .
    .
    .
  ]
},
"hash":"",
"meta":{}
}

/get_all_shipment

ENDPOINT: https://myparcelasia.com/api/v1/get_all_shipment

USAGE: Retrieve all shipment that has been created by the user.

PARAMETERS:
Name Type Rules Remarks
api_key string Required
POST Parameter Example
{
  "api_key":"XXXDEMOKEYXXX"

}
RESPONSE Example
{
"status":true,
"message":"Success",
"data":[
  {
    "id":"1008550",
    "shipment_id":"1008550",
    "user_id":"1048",
    .
    .
    .
    "shipment_created":"true"
  },
  .
  .
  .
  {
    "id":"1008606",
    "shipment_id":"1008606",
    "user_id":"1048",
    .
    .
    .
    "shipment_created":"false"
  }
],
"hash":"",
"meta":{}
}

/get_all_connote

ENDPOINT: https://myparcelasia.com/api/v1/get_all_connote

USAGE: Retrieve all shipment that has been and paid the connote has been generated for the specific user.

PARAMETERS:
Name Type Rules Remarks
api_key string Required
POST Parameter Example
{
  "api_key":"XXXDEMOKEYXXX"

}
RESPONSE Example
{
"status":true,
"message":"Success",
"data":[
  {
    "id":"1008550",
    "shipment_id":"1008550",
    "user_id":"1048",
    .
    .
    .
    "shipment_created":"true"
  },
  .
  .
  .
  {
    "id":"1008606",
    "shipment_id":"1008606",
    "user_id":"1048",
    .
    .
    .
    "shipment_created":"true"
  }
],
"hash":"",
"meta":{}
}