Postman is a free cross-platform API client app that allows you to experiment easily with API requests using a friendly interface.
The Metapack Shipping API (SOAP) Quick Start Collection is a packaged and downloadable bundle of SOAP requests that have been adapted to use the POST method in Postman.
The collection allows you to you quickly access a logical sequence of pre-written calls that take you from pre-ship carrier service selection through to manifesting.
You can download Postman here for Mac, Windows or Linux. It is also recommended that you set up a free Postman account to enable easy sharing.
Note
You can still use the Postman for Chrome extension, but this is deprecated and it is therefore recommended that you download your preferred native O/S version.
Downloading the Collection
You can download the collection by clicking the Run in Postman button below.
Note
Click here to familiarise yourself with the basics of making SOAP requests in Postman. There are also many useful YouTube tutorials.
Set up Delivery Manager before using the Collection
-
If you are new to the Shipping API, you will need a Delivery Manager account with your own
Username
andPassword
with which you can create and allocate consignments.Note
Your
Username
andPassword
are entered against theBasic Auth
type under the Authorization tab in Postman. These have already been parameterised for you.There is no need for an API key.
-
You will need to have logged onto your Delivery Manager account and gone through the preliminary steps required to set up your carrier services.
The collection assumes that your workflow is the default one in Delivery Manager - i.e. that you are set up to move automatically to 'Ready to manifest' (rather than 'Printed') after printing (refer to How do I Print and Manifest separately?).
API Methods used in the Collection
The API methods used in the collection are cut down versions of those referenced in From Pre-Ship through to Manifesting, i.e.
Running a request within the Collection
Your collection, once downloaded, should appear as a series of POST
requests in the left hand pane, as shown below. They are numbered 1-6 and should be run in the sequence indicated, as each call is dependent on a previous one.
Note
It is not appropriate to use the Postman Collection Runner as you will need to amend the values of particular variables between the running of requests.
Proceed as follows:
-
Click on the first request in the collection (findDeliveryOptionsWithBookingCode) and ensure that the Metapack Shipping API environment is selected in the top right hand corner (this will have been imported alongside your collection):
The request URL is set to the SOAP endpoint (i.e. the full path to the particular Delivery Manager service). In the above example, this is:
https://dm-delta.metapack.com/dm/services/AllocationService
Note
While REST typically uses JSON and other data formats, SOAP relies on XML, which is entered under the Body tab and must include the SOAP
Envelope
,Header
andBody
tags. The name of the particular API method is given at the top of theBody
tag. The body type is set toraw
.The values used in the request are a mixture of fixed values (e.g.
<parcelValue xsi:type="xsd:double">300</parcelValue>
) and variable values (enclosed within double braces, e.g.{{orderNumber}}
,{{recipientCountry}}
, etc.). -
Overwrite the fixed values as required, e.g. enter your own values for the
parcelDepth
,parcelHeight
,parcelValue
,parcelWeight
andparcelWidth
. -
For the variable values, go to the Metapack Shipping API environment in the top right hand corner of the application. Display the variables by first going to the Quick Look (eye) icon, and then clicking Edit:
-
You will see a list of variables representing many of the mandatory fields required to make the first two requests in the collection. Enter the values for all the variables as far down as
recipientName
:Note
We have pre-filled both the
recipientCountry
andsenderCountry
values asGBR
, but you will need to overwrite these if you are shipping to and from other countries.For the construction of the
bookingCode
used with both findDeliveryOptionsWithBookingCode and despatchConsignmentWithBookingCode, refer to Introduction to Booking Codes.The
carrierConsignmentCode
is returned by despatchConsignmentWithBookingCode and is for use with findConsignmentsByCarrierConsignmentCode.The
carrierCode
is also returned by despatchConsignmentWithBookingCode and is for use with createManifest.The
manifestCode
is returned by createManifest and is for use with both findConsignmentsOnManifest and createManifestAsPdf.Once you have completed the
initial values
, click Reset All to set all theinitial values
tocurrent values
. Then click Update at the bottom of the above environment box to save your values. -
Once all the values are as required, click Send to make the request.
The response will be returned under the response Body tab in XML format, where the status should be
200 OK
for a valid response, e.g. -
Repeat from step 1 for the next request. You must ensure that the variables are set as required for each request. Instructions are given at the top of the request, e.g.
Note
Two of the calls - despatchConsignmentWithBookingCode and createManifestAsPdf - return encoded strings that contains PDF documents. To decode the strings and generate the PDFs, refer to Store the Paperwork and Print Later.