Web Service Development Guide

MDS Collivery WSDL located at:
http://www.collivery.co.za/wsdl/v2

If you are integrating with us, please let us know as we would like to assist you in the process. We have lots of resources available that could save you a lot of time. Email us on [Enable JavaScript to view email].

The MDS Collivery Web Service is a API that can be used by external programs to speak to our system. It can, amongst other things, create Colliveries, retrieve pricing information, and get the status of a Collivery. For more information, please email us on [Enable JavaScript to view email].

If you are developing in PHP, we have a class available that will do all the hard work for you! Download it here:
Github: https://github.com/Collivery/Collivery-Client
Composer: https://packagist.org/packages/mds/collivery

Table of Contents

  1. SoapFault Error Codes
  2. Rate Limits
  3. Authenticate
  4. Get Towns
  5. Search Towns
  6. Get Suburbs
  7. Get Location Types
  8. Get Services
  9. Get Address
  10. Get Addresses
  11. Get Contacts
  12. Add Address
  13. Add Contact
  14. Get POD
  15. Get Waybill
  16. Get list of parcel images
  17. Get parcel image
  18. Get Collivery Status
  19. Get Parcel Types
  20. Get Price
  21. Validate Collivery
  22. Add Collivery
  23. Accept Collivery

SoapFault Error Codes

Description: Error codes returned when SoapFault is thrown

The following codes are used to identify errors that could surface when using our API. Each error code is returned with an error message. The purpose of the error messages are mainly for debugging. It is recommended that you display a personalized error message to the user or take appropriate action.

Code Description
auth You are not authenticated. Ether you didn't supply a token, or the token you supplied is invalid/expired.
disabled_account Your company account has been disabled
disabled_user Your company has disabled your username
incorrect_login Your username and/or password is incorrect
missing_data You are not supplying all the required data
invalid_data The data you supplied is invalid
invalid_data_type The data you supplied is of a different data type than expected
rate_limit You have reached the maximum number of requests for an account/action/function in a given time
SOAP-ENV:Server There was a problem on our server. Please email [Enable JavaScript to view email] to report it.

Rate Limits

Description: These are the rate limits for our accounts, functions and actions. Should they become a problem to you, please feel free to contact us to discuss custom limits.

Account Limits

Account Daily Limit Hourly Limit Minute Limit
Standard Account 7680 960 240
API Testing Account 600 150 30

Action Limits

Action Daily Limit Hourly Limit Minute Limit Recommendations
Generate New Token 60 30 15 Always send previous token during Authentication. Tokens are valid for 1 hour since last use

Function Limits

Function Daily Limit Hourly Limit Minute Limit Recommendations
authenticate 120 60 15 Token valid for 1 hour since last use
get_towns 120 60 15 Cache for 1 day to 1 week
search_towns 960 240 60 Cache for 1 day to 1 week
get_suburbs 960 240 60 Cache for 1-2 weeks
get_location_types 120 60 15 Cache for 1-2 weeks
get_services 120 60 15 Cache for 1-2 weeks
get_address 480 120 60 Cache for 2 day
get_addresses 480 120 60 Updates a new address is added for the client
get_contacts 480 120 60 Updates when a new contact is added to the address
add_address 480 120 60
add_contact 480 120 60
get_pod 480 120 60 Scanned after delivery between 09:00 and 17:00 if waybill is invoiced
get_waybill 480 120 60 Changes if any of the waybill details change
get_parcel_image_list 120 60 15 Cache for 1 hour
get_parcel_image 120 60 15 Cache for 1 day
get_collivery_status 480 120 60 Cache for 1 hour
get_parcel_types 120 60 15 Cache for 1-2 weeks
get_price 960 240 60 Cache for 1 day
validate_collivery 960 240 60
add_collivery 960 240 60
accept_collivery 960 240 60

Authenticate

Description: Authenticate using your account email and password. It is recommended that you create a new user on your account that will be used with the web service only. Use this username (email) and password to authenticate so you can distinguish between Colliveries added by the web service and those added manually. You can do this using the User Admin tool in collivery.net. Please note that all correspondence for these Colliveries goes to this email address, so make sure it's a valid email that someone reads often. Once authenticated, store the returned token in a session and use that token on every query. Tokens expire after 1 hour of inactivity.

Usage: authenticate(email, password, token, info)

Parameters

Key Data Type Description
email varchar Email address used to login
password varchar Password for the Email address username.
old_token varchar Previously Authenticated token. Store it and use it in every function call. If the token hasn't expired, it will increase its lifetime to an hour and return the same token again. Creating too many tokens could be a security risk, so always send back the previously used token!
info Array (optional) This array can contain any information about your application. This information helps us better our services by understanding its usage. We highly recommend adding name and version to help with debugging later.
info [ name ] varchar(50) (recommended) Name of your application to be identified by.
info [ version ] varchar(50) (recommended) Current Version of your application. eg 2.5.43
info [ host ] varchar(50) (optional) If your application runs on top of another application, eg "Magento 1.8.0.0", "Joomla 1.5.16", "Wordpress 3.6 - WooCommerce 2.0.20"
info [ lang ] varchar(50) (optional) Main programming language(s) used and their version. eg "PHP 5.4.9", "Ruby 1.9.3"
info [ reseller_id ] int (optional) Your Reseller ID (If you have one)

Return Array

Key Data Type Description
client_id integer Your client ID
user_id integer Current user ID
user_email string Current user email address.
default_address_id integer Client Default Address ID
session string Session Information
token string Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity. 
authenticate('api@collivery.co.za', 'demo', '4M8wJGBXC6KKpT0', array('name'=>'Example','version'=>'1.4.7'))
Return Array
(
    [client_id] => 116
    [user_id] => 87
    [user_email] => api@collivery.co.za
    [default_address_id] => 951
    [session] => Active session found
    [token] => 4M8wJGBXC6KKpT0
)

Get Towns

Description: Returns a list of towns and their ID's for creating new addresses. Town can be filtered by country or province (ZAF Only).

Usage: get_towns(token, country = "ZAF", province = null)

Parameters

Key Data Type Description
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.
country varchar (optional) Get towns for a specific country. Defaults to South Africa (ZAF) if none is given. Uses ISO 3166-1 alpha-3 Standard
province varchar (optional) Filter towns for a specific province (South Africa only). CAP, EC, GAU, KZN, MP, NC, NP, NW, OFS

Return Array

Key Data Type Description
towns array Array of Towns (id => name)

Example

get_towns('4M8wJGBXC6KKpT0');
Return Array
(
    [towns] => Array
        (
            [2] => Aberdeen
            [472] => Acornhoek
            [746] => Adams Mission
            [425] => Addo
            [4] => Adelaide
            ...
            [790] => Zinkwazi Beach
            [889] => Zithobeni
            [992] => Zwelitsha
        )
)

Search Towns

Description: Allows you to search for town and suburb names starting with the given string. The minimum string length to search is two characters. Returns a list of towns, suburbs, and the towns the suburbs belong to with their ID's for creating new addresses. The idea is that this could be used in an auto complete function.

Usage: search_towns(town_name, token)

Parameters

Key Data Type Description
town_name varchar Lookup Towns/Suburbs starting with town_name. Requires at least two characters before lookup is done.
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.

Return Array

Key Data Type Description
towns array List of towns matching {town_name}
suburb_towns array List of towns that have suburbs matching {town_name}
suburbs array List of towns id's that have suburbs matching {town_name}
suburbs {town_id} array List of suburbs matching {town_name}

Example

search_towns('Pre', '4M8wJGBXC6KKpT0');
Return Array
(
    [towns] => Array
        (
            [5391] => Preili
            [2875] => Preko
            [2868] => Prelog
            [3110] => Prerov
            [1297] => Presidencia Roque Saenz Pena
            [7509] => Presidente Franco
            [9459] => Prestea
            [248] => Pretoria
        )

    [suburb_towns] => Array
        (
            [83] => Durban
            [147] => Johannesburg
            [357] => Pietermaritzburg
            [248] => Pretoria
        )

    [suburbs] => Array
        (
            [83] => Array
                (
                    [3585] => Prestondale
                )

            [147] => Array
                (
                    [5139] => President Park
                    [1679] => President Park A.H.
                    [1680] => President Ridge
                    [1681] => Presidents Ranch
                    [1682] => Presidentsdam
                    [1690] => Pretoriusstad
                )

            [357] => Array
                (
                    [4190] => Prestbury
                )

            [248] => Array
                (
                    [5069] => Pretoria Central
                    [1684] => Pretoria Gardens
                    [1685] => Pretoria Indust Town
                    [1686] => Pretoria North
                    [5692] => Pretoria Rural
                    [1687] => Pretoria West
                    [1688] => Pretorius Park
                )

        )

)

Get Suburbs

Description: Returns all the suburbs of a specific town and their ID's. Use this ID when creating a new address. Some towns only have a single suburb, with the same name as the town. This is mainly because the town is small enough to not require any additional information.

Usage: get_suburbs(town_id, token)

Parameters

Key Data Type Description
town_id integer ID of the town to retrieve suburbs for. List of Towns can be obtained from the get_towns or search_towns function.
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.

Return Array

Key Data Type Description
town_name string Name of the town.
suburbs array List of suburbs
suburbs {suburb_id} string Suburb Name

Example

get_suburbs(248, '4M8wJGBXC6KKpT0')
Return Array
(
    [town_name] => Pretoria
    [suburbs] => Array
        (
            [5174] => Akasia
            [37] => Alphen Park
            [44] => Amandasig
            ...
            [2433] => Yskor
            [2445] => Zwartkop
            [2448] => Zwavelpoort
        )
)

Get Location Types

Description: Returns the different location types (Private House, Business Premises, Mine) and their ID. This is important when you need an accurate price as some location types may incur a surcharge due to time spent during the delivery.

Usage: get_location_types(token)

Parameters

Key Data Type Description
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.

Return Array

Key Data Type Description
results array List of location types (id => name)

Example

get_location_types('4M8wJGBXC6KKpT0')
Return Array
(
    [results] => Array
        (
            [1] => Business Premises
            [13] => Chain Store
            [11] => Embassy / Consulate
            [3] => Farm / Plot
            [10] => Game Reserve / Resort
            [16] => Gated Suburb
            [4] => Government Building
            [2] => Government Hospital
            [5] => Mine
            [9] => Office Park
            [6] => Power Station
            [15] => Private House
            [12] => Shopping Centre
            [8] => High Risk
            [7] => Trust Area
            [14] => University
        )

)

Get Services

Description: Returns an array of the available Collivery Service Types.

Usage: get_services(token)

Parameters

Key Data Type Description
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.

Return Array

Key Data Type Description
services array List of available services and their ID's. (id => name)

Example

get_services('4M8wJGBXC6KKpT0')
Return Array
(
    [services] => Array
        (
            [1] => Overnight Before 10:00
            [2] => Overnight before 16:00
            [5] => Road Freight Express
            [3] => Road Freight
        )

)

Get Address

Description: Returns all the information of a single address ID.

Usage: get_address(address_id, token)

Parameters

Key Data Type Description
address_id integer Address ID
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.

Return Array

Key Data Type Description
address array Array containing all the addresses
address [ address_id ] integer Address ID
address [ custom_id ] varchar(20) A Unique identifier you may use to search for this address or group a number of addresses together.
address [ client_id ] integer Your Client ID
address [ suburb_id ] integer ID of the Suburb for this address. List of Suburbs can be obtained from the get_suburbs or search_towns function.
address [ suburb_name ] string Address Suburb Name
address [ town_id ] integer Town ID of the town for this address. List of Towns can be obtained from the get_towns or search_towns function.
address [ town_name ] string Address Town Name
address [ location_type ] integer Address Location Type. The list of Location ID’s can be obtained from the get_location_types function.
address [ company_name ] string Company Name
address [ building_details ] string Building Details
address [ street ] string Street name and house number
address [ street_name ] string (Deprecated) Support for legacy addresses that have name and number separate. This will not be supported in the next version.
address [ street_no ] string (Deprecated) Support for legacy addresses that have name and number separate. This will not be supported in the next version.
address [ province ] string The Nine South African Provinces (Only if South African address): EC, FS, GP, KZN, LP, MP, NC, NW, WC
address [ country_brief ] string Uses ISO 3166-1 alpha-3 Standard.
address [ country_name ] string Country Name
address [ surcharge ] float Surcharges added for address
address [ nice_address ] string Company, Building Details, Street, Suburb, Town

Example

get_address(515872, '4M8wJGBXC6KKpT0')
Return Array
(
    [address] => Array
        (
            [address_id] => 515872
            [custom_id] =>
            [client_id] => 116
            [suburb_id] => 1936
            [suburb_name] => Selby
            [town_id] => 147
            [town_name] => Johannesburg
            [location_type] => 1
            [company_name] => MDS Collivery
            [building_details] => MDs House
            [street] => 58c Webber St
            [street_name] => Webber St
            [street_no] => 58c
            [province] => GAU
            [country_brief] => ZAF
            [country_name] => SOUTH AFRICA
            [surcharge] => 0.00
            [nice_address] => MDS Collivery, MDs House, 58c Webber St, Selby, Johannesburg
        )

)

Get Addresses

Description: Returns all the addresses belonging to a client and their Information.

Usage: get_addresses(token, filter)

Parameters

Key Data Type Description
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.
filter array (Optional)
filter [ company_name ] string (Optional) Show only addresses where the company name contains company_name
filter [ town_id ] integer (Optional) Show only addresses for this Town ID.
filter [ suburb ] varchar (Optional) Show only addresses for this Suburb Name.
filter [ custom_id ] varchar(20) (Optional) Search for your Custom ID.

Return Array

Key Data Type Description
addresses array Array containing all the addresses
addresses {address_id} array Array containing all the address fields
addresses {address_id} [ address_id ] integer Address ID
addresses {address_id} [ custom_id ] varchar(20) A Unique identifier you may use to search for this address or group a number of addresses together.
addresses {address_id} [ client_id ] integer Your Client ID
addresses {address_id} [ suburb_id ] integer ID of the Suburb for this address. List of Suburbs can be obtained from the get_suburbs or search_towns function.
addresses {address_id} [ suburb_name ] string Address Suburb Name
addresses {address_id} [ town_id ] integer Town ID of the town for this address. List of Towns can be obtained from the get_towns or search_towns function.
addresses {address_id} [ town_name ] string Address Town Name
addresses {address_id} [ location_type ] integer Address Location Type. The list of Location ID’s can be obtained from the get_location_types function.
addresses {address_id} [ company_name ] string Company Name
addresses {address_id} [ building_details ] string Building Details
addresses {address_id} [ street ] string Street name and house number
addresses {address_id} [ street_name ] string (Deprecated) Support for legacy addresses that have name and number separate. This will not be supported in the next version.
addresses {address_id} [ street_no ] string (Deprecated) Support for legacy addresses that have name and number separate. This will not be supported in the next version.
addresses {address_id} [ province ] string The Nine South African Provinces (Only if South African address): EC, FS, GP, KZN, LP, MP, NC, NW, WC
addresses {address_id} [ country_brief ] array Uses ISO 3166-1 alpha-3 Standard
addresses {address_id} [ country_name ] string Country Name
addresses {address_id} [ surcharge ] float Surcharges added for address
addresses {address_id} [ nice_address ] array Company, Building Details, Street, Suburb, Town

Example

get_addresses('4M8wJGBXC6KKpT0')
Return Array
(
    [addresses] => Array
        (
            [515872] => Array
                (
                    [address_id] => 515872
                    [custom_id] =>
                    [client_id] => 116
                    [suburb_id] => 1936
                    [suburb_name] => Selby
                    [town_id] => 147
                    [town_name] => Johannesburg
                    [location_type] => 1
                    [company_name] => MDS Collivery
                    [building_details] => MDS House
                    [street] => 58c Webber St
                    [street_name] => Webber St
                    [street_no] => 58c
                    [province] => GAU
                    [country_brief] => ZAF
                    [country_name] => SOUTH AFRICA
                    [surcharge] => 0.00
                    [nice_address] => MDS Collivery, MDS House, 58c Webber St, Selby, Johannesburg
                )

            ...

            [283817] => Array
                (
                    [address_id] => 283817
                    [custom_id] =>
                    [client_id] => 116
                    ...
                    [surcharge] => 14.00
                    [nice_address] => MDS Mafikeng, 23 Mafikeng Street, Mafikeng
                )
            ...
        )
)

Get Contacts

Description: Returns all the contacts belonging to a spesific address.

Usage: get_contacts(address_id, token)

Parameters

Key Data Type Description
address_id integer Address you wish to get clients for.
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.

Return Array

Key Data Type Description
contacts array Array containing all the contacts for the address.
contacts {contact_id} array Array containing all the information for the contact.
contacts {contact_id} [ contact_id ] integer Contact ID
contacts {contact_id} [ address_id ] integer Address ID
contacts {contact_id} [ full_name ] string Contacts Full Name
contacts {contact_id} [ phone ] string Contacts Phone Number
contacts {contact_id} [ cellphone ] string Contacts Cellphone Number
contacts {contact_id} [ email ] string Contacts Email Address
contacts {contact_id} [ nice_contact ] string Name, Number, Email

Example

get_contacts(419521, '4M8wJGBXC6KKpT0');
Return Array
(
    [contacts] => Array
        (
            [657544] => Array
                (
                    [contact_id] => 659945
                    [address_id] => 419521
                    [full_name] => Bernhard Breytenbach
                    [phone] =>
                    [cellphone] => 0123456789
                    [email] => email@domain.co.za
                    [nice_contact] => Bernhard Breytenbach, 0123456789, email@domain.co.za
                )
            ...
            [659945] => Array
                (
                    [contact_id] => 659945
                    ...
                    [nice_contact] => Bernhard Breytenbach, 9876543210, myemail@mydomain.com
                )
            ...
        )
)

Add Address

Description: Adds a new address to the your account on the Collivery system.

Usage: add_address(data, token)

Parameters

Key Data Type Description
data array Array containing the information for the address.
data [ company_name ] varchar(50) (Recommended) Company Name. Defaults to {full_name}
data [ building ] varchar(50) (Optional) Building name or extra information
data [ street ] varchar(50) Street name and house number
data [ location_type ] integer Location Type ID. Due to some types of deliveries incurring surcharges (eg. Government Buildings / Embassies / Farms / Plots), it is important to know, up front, the type of address we will be delivering to. The list of Location ID’s can be obtained by the get_location_types function.
data [ suburb_id ] integer ID of the Suburb for this address. The Suburb MUST belong to the given town. List of Suburbs can be obtained from the get_suburbs or search_towns function.
data [ town_id ] integer Town ID of the town for this address. List of Towns can be obtained from the get_towns or search_towns function.
data [ country ] varchar (optional) Country the address is in. Defaults to South Africa (ZAF) if none is given. Uses ISO 3166-1 alpha-3 Standard.
data [ zip_code ] varchar (Optional) Address Zip/Postal Code
data [ custom_id ] varchar(20) (optional) A Unique identifier you may use to search for this address or group a number of addresses together.
data [ full_name ] varchar(50) Contact person's full name and surname.
data [ phone ] varchar(20) Contact person's phone number.
data [ cellphone ] varchar(20) Contact person's cellphone number.
data [ email ] varchar(50) Contact person's email address. This is VERY Important if you need MDS Collivery to send the standard email notifications to the contact of pending delivery request.
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.

Return Array

Key Data Type Description
address_id integer Address ID
contact_id integer Contact ID

Example

data = Array
(
    [company_name] => MDS Collivery
    [building] => MDS House
    [street] => 58c Webber St
    [location_type] => 5
    [suburb_id] => 1936
    [town_id] => 147
    [custom_id] => AF65549
    [full_name] => Bernhard Breytenbach
    [phone] => 0123456789
    [cellphone] => 0834567912
    [email] => name@domain.co.za
)
add_address(data, '4M8wJGBXC6KKpT0')
Array
(
    [address_id] => 6035953
    [contact_id] => 6294617
)

Add Contact

Description:

Usage: add_contact(data, token)

Parameters

Key Data Type Description
data [ address_id ] integer Address ID you wish to add a contact for.
data [ full_name ] varchar(50) Contact person's full name and surname.
data [ phone ] varchar(20) Contact person's phone number.
data [ cellphone ] varchar(20) Contact person's cellphone number.
data [ email ] varchar(50) Contact person's email address. This is VERY Important if you need MDS Collivery to send the standard email notifications to the contact of pending delivery request.
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.

Return Array

Key Data Type Description
contact_id integer Contact ID

Example

data = Array
(
    [address_id] => 6035953
    [full_name] => Bernhard Breytenbach
    [phone] => 0123456789
    [cellphone] => 0834567912
    [email] => name@domain.co.za
)
add_contact(data, '4M8wJGBXC6KKpT0')
Array
(
    [contact_id] => 6294618
)

Get Proof of Delivery

Description: Returns the POD image for a given Waybill Number.

Usage: get_pod(collivery_id, token)

Parameters

Key Data Type Description
collivery_id integer Waybill number for the requested POD.
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.

Return Array

Key Data Type Description
pod array Contains the POD and its information.
pod [ size ] integer Size of the POD in bytes.
pod [ mime ] string File mime
pod [ filename ] string File Name
pod [ file ] string Base64 encoded file

Example

get_pod(55555, '4M8wJGBXC6KKpT0')
Return Array
(
    [pod] => Array
        (
            [size] => 31474
            [mime] => image/pdf
            [filename] => 55555.pdf
            [file] => SUkqAER6AAD///ymHctrgQ7uCDIfDJDhhUe4W0Da9hbth9oH+6j/...............EAAAACAAAAAAAAAA==
       )
)

Get Waybill Pdf

Description: Returns the Waybill image for a given Waybill Number.

Usage: get_waybill(collivery_id, token)

Parameters

Key Data Type Description
collivery_id integer Waybill number for the requested POD.
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.

Return Array

Key Data Type Description
waybill array Contains the waybill and its information.
waybill [ size ] integer Size of the waybill in bytes.
waybill [ mime ] string File mime
waybill [ filename ] string File Name
waybill [ file ] string Base64 encoded file

Example

get_waybill(55555, '4M8wJGBXC6KKpT0')
Return Array
(
    [waybill] => Array
        (
            [size] => 31474
            [mime] => image/pdf
            [filename] => 55555.pdf
            [file] => SUkqAER6AAD///ymHctrgQ7uCDIfDJDhhUe4W0Da9hbth9oH+6j/...............EAAAACAAAAAAAAAA==
       )
)

Get list of parcel images

Description: Returns a list of available parcel images and their info for a given Waybill Number.

Usage: get_parcel_image_list(collivery_id, token)

Parameters

Key Data Type Description
collivery_id integer Waybill number for the requested images.
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.

Return Array

Key Data Type Description
images array Contains a list of images for given Waybill number.
images {parcel_id} array Contains information about the image
images {parcel_id} [ size ] integer Size of the POD in bytes.
images {parcel_id} [ mime ] string File mime
images {parcel_id} [ filename ] string File Name
images {parcel_id} [ parcel_id ] string Parcel ID

Example

get_parcel_image_list(55555, '4M8wJGBXC6KKpT0')
Return Array
(
    [images] => Array
        (
            [55555-1] => Array
                (
                    [size] => 21403
                    [mime] => image/jpeg
                    [filename] => 55555-1.jpg
                    [parcel_id] => 55555-1
                )

            [55555-2] => Array
                (
                    [size] => 26835
                    [mime] => image/jpeg
                    [filename] => 55555-2.jpg
                    [parcel_id] => 55555-2
                )

        )

)

Get Parcel Image

Description: Returns a image encoded in BASE 64 and its information for a given parcel ID.

Usage: get_parcel_image(parcel_id, token)

Parameters

Key Data Type Description
parcel_id string Parcel ID for the requested image. Can be obtained by using the get_parcel_image_list function.
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.

Return Array

Key Data Type Description
image array Contains the POD and its information.
image [ size ] integer Size of the POD in bytes.
image [ mime ] string File mime
image [ filename ] string File Name
image [ file ] string Base64 encoded image

Example

get_parcel_image(parcel_id, '4M8wJGBXC6KKpT0')
Return Array
(
    [image] => Array
        (
            [size] => 26835
            [mime] => image/jpeg
            [filename] => 55555-2.jpg
            [file] => /9j/4AAQSkZJRgABAQAAAQABAAD/...............c3B+td3f6hetbspvLgqwIYGVsEeh5rgdSOblqHK7HFWP/Z
        )

)

Get Collivery Status

Description: Returns the status tracking detail of a given Waybill number. If the Collivery is still active, the estimated time of delivery will be provided. If delivered, the time and receivers name (if available) is returned.

Usage: get_collivery_status(collivery_id, token)

Parameters

Key Data Type Description
collivery_id integer Waybill number to get status for.
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.

Return Array

Key Data Type Description
[ status_id ] integer Current Status ID
[ status_text ] string Current Status Text
[ delivery_date ] string Date of Delivery
[ delivery_time ] string Parcel will be delivered before this time.
[ updated_date ] string Updated Date
[ updated_time ] string Updated Time
[ total_price ] float The Total Price for this Collivery.
[ collection_latitude ] float Latitude co-ordinate of the collection address.
[ collection_longitude ] float Longitude co-ordinate of the collection address.
[ delivery_latitude ] float Latitude co-ordinate of the delivery address.
[ delivery_longitude ] float Longitude co-ordinate of the delivery address.
[ eta ] integer Unix timestamp for Estimated Time of Arrival.
[ eta_text ] string Date Time String for Estimated Time of Arrival.

Example

get_collivery_status(55555, '4M8wJGBXC6KKpT0')
Return Array
(
    [status_id] => 15
    [status_text] => Delivery Driver Dispatched
    [delivery_date] => 2013-08-08
    [delivery_time] => 16:00:00
    [updated_time] => 08:29:40
    [updated_date] => 2013-08-08
    [total_price] => 57.55
    [collection_latitude] => -25.000000
    [collection_longitude] => 25.000000
    [delivery_latitude] => -30.000000
    [delivery_longitude] => 30.000000
    [eta] => 1375969569
    [eta_text] => 2013-08-08 15:46:09
)

Get Parcel Types

Description: Returns the available Parcel Type ID and value array for use in adding a Collivery.

Usage: get_parcel_types(token)

Parameters

Key Data Type Description
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.

Return Array

Key Data Type Description
{parcel_type_id} array Contains information about the Parcel Type
{parcel_type_id} [ type_text ] string Name of Parcel Type
{parcel_type_id} [ type_description ] string Parcel Type Description

Example

get_parcel_types('4M8wJGBXC6KKpT0')
Return Array
(
    [1] => Array
        (
            [type_text] => Envelope
            [type_description] => Documents less than 2Kg and A4 size
        )

    [2] => Array
        (
            [type_text] => Package
            [type_description] => Parcel Exceeding 2Kg and any dimension above 20cm
        )

    [3] => Array
        (
            [type_text] => Tender Documents
            [type_description] => Documents for lodging Tenders
        )
)

Get Price

Description: Returns an price for the current delivery. Very similar to the Validate Function, however, address ID, and Contact ID can be replaced with Town ID and Location Type - however getting the price without a specific address it isn't as accurate as certain surcharges can't be calculated.

Usage: get_price(data, token)

Parameters

Key Data Type Description
data array Contains all the information of the Collivery to get a price for.
data [ collivery_from ]* integer Address ID where the parcel should be collected from. The list of Address ID’s can be obtained from the get_addresses function.
* Can be replaced with from_town_id and from_location_type.
data [ from_town_id ]* integer Town ID where the parcel should be collected from. The list of Town ID’s can be obtained from the get_towns function.
* Can be replaced with collivery_from.
data [ from_location_type ]* integer Location Type where the parcel should be collected from. The list of Location Types can be obtained from the get_location_types function.
* Can be replaced with collivery_from.
data [ collivery_to ]* integer Address ID where the parcel should be delivered to. The list of Address ID’s can be obtained from the get_addresses function.
* Can be replaced with to_town_id and to_location_type.
data [ to_town_id ]* integer Town ID where the parcel should be delivered to. The list of Town ID’s can be obtained from the get_towns function.
* Can be replaced with collivery_to.
data [ to_location_type ]* integer Location Type where the parcel should be delivered to. The list of Location Types can be obtained from the get_location_types function.
* Can be replaced with collivery_to.
data [ collivery_type ] integer ID of the Parcel Type from the get_parcel_types function.
data [ service ] integer ID of service type from the get_services function.
data [ cover ] int (0/1) Let MDS Collivery carry the risk on this consignment up to a maximum of R10 000.00.
1 for true, 0 for false. Defaults to 0.
data [ rica ] int (0/1) This delivery requires rica information to be issued.
data [ exclude_weekend ] integer Exclude Weekends to avoid additional surcharges.
1 for true, 0 for false. Defaults to 1.
data [ collection_time ] integer (optional) Unix Time for the time it will be collected. The system will calculate and return the collection time if none is given.
data [ parcel_count ] integer (optional if parcel array is given) Number to parcels for this Collivery. This will be replaced with the array count in the parcel array.
data [ weight ] decimal (optional if parcel array is given) Total weight of consignment rounded to 1 decimal point. This will be replaced with the weight sum of the weights in the parcel array.
data [ parcels ] array (Highly recommended, as volumetric weight will be calculated using the parcel array. We can't give a final price without accurate dimensions of every parcel. Please contact [Enable JavaScript to view email] for more information.) Contains the list of parcels for shipping
data [ parcels ] [ {int} ] array Contains information about the parcel
data [ parcels ] [ {int} ] [ weight ] decimal The weight of the parcel in kg
data [ parcels ] [ {int} ] [ height ] decimal The height of the parcel in cm
data [ parcels ] [ {int} ] [ length ] decimal The length of the parcel in cm
data [ parcels ] [ {int} ] [ width ] decimal The width of the parcel in cm
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.

Return Array

Key Data Type Description
[ collivery_from ] integer Address ID where the parcel should be collected from. The list of Address ID’s can be obtained from the get_addresses function.
[ from_town_id ] integer Town ID where the parcel should be collected from. The list of Town ID’s can be obtained from the get_towns function. Will be replaced by collivery_from.
[ from_location_type ] integer Location Type where the parcel should be collected from. The list of Location Types can be obtained from the get_location_types function. Will be replaced by collivery_from.
[ collivery_to ] integer Address ID where the parcel should be delivered to. The list of Address ID’s can be obtained from the get_addresses function.
[ to_town_id ] integer Town ID where the parcel should be delivered to. The list of Town ID’s can be obtained from the get_towns function. Will be replaced by collivery_to.
[ to_location_type ] integer Location Type where the parcel should be delivered to. The list of Location Types can be obtained from the get_location_types function. Will be replaced by collivery_to.
[ collivery_type ] integer ID of the Parcel Type from the get_parcel_types function.
[ parcel_count ] integer Number to parcels for this Collivery. This should match the array count of the parcel dimensions array.
[ weight ] decimal Total weight of consignment rounded to 1 decimal point
[ service ] integer ID of service type from the get_services function.
[ cover ] int (0/1) Let MDS Collivery carry the risk on this consignment up to a maximum of R10 000.00.
1 for true, 0 for false. Defaults to 0.
[ vm_divisor ] integer This is used to calculate the Volumetric weight using (length*width*height)/vm_divisor
[ vol_weight ] decimal Volumetric weight. If the Volumetric weight is more than the actual weight, the volumetric weight will be used instead.
[ collection_time ] integer Unix Time for the time it will be collected.
[ price ] array Contains different pricing information.
[ price ] [ ex_vat ] decimal Price of the Collivery excluding vat.
[ price ] [ inc_vat ] decimal Price of the Collivery including vat.
[ price ] [ vat ] decimal Total vat paid for the Collivery
[ price ] [ inc_weight ] decimal The initial included weight.
[ price ] [ rate_per_kg ] decimal Rate per Kilogram after the initial included weight.
[ parcels ] array Contains the list of parcels for shipping
[ parcels ] [ {int} ] array Contains information about the parcel
[ parcels ] [ {int} ] [ weight ] decimal The weight of the parcel in kg
[ parcels ] [ {int} ] [ height ] decimal The height of the parcel in cm
[ parcels ] [ {int} ] [ length ] decimal The length of the parcel in cm
[ parcels ] [ {int} ] [ width ] decimal The width of the parcel in cm
[ parcels ] [ {int} ] [ vol_weight ] decimal The volumetric weight of the parcel in kg

Example

data = Array
(
    [collivery_from] => 605978
    [contact_from] => 629614
    [collivery_to] => 605536
    [contact_to] => 629151
    [collivery_type" => 2
    [weight] => 6
    [service] => 5
    [cover] => true
    [parcels] => Array
        (
            [0] => Array
                (
                    [weight] => 2
                    [height] => 10
                    [length] => 12
                    [width] => 7
                )
            [1] => Array
                (
                    [weight] => 4
                    [height] => 3
                    [length] => 17
                    [width] => 19
                )
        )
)
get_price(data, '4M8wJGBXC6KKpT0')
Array
(
    [collivery_from] => 951
    [to_town_id] => 248
    [to_location_type] => 15
    [collivery_type] => 2
    [weight] => 1
    [exclude_weekend] => 1
    [service] => 2
    [collection_time] => 1376985600
    [cover] => 1
    [parcel_count] => 1
    [vm_divisor] => 5000
    [vol_weight] => 1.9
    [parcels] => Array
        (
            [0] => Array
                (
                    [weight] => 1
                    [height] => 30
                    [length] => 17
                    [width] => 19
                    [vol_weight] => 1.938
                )

        )

    [delivery_type] => local
    [price] => Array
        (
            [ex_vat] => 82.81
            [inc_vat] => 94.4
            [vat] => 11.59
            [vat_pct] => 14
            [inc_weight] => 2
            [rate_per_kg] => 6.48
        )

)

Validate Collivery

Description: Returns the validated data array of all details pertaining to a Collivery. This process validates the information based on services, time frames and parcel information. Dates and times may be altered during this process based on the collection and delivery towns service parameters. Certain towns are only serviced on specific days and between certain times. This function automatically alters the values. The parcels volumetric calculations are also done at this time. It is important that the data is first validated before a Collivery can be added.

Usage: validate_collivery(data, token)

Parameters

Key Data Type Description
data array Contains all the information of the new Collivery.
data [ collivery_from ] integer Address ID where the parcel should be collected from. The list of Address ID’s can be obtained from the get_addresses function.
data [ contact_from ] integer Contact ID of the person from whom the parcel should be collected from. This is linked to the selected Address ID. The list of Contacts for a specific address can be obtained from the get_contacts function.
data [ collivery_to ] integer Address ID where the parcel should be delivered to. The list of Address ID’s can be obtained from the get_addresses function.
data [ contact_to ] integer Contact ID of the person from whom the parcel should be delivered to. This is linked to the selected Address ID. The list of Contacts for a specific address can be obtained from the get_contacts function.
data [ collivery_type ] integer ID of the Parcel Type from the get_parcel_types function.
data [ service ] integer ID of service type from the get_services function.
data [ cover ] int (0/1) Let MDS Collivery carry the risk on this consignment up to a maximum of R10 000.00.
1 for true, 0 for false. Defaults to 0.
data [ rica ] int (0/1) This delivery requires rica information to be issued.
data [ collection_time ] integer (optional) Unix Time for the time it will be collected. The system will calculate and return the collection time if none is given.
data [ parcel_count ] integer (optional if parcel array is given) Number to parcels for this Collivery. This will be replaced with the array count in the parcel array.
data [ weight ] decimal (optional if parcel array is given) Total weight of consignment rounded to 1 decimal point. This will be replaced with the weight sum of the weights in the parcel array.
data [ parcels ] array (Highly recommended, as volumetric weight will be calculated using the parcel array. We can't give a final price without accurate dimensions of every parcel. Please contact [Enable JavaScript to view email] for more information.) Contains the list of parcels for shipping
data [ parcels ] [ {int} ] array Contains information about the parcel
data [ parcels ] [ {int} ] [ weight ] decimal The weight of the parcel in kg
data [ parcels ] [ {int} ] [ height ] decimal The height of the parcel in cm
data [ parcels ] [ {int} ] [ length ] decimal The length of the parcel in cm
data [ parcels ] [ {int} ] [ width ] decimal The width of the parcel in cm
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.

Return Array

Key Data Type Description
[ collivery_from ] integer Address ID where the parcel should be collected from. The list of Address ID’s can be obtained from the get_addresses function.
[ contact_from ] integer Contact ID of the person from whom the parcel should be collected from. This is linked to the selected Address ID. The list of Contacts for a specific address can be obtained from the get_contacts function.
[ collivery_to ] integer Address ID where the parcel should be delivered to. The list of Address ID’s can be obtained from the get_addresses function.
[ contact_to ] integer Contact ID of the person from whom the parcel should be delivered to. This is linked to the selected Address ID. The list of Contacts for a specific address can be obtained from the get_contacts function.
[ collivery_type ] integer ID of the Parcel Type from the get_parcel_types function.
[ parcel_count ] integer Number to parcels for this Collivery. This should match the array count of the parcel dimensions array.
[ weight ] decimal Total weight of consignment rounded to 1 decimal point
[ service ] integer ID of service type from the get_services function.
[ cover ] int (0/1) Let MDS Collivery carry the risk on this consignment up to a maximum of R10 000.00.
1 for true, 0 for false. Defaults to 0.
[ vm_divisor ] integer This is used to calculate the Volumetric weight using (length*width*height)/vm_divisor
[ vol_weight ] decimal Volumetric weight. If the Volumetric weight is more than the actual weight, the volumetric weight will be used instead.
[ collection_time ] integer Unix Time for the time it will be collected.
[ delivery_time ] integer Unix Time for the time it will be delivered.
[ time_changed ] int (0/1) Was the time adjusted?
1 for true, 0 for false.
[ time_changed_reason ] string The reason the time was changed.
[ price ] array Contains different pricing information.
[ price ] [ ex_vat ] decimal Price of the Collivery excluding vat.
[ price ] [ inc_vat ] decimal Price of the Collivery including vat.
[ price ] [ vat ] decimal Total vat paid for the Collivery
[ price ] [ inc_weight ] decimal The initial included weight.
[ price ] [ rate_per_kg ] decimal Rate per Kilogram after the initial included weight.
[ parcels ] array Contains the list of parcels for shipping
[ parcels ] [ {int} ] array Contains information about the parcel
[ parcels ] [ {int} ] [ weight ] decimal The weight of the parcel in kg
[ parcels ] [ {int} ] [ height ] decimal The height of the parcel in cm
[ parcels ] [ {int} ] [ length ] decimal The length of the parcel in cm
[ parcels ] [ {int} ] [ width ] decimal The width of the parcel in cm
*Own Index Names* Any additional fields sent to the validate function will be returned untouched. This is useful if you wish to already set the data that will be passed to the add_collivery function without adding them later.

Example

data = Array
(
    [collivery_from] => 605978
    [contact_from] => 629614
    [collivery_to] => 605536
    [contact_to] => 629151
    [collivery_type" => 2
    [weight] => 6
    [service] => 5
    [cover] => true
    [parcels] => Array
        (
            [0] => Array
                (
                    [weight] => 2
                    [height] => 10
                    [length] => 12
                    [width] => 7
                )
            [1] => Array
                (
                    [weight] => 4
                    [height] => 3
                    [length] => 17
                    [width] => 19
                )
        )
)
validate_collivery(data, '4M8wJGBXC6KKpT0')
Array
(
    [collivery_from] => 605978
    [contact_from] => 629614
    [collivery_to] => 605536
    [contact_to] => 629151
    [collivery_type] => 2
    [weight] => 0
    [service] => 5
    [cover] => 1
    [parcels] => Array
        (
            [0] => Array
                (
                    [weight] => 2
                    [height] => 10
                    [length] => 12
                    [width] => 7
                )
            [1] => Array
                (
                    [weight] => 4
                    [height] => 3
                    [length] => 17
                    [width] => 19
                )
        )
    [count_changed] => No parcel_count found. Updating count to 2
    [parcel_count] => 2
    [vm_divisor] => 4500
    [vol_weight] => 1
    [collection_time] => 1375452000
    [collection_year] => 2013
    [collection_month] => 08
    [collection_day] => 02
    [collection_hour] => 16
    [collection_minute] => 0
    [delivery_time] => 1375884000
    [delivery_year] => 2013
    [delivery_month] => 08
    [delivery_day] => 04
    [delivery_hour] => 16
    [delivery_minute] => 0
    [time_changed_reason] => Time Changed : Road Freight Express Service will deliver by end of 2 working days.The minimum delivery time frame for this collivery is 72 working hours. The delivery time has been CHANGED to Wednesday, 7 Aug 2013
    [time_changed] => 1
    [min_hours] => 72
    [price] => Array
        (
            [ex_vat] => 103.00
            [inc_vat] => 117.42
            [vat] => 14.42
            [vat_pct] => 14
            [inc_weight] => 5
            [rate_per_kg] => 9.56
        )

)

Add Collivery

Description: Creates a new Collivery based on the data array provided. The array should first be validated before passing to this function. The Waybill No is return upon successful creation of the Collivery.

Usage: add_collivery(data, token)

Parameters

Key Data Type Description
data array Should contain the array returned by the validate function WITHOUT any changes! If you need to make adjustments to the information, first re-validate it before passing it to the add_collivery function.
data [ ignore_validation_change ] integer (Optional, Not Recommended) Do not check if anything (Time, Pricing, Information) changed since previous validation. This should only be used if you do not care about the information returned by the validate function.
data [ cust_ref ] varchar(30) (optional) Customer reference number.
data [ custom_id ] varchar(25) (optional) Alternative waybill number for tracking parcel using clients waybill number. Should start with an Alpha Character.
data [ instructions ] varchar(4096) (optional) Extra instructions a user might want to provide.
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.

Return Array

Key Data Type Description
[ collivery_id ] integer ID of the Collivery. Store it for later use.
[ collection_time ] integer Unix Time for the time it will be collected.
[ delivery_time ] integer Unix Time for the time it will be delivered.
[ weight ] decimal Total weight of consignment rounded to 1 decimal point
[ vol_weight ] decimal Volumetric weight. If the Volumetric weight is more than the actual weight, the volumetric weight will be used instead.
[ price ] array Contains different pricing information.
[ price ] [ ex_vat ] decimal Price of the Collivery excluding vat.
[ price ] [ inc_vat ] decimal Price of the Collivery including vat.
[ price ] [ vat ] decimal Total vat paid for the Collivery
[ price ] [ inc_weight ] decimal The initial included weight.
[ price ] [ rate_per_kg ] decimal Rate per Kilogram after the initial included weight.
[ parcels ] array Contains the list of parcels for shipping
[ parcels ] [ {int} ] array Contains information about the parcel
[ parcels ] [ {int} ] [ weight ] decimal The weight of the parcel in kg
[ parcels ] [ {int} ] [ height ] decimal The height of the parcel in cm
[ parcels ] [ {int} ] [ length ] decimal The length of the parcel in cm
[ parcels ] [ {int} ] [ width ] decimal The width of the parcel in cm
[ parcels ] [ {int} ] [ parcel_label ] string Label used to reference that specific parcel. Used in the get_image function
[ parcels ] [ {int} ] [ vol_weight ] decimal The volumetric weight of the parcel.

Example

validated_data = validate_collivery(data, '4M8wJGBXC6KKpT0')
add_collivery(validated_data, '4M8wJGBXC6KKpT0')
Array
(
    [parcels] => Array
        (
            [0] => Array
                (
                    [weight] => 5
                    [height] => 12
                    [length] => 8
                    [width] => 39
                    [parcel_label] => 1182483-1
                    [vol_weight] => 0.8
                )

            [1] => Array
                (
                    [weight] => 1
                    [height] => 30
                    [length] => 17
                    [width] => 19
                    [parcel_label] => 1182483-2
                    [vol_weight] => 2.2
                )

        )

    [collivery_id] => 1182483
    [collection_time] => 1376316000
    [delivery_time] => 1376575200
    [weight] => 6
    [vol_weight] => 3
    [price] => Array
        (
            [ex_vat] => 237.32
            [inc_vat] => 270.54
            [vat] => 33.22
            [vat_pct] => 14
            [inc_weight] => 5
            [rate_per_kg] => 9.56
        )

)

Accept Collivery

Description: Processes the newly created Collivery from Waiting Acceptance to Accepted.

Usage: accept_collivery(collivery_id, token)

Parameters

Key Data Type Description
collivery_id integer ID of the Collivery you wish to Accept
token varchar(15) Obtained after authenticating. Store it and use it in every function call. Tokens expire after 1 hour of inactivity.

Return Array

Key Data Type Description
[ result ] string Should say "Accepted".

Example

accept_collivery(1182483, '4M8wJGBXC6KKpT0')
Array
(
    [result] => Accepted
)
Back to Top
like twtr linkedin

We use cookies and similar technologies to help personalise content, tailor and measure ads, and provide a better experience. By clicking OK or turning an option on in Cookie Preferences, you agree to this as outlined in our Cookie Policy. To change preferences or withdraw consent, please update your Cookie Preferences.