Document Owner

INTERSOFT Systems and Programming Limited

Version

1.7.17

Date

15/09/2023

Description

Describes how to integrate with the Intelligent Shipper Shipment Booking API

Author

Laura Price

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

generateQRCode

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

PreallocatedRMTrackingNumber

Pre-allocates a Royal Mail tracking number without creating a shipment and returns the tracking number in the response, so that it can  later be used in the createShipment request when generating a Royal Mail Shipping label.

Optional

Get

/api/v1.7/shipments/getPreallocatedRMTrackingNumberRequest

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. If the API requests for a customer account are being sent one at a time, so that one transaction has been completed before the next transaction is started, then the same transactionId can be used for all requests. However if a customer account is sending multiple API requests at a time (e.g. on multiple workstations) then each request will need to have a unique transactionId – there cannot be multiple transactions with the same transactionId occurring at one time.

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

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.

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

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

C

Mandatory for some carriers. See the document “Intelligent Shipper Carrier Integrations and Features” for more information.

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

Company name of the destination address, if applicable

<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