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.6
Document Version: 1.6.28




Document Owner

INTERSOFT Systems and Programming Limited

Version

1.6.28

Date

15/07/2022h

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
_Toc108790102
_Toc108790102
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
_Toc108790103
_Toc108790103
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
_Toc108790104
_Toc108790104
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
_Toc108790105
_Toc108790105
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.6/shipments/createShipmentRequest

cancelShipment

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

Optional

Post

/api/v1.6/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.6/shipments/confirmShipmentRequest

printDocument

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

Optional

Post

/api/v1.6/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.6/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.6/shipments/manifestHistoryRequest

printManifest

Returns a manifest image in Base64 encoded PDF format.

Optional

Post

/api/v1.6/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
_Hlk14797475
_Hlk14797475
Anchor
_Toc108790106
_Toc108790106
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
_Toc108790107
_Toc108790107
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
_Toc108790108
_Toc108790108
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
_Toc108790109
_Toc108790109
Response Footer

If the data in the request generated any errors or warnings, 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

 

 

 

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
_Toc53581486
_Toc53581486
Anchor
_Toc53581487
_Toc53581487
Anchor
_Toc53581488
_Toc53581488
Anchor
_Toc53581489
_Toc53581489
Anchor
_Toc53581490
_Toc53581490
Anchor
_Toc53581491
_Toc53581491
Anchor
_Toc53581492
_Toc53581492
Anchor
_Toc53581493
_Toc53581493
Anchor
_Toc53581494
_Toc53581494
Anchor
_Toc53581495
_Toc53581495
Anchor
_Toc53581596
_Toc53581596
Anchor
_Toc53581597
_Toc53581597
Anchor
_Toc53581598
_Toc53581598
Anchor
_Toc53581599
_Toc53581599
Anchor
_Toc53581600
_Toc53581600
Anchor
_Toc53581601
_Toc53581601
Anchor
_Toc53581652
_Toc53581652
Anchor
_Toc108790110
_Toc108790110
createShipment

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

Anchor
_Toc108790111
_Toc108790111
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.