This article will explain how to build a basic request to the Shipment Server API. It will go through some examples and explain more about the most common fields.
Topics in this article:
- Creating a parcel shipment
- Creating a pallet shipment
- Handling drop points
- Finding information for mandatory fields
See these other articles for more help on implementation:
Creating a parcel shipment
To create a simple parcel shipment, your request must contain all the information necessary to create a shipment. This can vary from carrier to carrier but the example below contains the most basic information needed.
- Kind - Base class Shipment and Type of ShipmentKind that defines what kind of shipment it is. The value "1" means a normal shipment
- ActorCSID - The key for your installation
- ProdConceptID - The ID for the specific product you want to use, e.g. 1067 means "Bring Home Delivery".
- Services - The ID for the specific service you want to use at a certain carrier, e.g. "142059" means "Curbside". Som products have mandatory services.
- Addresses - Section where you define data for sender, receiver, drop point and so on.
- Kind - Base class Address and Type of AddressKind. The value "1" is receiver and "2" is sender.
- Lines - Section where you define the data for the packages at line level.
- PkgWeight - The weight in grams for each package on the line.
- Pkgs - Base class Package, the data for packages.
- ItemNo - "1" means that this is the first package in the shipment on this line and the next would have value 2 and so on.
Example request in json:
{
"Kind": 1,
"ActorCSID": 63,
"ProdConceptID": 1067,
"Services": [
142059
],
"Addresses": [
{
"Kind": 2,
"Name1": "Consignor Test sender",
"Street1": "Test road 1",
"PostCode": "0580",
"City": "OSLO",
"Phone": "10203040",
"Mobile": "04799999999",
"Attention": "test",
"CountryCode": "NO"
},
{
"Kind": 1,
"Name1": "John Doe",
"Street1": "Test street 10",
"Street2": "Test address",
"PostCode": "0580",
"City": "OSLO",
"CountryCode": "NO"
}
],
"Lines": [
{
"PkgWeight": 5000,
"Pkgs": [
{
"ItemNo": 1
}
]
}
]
}
The example above includes the Sender address. It is not necessary to include this in each request since Shipment Server will use the one that is configured on the server for your installation.
Creating a pallet shipment
Creating a pallet shipment is very much like creating a parcel shipment. Most of the basic information is the same, but pallets often require some additional information that are usually not needed on parcel shipments.
Examples of additional information needed on pallets and groupage shipments (not all information below is required by all pallet and groupage carriers):
- Height - Height of the goods in mm
- Length - Length of the goods in mm
- Width - Width of the goods in mm
- PkgVol - Volume of the goods in mm3
- Loadmeter - loadmeter in mm
- Reference - Contains more information about the goods. In this example, value "23" in kind refers to Contents of the goods (See Appendix for possible values)
Example request in json
{
"Kind": 1,
"ActorCSID": 63,
"ProdConceptID": 837,
"Addresses": [
{
"Kind": 2,
"Name1": "Test sender",
"Street1": "Test Address",
"PostCode": "0580",
"City": "OSLO",
"Phone": "23249480",
"Mobile": "04799999999",
"Attention": "test",
"CountryCode": "NO"
},
{
"Kind": 1,
"Name1": "John Doe",
"Street1": "Test road 1",
"PostCode": "7000",
"City": "Fredericia",
"Phone": "11223344",
"Attention": "Doe",
"CountryCode": "DK"
}
],
"Lines": [
{
"PkgWeight": 50000,
"Height": 1000,
"Length": 800,
"Width": 1200,
"PkgVol": 960000000,
"Loadmeter": 1200,
"GoodsTypeKey1": "PALLET",
"References": [
{
"Kind": 23,
"Value": "Test content"
}
],
"Pkgs": [
{
"ItemNo": 1
}
]
}
]
}
Handling drop points
Some products requires a drop point to be selected on the shipment. A drop point is the address of a service point 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".
If the drop point address is left out in the request for a product that require a drop point, then the shipment server may choose a drop point based on the receiver address. However, for some carriers, this requires a drop point service to be included.
Some carriers support lookup on droppoint ID. Use the variable "CustNo" and include the drop point ID and Shipment Server will then do a lookup on this ID and fill out the drop point address. You should offer drop point selection in your solution to include this in your request.
{
"Kind":10,
"CustNo": "3535747"
}
If the drop point ID does not match at our end, Shipment Server will respond with an error and it must be correct to submit the shipment.
If you provide drop point data in your request, Shipment Server will not do any lookup, but use the data provided - even if it's not valid at the carrier.
{
"Kind":10,
"CustNo": "3535747",
"Name1": "RIMI SINSEN AVD 3821"
"Street1": "SINSENV 55",
"Postcode": "0585",
"City": "OSLO",
"CountryCode": "NO"
}
Finding information for mandatory fields
It can be tricky to find all the mandatory information to include in your request. You will receive some of it from your Consignor consultant, but using the Shipment Server test bench can also be helpful. You can use several different commands to find data.
If you choose the command GetProducts you will get a response with a lot of details about the carriers activated on your actor.
In the response you will find information about product and service ID. In the request excerpt below, you can see the ProdConceptID which is needed in the request. You can also see the name of the product and what services are available on this product. It is the value from ServiceID you need to use to book a service.
"CarrierConceptID": 142,
"CarrierCSID": 116,
"CountryCode": "NO",
"CarrierFullName": "Bring",
"CarrierShortName": "Bring",
"Subcarriers": [
{
"SubcarrierConceptID": 211,
"SubcarrierCSID": 191,
"SubcarrierName": "Pakker",
"Products": [
{
"ProdConceptID": 1032,
"ProdCSID": 872,
"ProdName": "Bedriftspakke",
"AllowDG": 1,
"AllowInsurance": 1,
"AllowCOD": 1,
"Services": [
{
"ServiceID": 142008,
"ServiceName": "Varsle for utlevering",
"ServiceCode": "Z20",
"GroupID": 12
},