Shipments via API

Test file with example requests can be found here.

A shipment record need to be created to link all the parcels together that will be shipped out at the same time. To create the shipment, we use endpoint POST /api/v1/shipments

Let’s first take a closer look at the fields that apply to the shipment.

First value in shipment creation is type. This indicates the shipment type (not to be confused with mail type on parcel level). Possible values include:

1. AWB (Airway bill)

2. CMR

3. Courier

4. Labels

5. MailTransit

6. PostalLastMile

7. Transport

8. VirtualDespatch

The shipment number needs to be a fixed format only in case of AWB (format like 123-12345678 - read more about the format in Wikipedia). The other types do not check shipment number format. If this field is left empty, a shipment number will be generated by the system.

The terminal code is usually “AMS”. In case you need to use a different one, the instructions will be provided by the account manager or by IT when the time arrives.

All possible values include:

• AMS
• NDL
• PDL
• HKT
• MNL
• BKK
• TLL

Next up we have the arrival info section. This contains information that can be used for planning.

Transport number should show the transport used by the client to ship to us. In case the goods will be arriving by plane, the shipment type is AWB, mawb number is the shipment number and the transport number should indicate the flight number. In case a truck will be used, this field should contain the transport number.

Origin Country code shows which country the goods will be shipped out from by the client. If the client is located and ships out from China, this field should contain “CN”. If it's left empty, info is taken from the client contact address, thus it's important to fill this in case the goods are shipped out from a different country,

Total weight can (and usually does) differ from the parcel weights added up that are linked to one shipment. The reason is that the Total weight under the arrival info section, contains also tare (like a pallet etc). Unit: KG

Total bags – this field shows the distinct count of bag numbers.

Arrival on – the estimated date of the shipment arrival to PostPlus.

Notes can contain any info that the client might want to have under the shipment record. Can be left empty.

Since the arrival info may not be known while creating the shipment, it can be updated later. It's sufficient to just use type, shipment number and terminal code in the initial shipment creation.

If the shipment creation was successful, a shipment ID will be provided. This ID will be used to update and link parcels to this shipment record.

The shipment ID can then be used to update via endpoint PUT /api/v1/shipments/{shipmentId}

Once the parcels are created, these could be linked with the shipment. More about how to create parcels in this article.

To update the bag reference, we need to call /api/v1/parcels/update-references-many

It could be done by using create-or-update-many endpoint, as used when creating&updating parcels, since the bag field is in that request and it updates the data on the parcel record, but it would also be more complicated. In update-references-many, it’s enough to just add all parcels that were put into one bag in one request line like this:

In this case both parcels were inserted into one bag.

Since at this point the shipment has been created, we could link the parcels to the shipment as well with the same request by just adding the shipment ID:

It is important to keep in mind to not create mixed bags. All parcels added into one bag, should have the same destination and either be postal or non-postal. This ensures the fastest handling in our AMS terminal.

Once the parcels are linked to the shipment by updating parcel references, the shipment can be validated. For this we use ​/api​/v1​/shipments​/{shipmentId}​/prepare which checks if everything is okay with the shipment. In this stage, client will be reminded in case an erroneous parcel has been linked to this shipment record or if the total bags under arrival info does not match the distinct bag count linked to the shipment.

The errors could state:

"ShipmentNr not valid. AWB check digit validation failed" - Check and update the shipment number or the shipment type (shipment type AWB needs a valid air waybill number)

"ArrivalTransportNr: cannot be empty" - update the shipment arrival information

"ArrivalOn: must be specified" - update the shipment arrival information

"ArrivalWeight: must be specified" - update the shipment arrival information

"ArrivalBags: must be specified" - update the shipment arrival information

"One or more bags has errors." - if the parcel errors are also mentioned, it's highly likely that the error is only there (parcel is inside the bag so the bag gets an automatic error in case a parcel in it has an error)

"One or more parcels has errors." - check the parcels in this shipment, one wasn't successfully created. A more descriptive error message should be seen under the parcel record.

If any errors should appear, the client can just go back and update the data where necessary. 

After solving the errors, the shipment should be validated again. In case there are no errors and everything has gone well up to this point, the response will contain a shipment submit token. This can be used to submit the shipment, using endpoint /api/v1/shipments/{shipmentId}/submit. Submitting the shipment will mean that no changes can be made to this shipment record anymore.