This guide will show how to implement and use the ShipAdvisor web service.
I will explain the common method that is used to integrate with ShipAdvisor. I will use C# and PHP to show code examples with hard coded values. It should be easy to translate into any code language from the examples. See the sample code section for complete PHP Script and .NET project.

As mention in the flow overview document this is the order of calling ShipAdvisor:

1. GetFreightProductsForShipment
2. (optional) DropPoint Methods
3. CreateConfirmedOrder

 
GetFreightProductsForShipment
Input parameters: WebShopshipment and deliveryTypeOrder.

This method get the suited products from ShipAdvisor based on the input from the webshop.
The method use the following classes to build up the webshop shipment that is sent to ShipAdvisor for product validation.
First we have to create an instance of the web service class FreightShopWS and use SOAP header authentication.

.NET
//SOAP header authentication
ShipAdvisorWS ws = new ShipAdvisorWS();
ws.ServiceAuthenticationHeaderValue = new ServiceAuthenticationHeader();
ws.ServiceAuthenticationHeaderValue.Username = "Username";
ws.ServiceAuthenticationHeaderValue.Password = "Password";

PHP
//Create Soap Client.
$Soap_client = new SoapClient('http://consignorsupport.no/ShipAdvisor/main.asmx?WSDL');

//Create Soap Header.
$Soap_header = new SoapHeader('SoapAuthenticator', 'ServiceAuthenticationHeader',
                                      array('Username'=>'Username', 'Password'=>'Password'));

//Set the Headers of Soap Client.
$Soap_client->__setSoapHeaders($Soap_header);

The username and password is provided by nShift.

Receiver:
This is the data on the receiver of the goods / order, and we start out with making an instance of the class Receiver. In this method you only need to use the fields Receiver.PostCode and Receiver.Country and assign postcode and country code to them.

.NET
// Create the receiver
Receiver Receiver = new Receiver();
Receiver.PostCode = "0580";
Receiver.CountryCode = "NO";

PHP
//Create the receiver
$Receiver = array(
       'ReceiverId'=> 0,
       'CountryCode'=> 'NO',
       'PostCode'=> '0580'
        );

WebShopLine:
In this class the shipment goods line is created and the data like number of packages and weight on the Shipment is assigned so the ShipAdvisor can validate products and calculate price on the shipment. WebShopLine is a type of array so it is possible to use more lines here if you could provide shipment data on line level.

.NET
//Create WebshopLine( goods line)
List<WebShopLine> lines = new List<WebShopLine>();
WebShopLine ln = new WebShopLine();
ln.NumberOfPackages = 2;
ln.PackageWeight = 5000;
lines.Add(ln);

PHP
See next section where this is combined with WebShopShipment and WebShopLine.

In this example the shipment has 2 packages and weight of 5000 grams(5 kg) per. package.
If you provide total weigh on the shipment from the webshop and don`t use multiply
WebShopLines , then divide the PackageWeight with NumberOfPackages.
One WebShopLine also contains fields for measurements and volume. If you can provide that data, then use those to get a more accurate shipment price in that case that the volume will kick in on the price rather than weight.

PackageHeight

PackageLength

PackageWidth

PackageVolume

Remember that weight is provides in grams, Height, Length, Width in mm(millimeter) and Volume in mm3(cubic millimeter).

WebShopshipment:
This class contains all the data on the shipment that is sent to ShipAdvisor.
WebshopId – the unique id for your webshop configured in ShipAdvisor
Shopper – the receiver
CODAmount - if the order is a shipment with COD. In this method you can assign 0 if it`s not COD, 1 if it is COD or just pass in the amount the customer has to pay if it is COD. This is used in the filtering in ShipAdvisor to only return products that supports COD if any value is provided.

.NET
//Create shipment
WebShopShipment shipment = new WebShopShipment();
shipment.WebShopId = 104;
shipment.Shopper = Receiver;
shipment.CODAmount = 0
shipment.Lines = lines.ToArray();

PHP

//Create shipment and goods line
$Shipment = array(
          'Shipment' =>array(
          'WebShopId' => 104,
          'CODAmount' => 0,
           'Lines' => array(
               'WebShopLine' => array(
                'NumberOfPackages' => 1,
                'PackageWeight' => 5000
        )
      ),
        'Shopper' => $Receiver
   ),
    'deliveryTypeOrder' => 10
);

ProductsWrapper:
This class is used as an container for products returned by ShipAdvisor and with the GetFreightProductsForShipment method. It returns a ProductInfoList that is an array of SuitedProductInfo.

.NET
// Create an instance of ProductsWrapper class to hold the available products that is returned from ShipAdvisor//
ProductsWrapper FreightProducts = new ProductsWrapper();
FreightProducts = ws.GetFreightProductsForShipment(shipment, 10);

PHP
//Call ShipAdvisor
$FreightProducts = $Soap_client->GetFreightProductsForShipment($Shipment);

The input for delivertTypeOrder is in this example is 10. That means I get products that is configured on the webshop in group 10. As mention in the flow overview document this depends on if the webshop want to use grouping of products or just use one.
deliveryTypeOrder:
10 = Home delivery
20 = At Work
30 = Pick Up (at chosen drop point)
In this example code I finally bind the data that is returned from the ShipAdvisor to a datagrid.

.NET
// Display the result in the grid view
grdFreight.DataSource = FreightProducts.ProductInfoList;
grdFreight.DataBind();

PHP
//Show result in data dump
echo
"<pre>";
var_dump($FreightProducts);
echo
"</pre>";

In the grid you can see the result from ShipAdvisor returned as SuitedProductInfo.
Note that the field Supports DropPoint tells you if the product supports drop points or not, and that brings us to the next method we are going to use.

SearchForDropPoints:
Input parameters:
ProductConceptID - this is the productid you can see in the previous screenshot in the field ConceptID. This is used to get the drop point on the product with this productid. So when a user selects a product then you pass in the ProductConceptID if the product support drop point is true.
installationID – identifier for the customer installation, provided by nShift.
country
address
postcode
city
limit – number of drop points to present to the customer

As you can see we have several methods to handle drop points, but I will not get into those since it is the similar use as this one.
As mention above you can call SearchForDropPoints method if the customer chose a product that supports drop points. This could be presented to the customer as a list to choose drop points from and / or show the drop points on a Google map. This methods returns all the coordinates on the drop points to use in Google map. I`m only going to show in code how you get this into a list(array).

.NET
//Create an array of the DropPointData class
DropPointData[] AllDP;

//Get all droppoint and display them in a datalist
AllDP = ws.SearchForDropPoints(60, 10916000028, NO, "", "0580", "", 15)

//Bind all dropoints to DPlist
DPlist.DataSource = AllDP;
DPlist.DataBind();

PHP
//Input parameters, set limit on the search
$Params = array(
            'productConceptID'=> 60,
            'installationID'=> '10916000028',
            'country'=> 'NO',
            'postCode'=> '0580',
            'limit' => 15
            );

//Get all drop points
$DropPoints = $Soap_client->SearchForDropPoints($Params);

//Show result in data dump
echo "<pre>";
var_dump($DropPoints);
echo
"</pre>";

CreateConfirmedOrder:
Input parameters:
WebShopShipment - all the data on the shipment that is sent to ShipAdvisor.
SelectedProductInfo – data on the selected product that the customer chose.

This method is very similar to GetFreightProductsForShipment and uses the same logic.
The difference is that CreateConfirmedOrder uploads the shipment and selected data to ShipAdvisor so it is possible to get the shipment back to DeliveryHub later and then have integration with the software. Since this uploads to ShipAdvisor we need to provide more data than we did in GetFreightProductsForShipment. The use of this method is optional.

First, we get the data that the user selected from GetFreightProductsForShipment.

.NET
//Assign values to selectedProduct
SelectedProduct Product = new SelectedProduct();
Product.WebShopProductId = 1040009;
Product.Price = 75;
Product.CurrencyCode = NOK;

PHP
//Assign values to selectedProduct
$SelectedProduct = array(
        'WebShopProductId' => 1040009,
        'Price' => 75,
        'CurrencyCode' => 'NOK',
        'DropPoint' => $DropPointData
        );

Then we check if the product supports drop point and use the class DropPointData to assign the
needed drop point data. This example show if the customer chose Mypack.

.NET
//If selected product supports droppoint then assign values to DropPointData

if ((Boolean)Session["SupportDropPoint"] == true)
{
DropPointData DP = new DropPointData();
OriginalId = "3425964";
DP.Name1 = "KIWI 380 ØKERN"
DP.Address1 = "ØKERNV 145"
DP.PostalCode = "0580"
DP.City = "OSLO"
DP.CountryCode = "NO"
Product.DropPoint = DP;
}

PHP
//Selected Drop point Data
$DropPointData = array(
         'OriginalId' => '3425964',
         'Name1' => 'KIWI 380 ØKERN',
         'Address1' => 'ØKERNV 145',
         'PostalCode' => '0580',
         'City' => 'OSLO',
         'CountryCode' => 'NO',
         'MapRefX' => 0,
         'MapRefY' => 0,
         'Distance' => 0
         );

.NET
//Create the receiver
Receiver Receiver = new Receiver();
Receiver.Name = "nShift AS"
Receiver.Address = "Lørenvangen 22";
Address2 =""; (optional)
Receiver.PostCode = "0580";
Receiver.City = "OSLO";
Receiver.CountryCode = "NO";
Receiver.Phone = "";(optional)
Receiver.Email = "";(optional)
Receiver.Attention = ""(optional)
Receiver.ReceiverRef = "";(optional)
Receiver.MessageToCarrier = ""; (optional)
Receiver.MessageToDriver = ""; (optional)
Receiver.MessageToReceiver = ""; (optional)
Receiver.CODKID = "";(optional)
Receiver.CODReference = "";(optional)

PHP
//Create the receiver
$Receiver = array(
        'ReceiverId' => 0,
        'Name'=> 'nShift AS',
        'Address' => 'Lørenvangen 22',
        'PostCode'=> '0580',
        'City'=> 'OSLO',
        'CountryCode'=> 'NO'
        );

.NET
//Create WebshopLine( goodsline)
List<WebShopLine> lines = new List<WebShopLine>();
WebShopLine ln = new WebShopLine();
ln.NumberOfPackages = 2;
ln.PackageWeight = 5000;
ln.PackagesContents = ""; (optional)
lines.Add(ln);

//Create shipment
WebShopShipment shipment = new WebShopShipment();
shipment.WebShopId = 104;
shipment.OrderNumber = "12"; (order number for the webshop order)
shipment.Shopper = Receiver;
shipment.CODAmount = 0 (Pass in the amount the customer should pay if it is COD)
shipment.CurrencyCode = "NOK";
shipment.Lines = lines.ToArray();

PHP
//Create shipment and goods line
$Shipment = array(
             'Shipment' => array(
              'WebShopId'=> 104,
              'OrderNumber'=> '344',
              'CODAmount'=> '0',
              'CurrencyCode'=> 'NOK',
               'Lines' => array(
                'WebShopLine' => array(
                'NumberOfPackages' => 1,
                'PackageWeight' => 5000
             )
          ),
              'Shopper' => $Receiver
       ),
             'Product' => $SelectedProduct
   );

You can use the class OrderOutput to get message from ShipAdvisor if the upload is successful and catch the error message if anything goes wrong.

.NET
// Call ShipAdvisor, fetch data and catch the error message if any. Display ChodId and write success message if all is ok
OrderOutput Output = ws.CreateConfirmedOrder(shipment, Product);

if (String.IsNullOrEmpty(Output.ErrorMessage))
{
lblMessage.Text = "Successfully uploaded to ShipAdvisor with ShipAdvisorID: " + Output.ChODId.ToString() + " and order number: " + "12";

}

else
{

lblMessage.Text = Output.ErrorMessage;
}

PHP
//Call ShipAdvisor
$Result = $Soap_client->CreateConfirmedOrder($Shipment);

//Show result in data dump
echo
"<pre>";
var_dump($Result);
echo
"</pre>";