Intelligent Shipper
| Anchor | ||||
|---|---|---|---|---|
|
Multipiece Shipment Bookings
Technical User Guide
API Version: 1.6
Document Version: 1.6.28
| 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 | ||||
|---|---|---|---|---|
|
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.
- 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 | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
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 | ||||
|---|---|---|---|---|
|
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 | ||||
|---|---|---|---|---|
|
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 | |
printManifest | Returns a manifest image in Base64 encoded PDF format. | Optional | Post |
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 | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
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 | ||||
|---|---|---|---|---|
|
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 | |||
<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 | ||||
|---|---|---|---|---|
|
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 | ||
<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 | ||||
|---|---|---|---|---|
|
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 | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
| Anchor | ||||
|---|---|---|---|---|
|
The createShipment service is used to generate the final delivery label(s) for your packages.
| Anchor | ||||
|---|---|---|---|---|
|
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. | |||
<shipperVatNumber> | C–15 | C | Shipper's VAT Number. | |||
<shipperEoriNumber> | C-18 | C |