In this section I`m going to show some examples of how to build up your request to the Shipment Server. Since Shipment Server consist of many classes (objects) and fields, I have placed this information in the Appendix section. As you can see in the Appendix it is a lot fields that could be used when creating a shipment. Don`t be intimidated by it, since in the most cases only a small selection of fields will be used. Many of the fields is only used in the response from the server to present the data generated on the server and some of them are preconfigured on the server so you do not need to use them in your request.
Let us start out with a simple request. In the Appendix you can see the name of the enumerated fields and see other available fields to use.
Kind: Base class Shipment and Type of ShipmentKind that define what kind of shipment this is. The value 1 means that this is a "Normal" shipment.
ActorCSID: The key for your installation / Actor on the server.
ProdConceptID: The uniq id for the product you want to create the shipment on. In this example this is 1032 that means it is the product Bedriftspakke dør- dør and the carrier is Bring.
Section for Addresses where you define the data for sender, receiver, drop point and so on.
Kind: Base class Address and Type of AddressKind. The value 1 means that this is the receivers address.
The rest of the fields in Address should be self-explaining.
Section where you define the data for the packages at line level.
PkgWeight: The weight for each package on the line.
Pkgs: Base class Package, the data for packages.
ItemNo:1 means that this the first package in the shipment on this line and the next would have value 2 and so on.
There is an alternative way to define number of packages on a line. The property Number determines the number of packages. This will give the same output as the use of Pkgs shown in the previous example.
Either use Number or Pkgs but not both in a request. Pkgs has to be used if you e.g. want to import your own package numbers (e.g. EAN numbers) and references for the packages.
In other cases using just the Number property maybe easier.
Let's move on to another request.
As you can see here it is an additional entry for address that is for the sender. It is not necessary to send this for each request since Shipment Server will use the one that is configured on the server for your installation.
In the line section I demonstrate the build-up of a shipment with multiply lines and packages. In this example the shipment has two lines. The first line contains 1 package with weight 5 kg and the second line has two packages with 3 kg each. Use multiply lines if you need to define different measures for packages.
This section is used for different amount types on the shipment like COD (cash on delivery) and insurance. In this example I show COD.
Kind: Base class Amounts and Type of ShipmentAmountKind. The value 5 means that this is a shipment with COD.
CurrencyCode: In this example the value is 1 that means that the currency is in NOK. See the Appendix for the full list of values for currencies.
Value: The amount the receiver should pay when receiving the shipment.
The next two sections are References and Messages that is used on the shipment for additional info to the receiver, carrier and driver.
Drop Point (Service Point) handling
Some products requires a drop point to be selected on the shipment. A drop point is the address to where the customers can pickup the delivery.
In the shipment object this is defined in the section for Addresses with the Kind set to 10.
NOTE: If this section is left out in the request, but the product require a drop point, then shipment server will choose the one marked as the closest one from the carrier based on the receiver.
We only need to use the variable CustNo containing the value for the drop point`s unique id. Shipment Server will then do a lookup on this id and fill out the rest of the address data that belongs to the drop point. This ensures that the shipment is created with correct data for the drop point. If the client do not offer any drop point selection, then this section should be left out in the request and Shipment Server will choose the default drop point defined by the carrier based on the receivers post number.
NOTE: There are some carriers e.g. Itella and DHL, that does not provide lookup from drop point Id (CustNo).
In that case the appropriate data on the drop point has to be in the request.
If needed Consignor can provide drop point service to be used at the client side to present drop point to the end user to choose from, through the ShipAdvisor API.
Define drop point by drop point id:
As mention, if only the drop point id is provided in the request, the Shipment Server does a lookup on the drop point by this id. The drop point will be chosen for the shipment with the proper data for the drop point.
In cases where the drop point id do not exist or do not match at our end, the Shipment Server will throw an error.
This needs to be corrected before the shipment could be successfully committed.
Define drop point by providing data for the drop point:
In this case the Shipment Server will not do any lookup of the drop point data. The data provided for the drop point will be used for the shipment, even if it`s not valid for the drop point.
Both requests will produce a shipment with the drop point data shown in the latter example.
The shipment could be insured by using If insurance.
In the shipment object use Amount class to define the amount that the shipment should be insured for.
Kind: Type of ShipmentAmountKind set to the value 12 that is the enum eSamkThirdPartyInsurance.
CurrencyCode: The currency for the amount. Supported currencies are: NOK (1), DKK (2), SEK (3) and EUR (5).
Use the value for the currency from the Currency Code table that could be found in Appendix.
Value: The amount the shipment should be insured for.
It is required to define a content for the shipment and an email address where the insurance certificate should be sent to. This is done by using the Reference class.
Kind: Type of ReferenceKind set to 139 that is the enum eSrkThirdPartyInsuranceContents.
Value: A description of the content of the shipments.
Define an email address:
Kind: Type of ReferenceKind set to 140 that is the enum eSrkThirdPartyInsuranceEmail.
Value: The email address to whom the insurance certificate should be sent to.
Note: See the methods GetIsnurancePrice if you want to get the insurance premium before submitting the shipment and the method GetInsuranceClaimURL that would return the claim URL.