Documentation for customer Portal API V7.2 (1) (PDF)

PROGRAMME & DEVELOPMENT SERVICES

Portal Web Services
Version 7.2
Service
Submitted By: POSTAPLUS – IT
Created By: POSTAPLUS - IT

XML Services: Posta Tool Kit

1|Page

This document is published by, and remains the property of, POSTAPLUS. It contains confidential and proprietary
information. The customer shall hold this information in confidence and may not make any copies or disseminate
this document to any third party. The customer may not disclose this information internally to its employees or
agents except on a need-to-know basis and shall instruct all such employees or agents to comply with the
POSTAPLUS confidentiality requirement implied by this statement.
POSTAPLUS
All Rights Reserved
Published: May 2016

Document Identification Information

Document Name
Description
Author
Issue Date
Status
Current Version
Reviewer(s)
Approver(s)
Confidentiality Classification

Revision
Number

Portal Web Service
This document guides Postaplus customer team on working flow of web
service related to pragramme and development
GSO DEPARTMENT
05/2016
Updated
7.2
GSO Project Manager
Director, Postaplus
Confidential

Revision Date

Author

1

04/2015

GSO Department

2

04/2016

GSO Department

Updated
Version
Number

Revised/Reviewed
By

6.0

Project Manager

Revision Description

Release 6

GSO
7.1

Project Manager

Release 7.1

GSO
3

05/2016

GSO Department

7.2

Project Manager

Release 7.2

GSO

XML Services: Posta Tool Kit

2|Page

Table of Contents
1. Introduction ……………………………………………………………………………….. 4
1.1. Web Services ………………………………………………………………………………..…….. 4
1.2. Web Services Contents …………………………………………………………………...……..... 4

2. Web Service Integration Steps ……………………………………………………………...5
2.1. Add Service to Client Application ………………………………………………………………....5
2.2. Generate the Airway Bill ..……………………………………………………………….………....6
2.3. Shipment Tracking ………………………………………………………………………………... 7

3. Data Element Definition …………………………………………………………………… 7
3.1. About the Data Element Definition Table ……………………………………………………….. 7
3.2. Shipment Preparation request Data Parameters Definitions ……………………………………………………. 7

4. Reference Data ………….……………………………………………………………….... 11
4.1. Currency Codes …………………………………………………………………………………... 11
4.2. Entity Codes …………………………………………………..…………………………………. 11
4.3. Carrier Codes ...…………………………………………………………………………………... 11
4.4. Service Codes …………………………………………………………………………………….. 12
4.5. Shipment Type Code …………………………………………………………………………….. 12
4.6. HS Codes …………………………………………………………………………………………. 12
4.7. Package Type Code ……………………………………………………………………………… 14
4.8. Station Codes …………………………………………………………………………………….. 14
4.9. Cities Codes ……………………………………………………………………………………… 14
5. Country Codes …………………………………………………………………………………….. 18
5.1. Sector Codes ……………………………………………………………………………………... 23
5.2 Areas Codes ………………………………………………………………………………………. 24
5.3 Payment Type Code ……………………………………………………………………………… 27

XML Services: Posta Tool Kit

3|Page

1. Introduction
1.1. Web Services
POSTAPLUS offers Web based online integration platform that provides Shipment Creating, tracking
services for POSTAPLUS customers.
Here is how Web services can help POSTAPLUS customers:
• By implementing this service they can easily prepare the shipments.
• By implementing this service they can easily track their shipments.

Below are list of available services or operations:
• Shipment Preparation - Validates shipment data and return Waybill and data.
• Shipment Tracking - Obtain shipment details and event visibility filtered by Waybill.
Here is the process of implementing Web integration with POSTAPLUS
1. POSTAPLUS Team will provide you the Service URL . Make sure that you have the
programming resources experienced with Web Service integration to work with this web service.
2. Development: Complete development and Integration work.
3. Production Support: Contact POSTAPLUS Technical Support team for production support.

1.2. Web Services Contents:
This service is provided to POSTAPLUS clients to help them understand and implement integration
with Web Services application.
These messages also help to understand the conditions/data values that might result in an error response
from Web API server.

XML Services: Posta Tool Kit

4|Page

2. Web Services Integration Steps:
2.1. Add the Service to Client Application:
The Service is developed and tested in Visual Studio 2010 environment using C#. Also included Classes
and functions. Kindly follow the below steps:
Step 1: Add a web reference to your project with http://etrack.postaplus.net/APIService/PostaWebClient.svc
Step 2: Call the service to client application by clicking the button next to the URL box. After connect to the
service you can find the service to the right side of the window along with the functions which works under this
service at the left to it.
Step 3: Provide a web reference name to the service.
Step 4: Create a reference by click on Add Reference.
Note : Check the below image for the further reference.

XML Services: Posta Tool Kit

5|Page

2.2. Generate the Airway Bill:
Step 1: After including web reference, client should define seven objects by calling below classes with the web
reference name which are as follows:

Step 2: After defined an objects, call the parameters in APIParameters class object with valid values and those
values should be in corresponding datatypes.
For Example,

XML Services: Posta Tool Kit

6|Page

Step 3: Create a string variable to get the returned airway bill from the method.
For example,

2.3. Shipment Tracking:
Step 1: Client should define one object by calling below class with the web reference name and create one
string and pass parameters which are as follows:

3. Data Element Definition:
3.1. About the Data Element Definition Tables:
•
•
•
•
•
•
•
•
•

The following tables describe the elements found in the Shipment Preparation. In the tables:
Parameter Name is the data element’s name those client will send to get the Airway Bill No.
Datatype/Format indicates the data element’s type or format if no specific datatype is listed (for
example, text strings).
Definition is a short description of the data element.
Required indicates whether an element is required or not.
M indicates that the segment is mandatory.
O indicates that the segment is optional.
Length indicates length of the value. Any special format of the field value is indicated in parentheses.
Valid Values indicates required values, if any. Where specific values are expected, the value passed in
the message is indicated in bold text, followed by the literal meaning in parentheses.
“ | “ is the separator for the characters in Valid Values

3.2. Shipment Preparation request Data Parameters Definitions:
Parameter Name

Datatype/Format Req Definition

Valid Values

CodeStation
ShipperAccount

String
String

M
M

POSTA Station Code
Shipper Account Number

=KWI,DXB,BHR

Username
Password
ConnoteWeight

String
String
Double

M
M
M

Shipper Account Username
Shipper Account Password
Shipment Weight

ConnotePieces

Integer

M

Atleast 1 Piece

ConnoteLength

Double

M

Shipment Length

ConnoteHeight

Double

M

Shipment Height

Less than 15 Characters
Could Contain 0-9|AZ|a-z|-

XML Services: Posta Tool Kit

Less than 50 Characters
Less than 15 Characters
Should be >= 0.500.
Could Contains- 0-9|.
Between 1 – 4.
Could Contains- 0-4
Should be > =0.
Could Contains- 0-9|.
Should be >=0.
Should Contains- 0-9|.
7|Page

ConnoteWidth

Double

M

Shipment Width

CodeShipmentType

String

M

POSTA ShipmentType Code

ConnoteDescription

String

M

Shipment Description

Should be >= 0.
Could Contains- 0-9|.
Refer to Reference 4.3
Less than 50 Characters.
Could Contains-0-9|A-

Z|a-z|.||_|(|)|,|space|@|#|$|/|
\|;

ConnoteInsured
ConnoteProhibited
NeedRoundTrip
CodeService
TelMobile

String
String
String
String
String

O
O
O
M
M

Boolean Flag
Boolean Flag
Round trip status
POSTA Service Code
Tel/Mobile No.
(including 965)

TelHome

String

O

Tel/Mobile No.
(including 965)

WhatsApp Number

String

O

Tel/Mobile No.
(including 965)

Note1

String

O

Note1

= Y or N
= Y or N
= Y or N
Refer to Reference 4.2
Equal to 15 digits, for eg
965**********
Could Contains- 0-9|Equal to 15 digits, for eg
965**********
Could Contains- 0-9|Equal to 15 digits, for eg
965**********
Could Contains- 0-9|Less than 200 characters
Could Contains-0-9|A-

Z|a-z|.||_|(|)|,|space|@|#|$|/|
\|;

Note2

String

O

Note2

Less than 200 characters
Could Contains-0-9|A-

Z|a-z|.||_|(|)|,|space|@|#|$|/|
\|;

Note3

String

O

Note3

Less than 200 characters
Could Contains-0-9|A-

Z|a-z|.||_|(|)|,|space|@|#|$|/|
\|;

Note4

String

O

Note4

Less than 200 characters
Could Contains-0-9|A-

Z|a-z|.||_|(|)|,|space|@|#|$|/|
\|;

Note5

String

O

Note5

Less than 200 characters
Could Contains-0-9|A-

Z|a-z|.||_|(|)|,|space|@|#|$|/|
\|;

Note6

String

O

Note6

Less than 200 characters
Could Contains-0-9|A-

Z|a-z|.||_|(|)|,|space|@|#|$|/|
\|;
XML Services: Posta Tool Kit

8|Page

CodeHS

String

O/M

OriginCountry

String

O/M

CodePackageType
Description

String
String

O
O/M

It is M, if shipment type is
INTL NON DOC
It is M, if shipment type is
INTL NON DOC
Type of package
Item Description

Refer to Reference 4.4
Refer to Reference 4.6
Refer to Reference 4.5
Less than 50 Characters
Could Contains-0-9|A-

Z|a-z|.||_|(|)|,|space|@|#|$|/|
\|;

Quantity

String

O/M

RateUnit

String

O/M

Reference1

String

O

It is M, if shipment type is
INTL NON DOC
It is M, if shipment type is
INTL NON DOC
Shipper Reference

Reference2

String

O

Consignee Reference

FromName

String

M

Shipper Name

FromAddress

String

M

Shipper Address

Should be >0
Could Contain - 0-9
Should be >0
Could Contain - 0-9|.
Less than 50 Characters
Could Contain- 0-9|A-

Z|a-z|.|-|,|space

Less than 50 Characters
Could Contain- - 0-9|A-

Z|a-z|.|-|,|space

Less than 50 Characters
Could Contain- - 0-9|AZ|a-z|-

Less than 200 characters
Could Contains-0-9|A-

Z|a-z|.||_|(|)|,|space|#|/|\|;

FromArea

String

M

Shipper POSTA Country
Area Code
Shipper POSTA Country
City Code
Shipper POSTA Country
Code
Shipper Tel/Mobile No.
(including 965)

Refer to Reference 4.8

FromCity

String

M

FromCodeCountry

String

M

FromMobile

String

M

FromPinCode

String

O

Shipper Area Pincode

String

M

FromTelephone

String

M

Shipper POSTA Country
Province Code
Shipper Tel/Mobile No.
(including 965)

Less than 15 characters
Could Contain - 0-9
=KW, AE, BH

FromProvince

Email1

String

O

Sender Email ID

Remarks

String

O

Remarks

Refer to Reference 4.7
Refer to Reference 4.6
Equal to 15 digits, for eg
965**********
Could Contain - 0-9

Equal to 15 digits, for eg
965**********
Could Contain - 0-9
Less than 50 Characters
Could Contain - 0-9|A-

Z|a-z|@|.

Less than 100 characters
Could Contain- - 0-9|A-

Z|a-z
XML Services: Posta Tool Kit

9|Page