1. Metapack
  2. Shipping
  3. Shipping API
  4. Quick Start

Shipping API Postman Collection

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

  1. If you are new to the Shipping API, you will need a Delivery Manager account with your own Username and Password with which you can create and allocate consignments.

    Note

    Your Username and Password are entered against the Basic Auth type under the Authorization tab in Postman. These have already been parameterised for you.

    There is no need for an API key.

  2. 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.

  1. findDeliveryOptionsWithBookingCode

  2. despatchConsignmentWithBookingCode

  3. findConsignmentsByCarrierConsignmentCode

  4. createManifest

  5. findConsignmentsOnManifest

  6. createManifestAsPdf

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:

  1. 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):

    Postman_READY_from_SOAP.png

    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 and Body tags. The name of the particular API method is given at the top of the Body tag. The body type is set to raw.

    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.).

  2. Overwrite the fixed values as required, e.g. enter your own values for the parcelDepth, parcelHeight, parcelValue, parcelWeight and parcelWidth.

  3. 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:

    Postman_Environment_Top_Right.png

  4. 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:

    Postman_Environment.png

    Note

    We have pre-filled both the recipientCountry and senderCountry values as GBR, 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 the initial values to current values. Then click Update at the bottom of the above environment box to save your values.

  5. 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.

    Postman_back_from_SOAP.png

  6. 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.

    Postman_SOAP_Instructions.png

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.