Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.



Intelligent Shipper

Anchor
_Hlk14796972
_Hlk14796972
Shipping Integration API
Multipiece Shipment Bookings
Technical User Guide
API Version: 1.7
Document Version: 1.7.11


Document Owner

INTERSOFT Systems and Programming Limited

Version

1.7.11

Date

15/07/2022

Description

Describes how to integrate with the Intelligent Shipper Shipment Booking API

Author

Laura Price



Anchor
_Hlk14797052
_Hlk14797052
Commercial and in Confidence
The information contained in this document is confidential.  No part of this document may be reproduced, disclosed to any third party, or issued in any form or by any means without the express written permission of Intersoft Systems & Programming Ltd.

  1. Contents

2. Introduction
2.1. Implementation of the Service
2.2. Fair Usage Policy
3. API Services
4. Integration Header and Footer
4.1. Request Header
4.2. Response Header
4.3. Response Footer
5. createShipment
5.1. createShipmentRequest
5.2. createShipmentResponse
6. cancelShipment
6.1. cancelShipmentRequest
6.2. cancelShipmentResponse
7. confirmShipment
7.1. confirmShipmentRequest
7.2. confirmShipmentResponse
8. printDocument
8.1. printDocumentRequest
8.2. printDocumentResponse
9. printQRCode
9.1. printQRCodeRequest
9.2. printQRCodeResponse
10. manifestHistory
10.1. manifestHistoryRequest
10.2. manifestHistoryResponse
11. printManifest
11.1. printManifestRequest
11.2. printManifestResponse
12. Terms and Definitions
13. Document Controls

Anchor
_Toc473545162
_Toc473545162
Anchor
_Toc103865249
_Toc103865249
Introduction

Anchor
_Hlk14797101
_Hlk14797101
This document describes the XML interface for the Intelligent Shipper Multipiece Shipment Bookings functionality. Example XML messages for each service are provided in the document "Intelligent Shipper API – Multipiece Shipment Bookings XML Examples".

Anchor
_Toc103865250
_Toc103865250
Implementation of the Service

The service is implemented using XML messaging. The customer is responsible for sending an XML message in the format displayed in the document "Intelligent Shipper API – Multipiece Shipment Bookings XML Examples". The customer is responsible for maintaining the capability of receiving XML messages in the format displayed in the example XML responses.
XSDs are not required, so do not exist. Communication to Intelligent Shipper endpoints will only utilise HTTPS. TLS version 1.2 (In affect from March 31st, 2020) only will be enabled. TLS cipher suites utilised on the Intelligent Shipper solution can be found via the below link for the Sandbox environment:
https://www.ssllabs.com/ssltest/analyze.html?d=test.intelligentshipper.net&latest
XMLs will be processed via Post actions. XMLs will be secured by data passed in the Integration Header portions of the XMLs provided. Intersoft will provide the required credentials via email as part of the onboarding process.

Anchor
_Toc103865251
_Toc103865251
Fair Usage Policy

In order to maintain optimal performance of our API and ensure that all partners and customers have a good experience, we urge all developers to consider and optimize their calls and flows. Fair use is defined as 20,000 API calls per 24-hour period per agreement.
If an application creates an excessive load on the API, Intersoft is at liberty, without warning, to restrict the integration's access to our APIs. Intersoft will offer help and guidance on how to optimise the technical implementation.

Anchor
_Toc103865252
_Toc103865252
API Services

The Intelligent Shipper Multipiece Shipment Bookings API contains the following services:

Service Name

Description

Mandatory / Optional

Allowed Methods

URL

createShipment

Creates a new shipment and generates the shipping label.

Mandatory

Post

/api/v1.7/shipments/createShipmentRequest

cancelShipment

Cancels a current shipping label for shipments that have not been confirmed.

Optional

Post

/api/v1.7/shipments/cancelShipmentRequest

confirmShipment

Locks down the shipment so that it can no longer be edited and generates the required collection paperwork (e.g. Manifest).

Mandatory

Post

/api/v1.7/shipments/confirmShipmentRequest

printDocument

Returns customs documentation for a shipment in the requested format – CN23, Proforma Invoice or Commercial Invoice.

Optional

Post

/api/v1.7/documents/printDocumentRequest

printQRCode

Generates a QR code for returns shipments using Royal Mail Tracked Returns services. The QR code can then be scanned at the Post Office to generate the returns label

Optional

Post

/api/v1.7/shipments/generateQRCodeRequest

manifestHistory

Returns details of the manifests created on a specified date. The manifest details returned in the response can then be used with the printManifestRequest to return a PDF manifest image.

Optional

Post

/api/v1.7/shipments/manifestHistoryRequest

printManifest

Returns a manifest image in Base64 encoded PDF format.

Optional

Post

/api/v1.7/shipments/printManifestRequest


The document contains a separate section for each of these services, which describes the service in more detail including the request and response XML content.

Anchor
_Integration_Header
_Integration_Header

Anchor
_Toc103865253
_Toc103865253
Anchor
_Hlk14797475
_Hlk14797475
Integration Header and Footer

The request and response header and response footer use the same format across each API service. The purpose and XML content of these header and footer sections is described below. Content unique to each service is described in the section for that service.

Anchor
_Toc103865254
_Toc103865254
Request Header

The request header confirms the version number being used and denotes the UTF-8 encoding used in the service. The header confirms who the request is coming from and verifies the credentials used in the request.
The request header contains the following elements:

Element Name

Data Type

Mandatory /Conditional / Optional

Notes

serviceNameRequest/integrationHeader

 

 

 




<dateTimeStamp>

D–19

O

YYYY-MM-DD HH:MM:SS
Date/Time Stamp of the request.

<transactionId>

C–32

M

Unique identifier of the request, preserved throughout the lifespan of the transaction. This must be generated by the customer.

<applicationId>

C–10

M

The ID of the Service Requester calling the service. This will be provided by Intersoft.

<userId>

C–10

M

User ID for system access. This will be provided by Intersoft.

<password>

C–10

M

Password for system access. This will be provided by Intersoft.


Anchor
_Toc103865255
_Toc103865255
Response Header

The response header contains the following elements:

Element Name

Data Type

Mandatory /Conditional / Optional

Notes

serviceNameResponse/integrationHeader

 

 

 




<dateTimeStamp>

D–16

O

YYYY-MM-DD HH:MM
Date/Time Stamp of the response.

<transactionId>

C–32

M

ID preserved throughout the lifespan of the transaction, unique when combined with the applicationId.

<applicationId>

C–10

M

The ID of the Service Provider, unique when combined with the TransactionId.


Anchor
_Toc103865256
_Toc103865256
Response Footer

If the data in the request generated any errors, the response XML will include a footer element containing details of these.
The response footer contains the following elements:

Element Name

Data Type

Mandatory /Conditional / Optional

Notes

serviceNameResponse/errors/errorDetail

 

 

 

 





<errorCode>

C–5

C

Error Code. Code associated with the error condition

<errorDescription>

C–32

C

Description of the error condition

<errorCause>

C–4

C

Cause of the business error (if known)

<errorResolution>

C–50

C

Description of the resolution and action required to correct the error

<errorContext>

C–50

C

Context of the business error, e.g. client or server


Each section will only be present if any errors were generated. See the document "Intelligent Shipper API – Multipiece Shipment Bookings Appendices" for a list of all the errors that could potentially be returned for each service.



Anchor
_Toc103865257
_Toc103865257
createShipment

The createShipment service is used to generate the final delivery label(s) for your packages.

Anchor
_Toc103865258
_Toc103865258
createShipmentRequest

The createShipmentRequest contains the following sections:

  • Shipper – contains the shipper address and contact details.
  • Destination - delivery address and contact details – it is the shipper's responsibility to provide accurate and concise information to ensure the best possible delivery experience for the consumer.
  • Shipment Information - the package and contents being sent. It is important that accurate information is supplied to ensure correct handling by customs authorities.
  • Item Information - the items being sent in the shipment. One shipment may contain multiple items. This information is used customs authorities to process clearance (where required).


Element Name

Data Type

Mandatory / Conditional / Optional

Notes

createShipmentRequest/shipment/shipper

 

 

 




<shipperCompanyName>

C–35

M

Shipper Company Name.

<shipperAddressLine1>

C–35

M

First line of shipper address.

<shipperAddressLine2>

C–35

O

Second line of shipper address, if applicable.

<shipperAddressLine3>

C–35

O

Third line of shipper address, if applicable.

<shipperCity>

C–30

M

Shipper Town.

<shipperCounty>

C–35

O

Shipper County.

<shipperCountryCode>

C–2

M

2 Digit ISO Country Code, per ISO 3166 Standard.

<shipperPostCode>

C–10

M

Shipper's Postcode.

<shipperContactName>

C–40

O

Shipper's Contact Name.

<shipperPhoneNumber>

C–20

M

Shipper's Contact Phone.
Accepts numeric characters and the following special characters only:
+.()-
No other special characters are accepted.

<shipperVatNumber>

C–15

C

Shipper's VAT Number.
Mandatory for some carriers. See the document "Intelligent Shipper Carrier Integrations and Features" for more information.

<shipperEoriNumber>

C-18

C

Shipper's EORI Number.
Mandatory for some carriers. See the document "Intelligent Shipper Carrier Integrations and Features" for more information.

<shipperEmailAddress>

C–254

O

Shipper's Email Address.

<shipperReference>

C–20

M

This is used for Returns processing and is usually the shipper's order number provided to the consumer.

<shipperReference2>

C-20

O

For Royal Mail shipments this must only be used to provide the eBay Virtual Tracking Number (VTN) – no other reference should be provided in this field.
For all other carriers this can be used to provide any further identifiers in addition to shipper reference. See the document "Intelligent Shipper Carrier Integrations and Features" for a list of which integrations use Shipper Reference 2.

<shipperDeptCode>

C–17

O

Shipper's Department Code.

createShipmentRequest/shipment/destination

 

 

 




<destinationCompanyName>

C–35

O

For domestic deliveries, use the contact name here.

<destinationAddressLine1>

C–35

M

Please ensure the address data is presented in line with the destination country formats.

<destinationAddressLine2>

C–35

O

Please ensure the address data is presented in line with the destination country formats.

<destinationAddressLine3>

C–35

O

Please ensure the address data is presented in line with the destination country formats.

<destinationCity>

C–30

M

Destination Town Name.

<destinationCounty>

C–35

C

Required for Australia, USA and Canada.

<destinationCountryCode>

C–2

M

2 Digit ISO Country Code, per ISO 3166 Standard.

<destinationPostCode>

C–10

C

Mandatory for countries where post code is required for delivery.

<destinationContactName>

C–40

M

Delivery Contact Name.

<destinationPhoneNumber>

C–20

M

Delivery Contact phone number. If an SMS notification enhancement is used, this must contain a valid mobile phone number for the destination country.
Accepts numeric characters and the following special characters only:
+.()-
No other special characters are accepted.
For Royal Mail shipments where an SMS notification enhancement is used, the following rules apply:

  • Phone number must start with "0" or "44"
  • Must then be followed by "7" and then any other number
  • If starting with 0, maximum length is 11. If starting with 44, maximum length is 12 e.g. 07123456789 or 447123456789
  • Any premium numbers, like the ones starting 070 are not allowed.

<destinationVatNumber>

C–15

O

Delivery VAT number.

<destinationEmailAddress>

C–254

C

Delivery Email Address. Required when an email notification service enhancement is used.

<deliveryInstructions>

C-50

O

Additional information relating to the delivery address, e.g. instructions on how to find or access the address. If the carrier supports additional delivery instructions this will be printed on the label.

NOTE: To specify a safe place for delivery when using Royal Mail and Parcelforce services, use the <safePlace> element instead.

<destinationPudoId>

C–20

O

PUDO Store ID or Postcode.

createShipmentRequest/shipment/shipmentInformation

 

 

 




<shipmentDate>

D–10

M

Date of despatch – YYYY-MM-DD.

<serviceCode>

C–4

M

Service Code.

createShipmentRequest/shipment/shipmentInformation/offLineShipment

 

 

 




<trackingNumber>

C-30

C

NOTE: The offLineShipment section is optional. This should only be included in the createShipmentRequest when you want to create an offline shipment (i.e. create a shipment record in Intelligent Shipper for a shipment that had a tracking number allocated outside of the system). For online/standard shipments do not include this section in the request.

When creating an offline shipment, this element is mandatory. Provide the tracking number allocated to the shipment.

<itemId>

C-8

C

Unique sequence number used in the 2D barcode.
Mandatory for Royal Mail offline shipments only; this does not need to be provided for any other carriers.

<carrierCode>

C-4

C

When creating an offline shipment, this element is mandatory. Provide the carrier code of the shipment carrier.
NOTE: The carrier code provided must be valid for the shipment service code, else an error will be returned.

<status>

C-30

O

Defaulted to printedOffline.

createShipmentRequest/shipment/shipmentInformation/serviceOptions

 

 

 




<postingLocation>

C-10

C

RMG Posting location.
Mandatory if using a Royal Mail service and your customer account has more than one posting location. Not required if your Royal Mail account only has one posting location.

Not required for non-Royal Mail shipments.

<serviceLevel>

C-2

O

Service level code. Valid values are 01-99.
Only used for Royal Mail services. If service level is not provided then the lowest available service level will be used.

Not required for non-Royal Mail shipments.

<serviceFormat>

C-1

O

Service format code. Valid values are L, F, P, G, E, N, H.
Only used for Royal Mail services. If service format is not provided, the default service format set in the system will be used.

Not required for non-Royal Mail shipments.

<safePlace>

C-30

O

Free text to describe a safe place to leave the parcel, if the service allows it.

If safe place is being used with Parcelforce service enhancements then a valid Parcelforce safe place must be used, else the safe place will be defaulted to "Driver Choice". See the Appendices document for a list of valid Parcelforce safe places.

createShipmentRequest/shipment/shipmentInformation/serviceOptions/serviceEnhancements

 

 

 




<serviceEnhancementCode>

C-10

O

May contain either a service enhancement code setup by the System Administrator or a Royal Mail service enhancement code. The System Administrator can provide a list of the service enhancement codes available in the system.
A list of valid Royal Mail service enhancement codes is provided in the Appendices document.
Multiple service enhancements can be used for a shipment; repeat the element for each service enhancement code required. For Royal Mail service enhancements, a maximum of four enhancement codes can be supplied per shipment.

If the requested enhancement(s) are not available for the service or if more than one enhancement is requested from a single enhancement group then an error will be returned in the response. See the Appendices document for a list of all potential errors that may be returned.

createShipmentRequest/shipment/shipmentInformation

 

 

 




<totalPackages>

N–2

M

Total number of packages.
Min=1 max=99.
For a list of the carriers that support multipackage shipments, see the document "Intelligent Shipper Carrier Integrations and Features".

<totalWeight>

N–7,3

M

Total weight of the parcel including packaging.

<weightId>

C–1

O

Weight unit of measurement.
K = Kgs / L = Lbs.
Defaults to K if blank.

<unitOfMeasurement>

C–1

O

Dimensions unit of measurement.
Always "C" for Centimetres.

<product>

C–3

M

Product type.
DOX for Document Shipments or NDX for any other content type.

<descriptionOfGoods>

C–70

M

General description of the goods being sent.

<reasonForExport>

C-50

O

Used to provide the reason an international shipment is being sent e.g. Sale, Gift, Return etc.
Currently only used with Royal Mail shipments. For Royal Mail shipments, only the following values should be provided:

  • Gift
  • Commercial Sample
  • Documents
  • Returned Goods
  • Other
  • Sale of goods
  • Mixed Content
    If Reason for Export is provided for a Royal Mail shipment, this will override the Default Reason for Export set on the customer's Royal Mail account record.

<declaredValue>

N–10,2

M

Total Shipment Value.

<declaredCurrencyCode>

C–3

M

3-digit ISO Currency code for shipment value.

<terms>

C–3

O

Incoterms / terms of trade for international NDX shipments.
Valid values are DDU, DDP, DAP and DAT.
If DDP is requested for a carrier that does not support it an error will be returned in the createShipmentResponse. See the Appendices document for details of the error.
If this field is not populated for International NDX shipments then DDU will be used by default.
Terms does not need to be provided for International DOX shipments.

<labelImageFormat>

C-10

O

Supported formats are PDF, and PNG. For Royal Mail shipments only, the ZPL formats , ZPL203DPI and ZL300DPI are also supported.. The ZPL formats are available for Royal Mail shipments only.
A PDF will be returned as default if a format is not specified.
Only PDF format will return customs documents.
Only PDF format can be used with multipiece shipments.

<silentPrintProfile>

C-36

O

The Silent Print application allows labels to be automatically printed to a chosen printer when shipments are created.
To automatically print the shipment label, provide the Silent Print Profile ID of the API user. When the shipment is created the labels will be sent automatically to the configured printer.
See the Silent Print Manual for more information on silent printing.

<shipmentAction>

C-8

O

Valid values = Create, Allocate.
If this element is left blank or not populated the shipment will be created as a processed shipment, and a label and tracking number will be returned in the response.
shipmentAction = Create will create the shipment in unprocessed state and the label and tracking number will not be generated. The unprocessed shipment must be scanned to generate the label and tracking number.
shipmentAction = Allocate will create the shipment in unprocessed state, return a tracking number in the response and create the label but not return it in the response. When the unprocessed shipment is scanned the label will be printed and the shipment will be moved to processed state.

createShipmentRequest/shipment/shipmentInformation/customsInformation

 

 

 




<preRegistrationNumber>

C-50

C

Certain countries operate a Tax Pre-Registration scheme (e.g., VOEC in Norway, GST in Australia). If you are registered for a Tax Pre-Registration scheme for the destination country and are shipping under the scheme rules then provide the pre-registration number for the destination country.
Mandatory for some carriers. See the document "Intelligent Shipper Carrier Integrations and Features" for more information.

NOTE: VAT and EORI numbers should be provided in the shipperVatNumber and shipperEoriNumber elements, not in the preRegistrationNumber element.

<preRegistrationType>

C-18

C

Provide the type of pre-registration scheme being used e.g., IOSS, GST, VOEC, OSS etc.
Mandatory if pre-registration number is provided and ignored if pre-registration number is not provided.
NOTE: VAT and EORI numbers should be provided in the shipperVatNumber and shipperEoriNumber elements, not in the preRegistrationNumber element.

<shippingCharges>

N-7,2

C

The amount the end customer was charged for shipping. This should not be populated with the amount you were charged by the carrier for shipping.
Mandatory for some carriers. See the document "Intelligent Shipper Carrier Integrations and Features" for more information.
If provided, this will be displayed on customs documents generated for the shipment.

<otherCharges>

N-7,2

O

Any costs the end customer has been charged additional to the standard shipping cost e.g., insurance charges.

<quotedLandedCost>

N-7,2

C

The total cost quoted to the end customer for delivering the shipment. This includes shipping charges, other charges and any customs taxes and duties charges that were quoted to the end customer. Mandatory for some carriers. See the document "Intelligent Shipper Carrier Integrations and Features" for more information.

<invoiceNumber>

C-35

C

Provide the invoice number of the Proforma Invoice or Commercial Invoice associated with the shipment, if applicable.
Mandatory for some carriers. See the document "Intelligent Shipper Carrier Integrations and Features" for more information.
For Royal Mail shipments only, invoice number is mandatory if invoice date is provided.
If provided, this will be displayed on customs documents generated for the shipment.

<invoiceDate>

D-10

C

The invoice data of the Proforma/Commercial invoice.
Mandatory if an invoice number is provided, ignored if invoice number is not provided.

<exportLicense>

C-5

O

True/False
Indicates whether an export license is required for the shipment.
An export license is needed for a specific type of goods used predominantly for military purposes. You can find out more about the type of items requiring an export licence on the UK Government website.

<addresseeIdentificationReferenceNumber>

C-20

O

Provide Addressee Identification Reference Number if supported by the destination country. This is a numeric code used to track a consumers purchasing history in countries such as Russia and Brazil.

createShipmentRequest/shipment/shipmentInformation/packages/package

 

 

 




<packageTypeName>

C-40

O

Anchor
_Hlk14448584
_Hlk14448584
If you are using packaging provided by the carrier, populate with the carrier's exact packaging name e.g. FEDEX_BOX. If the correct carrier packaging name is not used this may result in overcharges from the carrier.
The Appendices document contains a list of the carrier package type names supported in the system. Further details on carrier packaging types are available on the carrier's website.

<packageId>

C-15

C