Parcel Perfect Integration Service v7

Overview

PPIntegrationService is a web services interface between a system submitting waybill, POD and event
data to a Parcel Perfect environment.

Environment

Methods are exposed via both REST-based Json and SOAP end points. Documentation and examples are
provided for both.

Testing environment

You will need to obtain a test account from Parcel Perfect. Email [email protected] with the
subject: Request for ppintegration test account . Please provide your contact details and which courier /
transport provider you are working with.

On approval, you will be provided a username, password and account number.

Documentation and examples

You can find all supporting documentation and examples to run in the test environment at
http://adpdemo.pperfect.com/ppintegrationservice/v7/downloads/

End Point URLs

Type URL
Json end point http://adpdemo.pperfect.com/ppintegrationservice/v7/Json/
SOAP end point http://adpdemo.pperfect.com/ppintegrationservice/v7/Soap/
SOAP WSDL http://adpdemo.pperfect.com/ppintegrationservice/v7/Soap/index.php?wsdl

Authentication

Methods – Full API Specification at end of document

Method Function
getSalt On submitting the user name the method returns a salt value
getToken On submitting the user name and encrypted password using the
salt value and the user password, this method passes back a token
expireToken Calling this method invalidates the existing token

In order to use the web-services, one must first authenticate by getting a security token. All methods
within the PPIntegrationService other than the Auth class require the token to be submitted with the
request.

v7 Page | 1
 With your username and password, first get a salt from the end point URL. Encrypt the salt with MD5 and
use your username and encrypted password to get a token.

The token is valid until you call the expireToken method.

Authentication method flow

Username encrypted
Password getSalt salt md5pass getSecureToken Token
End Point URL password

Submitting data to the PPIntergation service

Methods – Full API Specification at end of document

Method Function
submitWaybill Use this method to submit waybill details along with contents,
tracking numbers and references
submitPOD Submit POD Details
submitEvent Submit parcel level tracking events. Used when each piece of a
consignment has tracking events.
submitWaybillEvent Used when a tracking event relates to an entire consignment.
getSingleWaybill Returns full waybill details by submitting a waybill no.
submitPodImage Allows the submission of a POD image

JSon / SOAP API Specification

Please note the ‘Required’ field notes if the field is required for the method to pass back a successful
result.

Class – Auth – Input parameters

Method Parameter Type Req Description

expireToken token_id string Y token id
getSalt email string Y user name, commonly an email addr
getSecureToken email string Y user name, commonly an email addr
password string Y encrypted password

Class – Auth – Output parameters

Method Parameter Type Description

expireToken none none
getSalt salt string generated salt string
getSecureToken token_id string generated token

Page | 2
Class – Waybill, POD, Event – Input parameters

Method Parameter Type Req Description

submitWaybill details array[..] Y details for waybill/quote
contents array[..] Y freight contents of waybill/quote
wayrefs array[..] N multiple references
tracks array[..] N tracking numbers for waybill

submitWaybill[details] waybill string[24] N quote or waybill number

accnum string[6] Y customer account number
costcentre integer N customer costcentre
service string[3] N transport service
waydate string[10] N waybill date
origpers string[35] N sender name or consignor
origperadd1 string[30] N senders address line 1
origperadd2 string[30] N senders address line 2
origperadd3 string[30] N senders address line 3
origperadd4 string[30] N senders address line 4
origtown string[50] N originating town / place name
origperpcode string[8] N senders postal code
origpercontact string[30] N senders contact name
origperphone string[30] N senders phone 1
origperphone2 string[20] N senders phone 2
origpercell string[20] N senders mobile number
origperemail string[50] N senders email address
destpers string[35] Y receiver name or consignee
destperadd1 string[30] Y receiver address line 1
destperadd2 string[30] N receiver address line 2
destperadd3 string[30] N receiver address line 3
destperadd4 string[30] N receiver address line 4
desttown string{50] N receivers town / place name
destperpcode string[8] N receiver postal code
destpercontact string[30] N receiver contact name
destperphone string[20] N receiver phone 1
destperphone2 string[20] N receiver phone 2
destpercell string[20] N receivers mobile number
destperemail string[50] N receivers email address
duedate string[10] N waybill due date
duetime string[8] N waybill due time
bookdate string[10] N booking date
bookstarttime string[8] N booking start time
bookendtime string[8] N booking end time
specinstruction string[60] N special instruction
reference string[15] N waybill reference number
insuranceflag integer N insurance flag
instype integer N insurance type
declaredvalue float N value of the freight for insurance

Page | 3
 nondoxflag integer N not documents flag
currency float N transport cost currency
customsvalue float N value of freight for customs
surchargeflag1 integer N surcharge flag 1
surchargeflag2 integer N surcharge flag 2
surchargeflag3 integer N surcharge flag 3
surchargeflag4 integer N surcharge flag 4
surchargeflag5 integer N surcharge flag 5
surchargeflag6 integer N surcharge flag 6
surchargeflag7 integer N surcharge flag 7
surchargeflag8 integer N surcharge flag 8
surchargeflag9 integer N surcharge flag 9
actkg integer N shipment mass
volcm integer N shipment volumetric cm
pieces integer N total pieces

submitWaybill[contents] pieces integer Y number of pieces

description string[30] Y freight description
dim1 integer N dimension 1 in centimetres
dim2 integer N dimension 2 in centimetres
dim3 integer N dimension 3 in centimetres
actmass float Y mass in kilograms
customsvalue float N value of contents
country string[3] N IATA destination country code
item integer Y start from 1, per array entry
subcontents array[..] N details of freight inside physical
cartons
submitWaybill.contents quantity integer Y number of same product
[subcontents] description string[30] Y description of product
partno string[20] N partno/SKU of product
serialno string[20] N serial number of product
customsvalue float N value of product
currency string[4] N currency of customs value

submitWaybill[wayrefs] reference string[15] Y reference number

pageno integer Y set to 1. Increment for multiple
instances of a reference number
submitWaybill[tracks] trackno string[28] Y unique tracking number
parcelno integer Y increment, start from 1
item integer N Required if linking tracking numbers
to specific pieces in contents array
submitPOD waybill string[24] Y waybill number
poddate string[10] Y pod date
podtime string[8] Y pod time
recipient string[30] N recipient
details string[120] N free text details
discrep string[50] N discrepancy noted
idnumber string[13] N id number
cellnumber string[20] N cell number

Page | 4
 submitEvent trackno string[28] Y tracking number of parcel / freight
manifest integer N manifest or delivery sheet number
hub string[3] N hub where event takes place**
eventtype string[3] Y internal event code***
eventdate string[10] Y tracking event date
eventtime string[8] Y tracking event time
submitWaybillEvent waybill string[24] Y waybill number
eventdate string[10] Y tracking event date
eventtime string[8] Y tracking event time
hub string[3] N hub where event takes place
manifest integer N manifest or delivery sheet number
eventtext string[200] Y tracking event description
getSingleWaybill waybillno string[24] Y waybill number
submitPodImage waybill string Y waybill number
reference string Y reference (#1 for POD image)
pageno integer Y Page number (1 for first page)
image string Y Base64 encoded image string

** Date format dd.mm.yyyy , Time format hh:mm:ss

Class – Waybill – Output parameters

Method Parameter Type Description

submitWaybill errorcode integer 0 = no error
errormessage string null if no error
results array[..] returned details if success
submitWabill[results] success string
waybillno string waybill number
actkg string total actual kg of contents
chargemass string calculated charge mass
getSingleWaybill details array[] waybill details
contents array[] contents array of waybill
tracks array[] tracking numbers for waybill
wayref array[] references for waybill

getSingleWaybill[details] waybill string[24] waybill number

collect integer collection number
pieces integer total number of pieces
service string[3] transport service
waydate string[10] waybill date
quotedate string[10] date waybill was quoted
accnum string[6] customer account number
custname string[35] customer name
origpers string[35] sender name or consignor
origplace integer internal number for town
origtown string[50] originating town / place name
origpercontact string[30] senders contact name
origperadd1 string[30] senders address line 1

Page | 5
origperadd2 string[30] senders address line 2
origperadd3 string[30] senders address line 3
origperadd4 string[30] senders address line 4
origperphone string[30] senders phone 1
origperphone2 string[20] senders phone 2
origpercell string[20] senders mobile number
origperpcode string[8] senders postal code
destpers string[35] receiver name or consignee
destplace integer internal number for town
desttown string[50] destination town / place name
destpercontact string[30] destination contact name
destperadd1 string[30] receiver address line 1
destperadd2 string[30] receiver address line 2
destperadd3 string[30] receiver address line 3
destperadd4 string[30] receiver address line 4
destperphone string[20] receiver phone 1
destperphone2 string[20] receiver phone 2
destpercell string[20] receivers mobile number
destperpcode string[8] destination postal code
duedate string[10] waybill due date
destlatitude float latitude co-ordinates
destlongitude float longitude co-ordinates
duedate string[10] waybill due date
reference string[15] waybill reference number
specinstruction string[60] special instruction
surchargeflag1 integer surcharge flag 1
surchargeflag2 integer surcharge flag 2
surchargeflag3 integer surcharge flag 3
surchargeflag4 integer surcharge flag 4
surchargeflag5 integer surcharge flag 5
surchargeflag6 integer surcharge flag 6
surchargeflag7 integer surcharge flag 7
surchargeflag8 integer surcharge flag 8
surchargeflag9 integer surcharge flag 9
invoice integer invoice number
quote string quote number
insuranceflag integer insurance flag
declaredvalue float value of the freight for insurance
nondoxflag integer not documents flag
customsvalue float value of freight for customs
currency float transport cost currency
destperemail string[50] receiver email address
eventdestemail string flag to determine if emails are sent
origperemail string[50] sender email address
eventorigemail string flag to determine if emails are sent
actkg float total mass of contents in kg
volcm integer total volumetric cm
volrate integer volumetric divider
chargemass float mass greater of vol mass and act kg

Page | 6
 mawbno string[16] master air waybill
flight string[16] flight number
costcntr integer branch to which the shipment is allocated
costname string[25] branch to which this shipment is allocated
duetime string[8] waybill due time
manifest integer manifest number
agent integer agent carrying shipment
agentname string[30] name of agent carrying shipment
desthub string[3] destination hub
charge float shipment charge
insurance float insurance charge
cartage float base transport charge
outly float outlying charge
docs float document charge
handling float handling charge
cursurcharge float currency surcharge
totsurcharge float sum of all surcharges
subtotal float subtotal charge
vat float vat charge
total float total charge
customsduties float customs duties charge
customsvat float customs vat charge

getSingleWaybill[contents] defitem integer >0 default contents item used

item integer numeric increment for number of
contents lines
pieces integer total pieces on contents line
description string[30] description of contents line
dim1 float dimension 1 in cm
dim2 float dimension 2 in cm
dim3 float dimension 3 in cm
actmass float mass of contents line

getSingleWaybill[tracks] trackno string[28] tracking number of parcel

parcelno integer incremental count
item integer >0 links to item on contents

getSingleWaybill[wayref] reference string[15] reference number

pageno integer page number for multiple pages of same
reference number

Page | 7
For submitEvent please note:
** A hub table will need to be provided to map to the specific couriers hub listing
The hub string is a 3 character abbreviation for example ‘CPT’ for Cape Town.
*** Event types will need to be provided based on the specific courier. As the description is configurable by
each courier, we use the eventtype field. A table of standard eventtype codes are listed below:
EventType Description

1 Out for Delivery

2 Inbound Manifest to *hub*
3 Outbound Manifest to *hub*
4 Return to Depot
5 Return to Client
7 Outbound Cage
R Ready for Collection
O Collected from Origin Address
D Checked in at Origin Depot
X Manifest Transferred
P POD Details Captured
I POD Image Scanned
Z Transfer to manifest/tripsheet
Y Remove from manifest/tripsheet
a Held at customs
b Delivery attempt failed
c Incomplete delivery address
d Requiring further information
e Damaged in transit
f Flight delayed
C Closed and Dispatched
W Trans-shipped
B Consignment details captured
U Unload manifest/tripsheet
M Mis-routed

Page | 8