tracking api technical user guide - royal mail...tracking api technical user guide the api spec t01...

of 40

A

PI

Sp

ec

T0

1

Royal Mail Customer Solutions

Tracking API

Technical User Guide

The API Spec T01 document details, for customers, the requirements for integrating with the Tracking External Web Services.

It specifically covers how the Tracking API is used by customers to receive Track-and-Trace information, and provides the technical information to build this integration.

This specification must be used with the relevant accompanying specifications for customers wishing to interface their systems with Royal Mail services.

23rd June 2014 Version 1.2

of 40

Contents 1 Document Control ...................................................................................................................... 4

1.1 Terms and abbreviations ............................................................................................ 4 1.2 Document author and document location................................................................... 4 1.3 Version history ........................................................................................................... 4 1.4 Document review and distribution ............................................................................. 5 1.5 Document approval and sign-off ................................................................................ 5

2 Overview ...................................................................................................................................... 6 3 Purpose ........................................................................................................................................ 7 4 Introduction to Tracking API .................................................................................................... 8

4.1 Interface Components ................................................................................................ 8 5 Integrating with the API ............................................................................................................ 9 6 Tracking Services ..................................................................................................................... 11

6.1 Services .................................................................................................................... 11 6.2 Message Structure .................................................................................................... 11

7 Common API Elements ........................................................................................................... 12 7.1 integrationHeader ..................................................................................................... 12

7.1.1 Description ........................................................................................................ 12 7.1.2 Request Message ............................................................................................... 12 7.1.3 Response Message ............................................................................................ 12 7.1.4 Example Data .................................................................................................... 13

7.2 integrationFooter ...................................................................................................... 13 7.2.1 Description ........................................................................................................ 13 7.2.2 Response Message ............................................................................................ 14 7.2.3 Example Data .................................................................................................... 14

7.3 Security Credentials ................................................................................................. 15 7.3.1 Description ........................................................................................................ 15

8 API Service Operations ............................................................................................................ 16 8.1 WSDL & XSD List .................................................................................................. 16 8.2 getSingleItemHistory ............................................................................................... 16

8.2.1 Description ........................................................................................................ 16 8.2.2 Request Message ............................................................................................... 16 8.2.3 Response Message ............................................................................................ 16 8.2.4 Example Data .................................................................................................... 17

8.3 getSingleItemSummary ............................................................................................ 18 8.3.1 Description ........................................................................................................ 18 8.3.2 Request Message ............................................................................................... 18 8.3.3 Response Message ............................................................................................ 18 8.3.4 Example Data .................................................................................................... 19

8.4 getProofOfDelivery .................................................................................................. 20 8.4.1 Description ........................................................................................................ 20 8.4.2 Request Message ............................................................................................... 20 8.4.3 Response Message ............................................................................................ 20 8.4.4 Example Data .................................................................................................... 21

8.5 getMultiItemSummary ............................................................................................. 22 8.5.1 Description ........................................................................................................ 22

of 40

8.5.2 Request Message ............................................................................................... 22 8.5.3 Response Message ............................................................................................ 22 8.5.4 Example Data .................................................................................................... 23

9 Error Handling .......................................................................................................................... 25 9.1 Overview .................................................................................................................. 25 9.2 Technical Errors ....................................................................................................... 25 9.3 Business Errors ......................................................................................................... 25 9.4 Warnings .................................................................................................................. 25

10 Protocol Specification .............................................................................................................. 26 10.1 Overview .............................................................................................................. 26 10.2 Transport ............................................................................................................... 26 10.3 WSDL and Schemas ............................................................................................. 26 10.4 Service Endpoint................................................................................................... 26

11 Non Functional Characteristics .............................................................................................. 27 11.1 Availability ........................................................................................................... 27

11.1.1 Service Hours .................................................................................................... 27 11.1.2 Maintenance Windows...................................................................................... 27 11.1.3 Unavailability .................................................................................................... 27

11.2 Performance .......................................................................................................... 27 11.3 Security ................................................................................................................. 27

12 Frequently Asked Questions ................................................................................................... 30 13 Appendix A – Reference Data ................................................................................................. 32

13.1 Technical Errors ................................................................................................... 32 13.2 Business Error Codes............................................................................................ 33 13.3 Warning Codes ..................................................................................................... 33

14 Appendix B - XML Examples ................................................................................................. 34 14.1 getSingleItemHistory ............................................................................................ 34 14.2 getSingleItemSummary ........................................................................................ 35 14.3 getProofOfDelivery .............................................................................................. 36 14.4 getMultiItemSummary.......................................................................................... 37

15 Appendix C - Character Set ................................................................................................... 40

of 40

1 Document Control 1.1 Terms and abbreviations Term Meaning

BIG Business Integration Gateway

COSS Customer Own System Solution

DMO Despatch Manager Online

HTTP Hypertext Transfer Protocol

HTTPS Hypertext Transfer Protocol Secure

IP Internet Protocol

OBA Online Business Account

RMGTT Royal Mail Generic Track & Trace

SOAP Simple Object Access Protocol

TAPI Tracking API

TODS Tracking Operational Data Store

WSDL Web Service Definition Language

XSD XSD is XML Schema Definition – this defines a specific template for the XML used by particular systems

XML eXtensible Markup Language, a flexible standard for data inside a hierarchical structure of named data items

1.2 Document author and document location Name

Role and organisation

1.3 Version history Version Date Author Notes

0.1 XXX February 2014 Initial draft

0.2 6th Feb 2014 MP Updated following comments

0.3 17th March 2014 Tom Whelan Additional RM content added

0.4 24th March 2014 Tom Whelan Additional RM content added

0.5 1st April 2014 Peter Cowen Updated following RM Comments

0.5 5th May 2014 Chris Vaughan Additional RM Comments added

1.0 22nd May 2014 Chris Vaughan Baselined with baselined WSDL and XDS files and feedback from Adrian Tharby

1.1 23rd May 2014 Chris Vaughan Updated with revised version numbers for supporting files

1.2 23rd June 2014 Peter Cowen Updated following minor schema changes

of 40

1.4 Document review and distribution Version Date issued for

review Recipient name Role/Position &

Department Reviewer comments Date review

completed

0.5 04/04/2014 Caleb Carter CE Help Desk Nothing to add to S Dodd’s reply

17/04/2014

0.5 10/04/2014 Simon Dodd Customer Solutions Consultant

Inspection sheet including add Multiple items example

15/04/2014

1.2 12/06/2014 Tom Whelan Business Analyst Confirmation of changes made by P Cowen included in this version

13/06/2014

1.5 Document approval and sign-off Version Approval date Name Role/Position/Business unit

1.1 23 May 2014 Adrian Tharby Product owner, Royal Mail Parcels

1.2 23 June 2014 Adrian Tharby Product owner, Royal Mail Parcels

of 40

2 Overview Royal Mail Tracking API exposes web services that allow account customers to receive track-and-trace information for their mail items. Built on industry standards, Tracking API provides a simple and low cost method for customers to integrate with Royal Mail. There are no costs to customers for using the Tracking API services, however development costs must be covered by the customer. Royal Mail will not accept any responsibility for these development, implementation and testing costs. Customers should address initial enquiries regarding development of systems for these purposes to their account handler.

of 40

3 Purpose This document is to provide Royal Mail customers with guidelines and detailed specifications for integrating with Royal Mail via the Tracking API web services. The document details:-

• The specification for the web service interfaces • Description of errors the API can return • Non-functional characteristics of the API including response times, service

availability and security considerations This document is primarily intended to be read by developers and other technical roles involved with integrating customer systems’ with the Tracking web service API. This document should be read in conjunction with the following artefacts:

• Tracking WSDL • Tracking XSDs

The WSDL and XSD list is provided in Section 7.1 The web service interfaces included in the document are:

• getSingleItemHistory • getSingleItemSummary • getProofOfDelivery • getMultiItemSummary

of 40

4 Introduction to Tracking API Tracking API provides the functionality for customers to enquire on the tracking status of their mail items. It provides an alternative mechanism to using the track and trace function on the Royal Mail website: http://www.royalmail.com/track-trace. The APIs provide the latest track for single and multiple mail items, the tracking history for a single mail item, and the proof of delivery information (minus the signature image) for a single mail item.

4.1 Interface Components

RM Tracking API

getSingleItemHistory()

getSingleItemSummary()

Scope of this document

HTTPS

Customer System

getProofOfDelivery()

getMultiItemSummary()

http://www.royalmail.com/track-trace

of 40

5 Integrating with the API What you need Once your organisation has been sent and accepted the Royal Mail Online Services Terms & Conditions, you will be provided with an Application ID and a certificate that will allow you to connect to the Tracking web service API. The URL for the Tracking web service API is: https://api.royalmail.com/tracking Acceptable Use The Royal Mail Online Services Terms and Conditions cover the ways in which the service may be used, and any integration activities must abide by these. While the Terms and Conditions do not specify hard limits for the number of enquiries that customers may make (since different customers will have different needs), Royal Mail expects customers to use the service in a responsible way; this includes refraining from continuously polling the API for updates. Updates to the backend systems that support the Tracking API are made hourly, so more frequent polling will not yield updated results. All Royal Mail APIs impose a cap on the number of transactions per second for each customer. Excessive volumes of traffic within a short period will result in transactions being refused WSDL Versioning Royal Mail is continuously working to improve its technology, and as part of this process updates to the services provided may on occasion necessitate a new WSDL version.. Royal Mail will look to maintain three versions of the WSDL; as new versions are introduced, previous versions move down the stack until they are ultimately removed completely:

• Latest version • Previous version • Deprecated version

Customers will always be encouraged to integrate against the latest version as this will give them the longest stable period without the need to change, but if they have already begun integration activities when a new version is released then they will be able to integrate against the previous version. Customers should not integrate against the deprecated version. Royal Mail’s target is to release a new version of the WSDL no more frequently than once per year. There is currently no onboarding environment for Tracking API; given that this is a read only interface there are no billing implications associated with integrating against the live service. Customers should note that in line with other APIs, performance testing during the integration process is not permitted. Certificate Expiration Certificates are issued with a validity period of 1 year, after which time you will need to update your system with the replacement certificate. An email reminder will be sent to

https://api.royalmail.com/tracking

of 40

you prior to the expiry date. If you do not receive such an email, contact RM Helpdesk on 08456 047267.

of 40

6 Tracking Services

6.1 Services

Business Service

Description Request Message Response Message Conversation Style

Service Type

Get Single Item History

Provides the tracking history for a single mail item.

getSingleItemHistoryRequest getSingleItemHistoryResponse

Synchronous Request / Response

Webservice

Get Single Item Summary

Provides the latest tracking event for a single mail item.

getSingleItemSummaryRequest

getSingleItemSummaryResponse


Webservice

Get Proof Of Delivery

Provides the proof of delivery information for a single mail item.

getProofOfDeliveryRequest getProofOfDeliveryResponse


Webservice

Get Multi Item Summary

Provides the latest tracking event for up to 5 mail items.

getMultiItemSummaryRequest getMultiItemSummaryResponse


Webservice

6.2 Message Structure Figure 1 - Message Structure Each of the above operations (in section 6.1) is defined as a SOAP operation, with separate request / response message parts. Technical details are documented in the WSDL and XSD schemas which should accompany this document. Within the SOAP body tags, each request message from customer systems is supplemented with an integrationHeader node and is described in Section 6.1. The definition of the data types used within the elements section of each service call is defined within the schemas in section 7.

Request

Integration Header

Message Content

Response

Integration Header

Message Content

Integration Footer

of 40

7 Common API Elements 7.1 integrationHeader

7.1.1 Description

The integrationHeader element is present in all request and response messages, and is used to support security and logging functionally within Royal Mail systems.

7.1.2 Request Message

All elements are relative to the integrationHeader element in the request message. integrationHeader Element occurs Type Description dateTime 0-1 DateTim

e This should be populated with the date timestamp when the message was generated.

version 0-1 Decimal The version of the API currently being used (initially 1.0).

identification 1-1 Object Identification object used to identify customer and transaction details supplied by customer. See identification table below for structure.

testFlag 0-1 Boolean Not Used by Tracking API. debugFlag 0-1 Boolean Not used by Tracking API.

Identification Element Occurs Type Description enduserID 0-1 String Not used by Tracking API applicationId 1-1 String This is the ten digit Customer Account Number

allocated by Royal Mail intermediaryId 0-1 String Not used by Tracking transactionId 1-1 String This is a unique number to identify the transaction

number as provided by customer systems.

7.1.3 Response Message

All elements are relative to the integrationHeader element in the response message. integrationHeader Element occurs Type Description dateTime 0-1 DateTim

e This is always returned and contains the same value provided in the request.

version 0-1 Decimal This is always returned and contains the same value provided in the request.

identification 1-1 Object This is always returned and contains the same values provided in the request.

testFlag 0-1 String Not Used by Tracking API, but will return the same value provided in the request if used

debugFlag 0-1 String Not used by Tracking API, but will return the same value provided in the request if used

of 40

Identification Element Occurs Type Description enduserID 0-1 String Not used by Tracking API, but will return the same

value passed in the request if used. applicationId 1-1 String This is always returned with the same ten digit

Customer Account Number provided in the request. intermediaryId 0-1 String Not Used by Tracking API, but will return the same

value provided in the request if used transactionId 1-1 String This is always returned with the same unique

transaction number provided in the request

7.1.4 Example Data

Full XML examples of SOAP requests and responses are provided in Section 14 at the end of this document. This section provides a simplified example shown focused on the integrationHeader only.

Example Request Data for the Integration Header Element Value dateTime 2014-01-01T 21:32:52 version 1.0 identification enduserID Null applicationId 0123456789 intermediaryId Null transactionId 9876543210 identification testFlag Null debugFlag Null

Example Response Data for the Integration Header Element Value dateTime 2014-01-01T21:32:52 version 1.0 identification enduserID Null applicationId 0123456789 intermediaryId Null transactionId 9876543210 identification testFlag Null debugFlag Null

7.2 integrationFooter

7.2.1 Description

The purpose of this element is to provide warning and error messages back to the customer. The integrationFooter element will be present in all response messages. If there are no errors or warnings this element will be empty.

of 40


All elements are relative to the IntegrationFooter element in the response message. IntegrationFooter Element Occurs Type Description errors 0-1 Object This will contain details on any errors encountered

in Tracking API. See sections 13.1 and 13.2 for a full list.

warnings 0-1 Object This will contain details on any warnings encountered in Tracking API. See section 13.3 for a full list.

Error Element Occurs Type Description errorCode 1-1 String This is the RM specified code for the error message. errorDescription 1-1 String This is the description associated with the error

code. errorCause 0-1 String This is the cause of the error if known. errorResolution 0-1 String This is the description of the resolution and action

required to correct the error if known. errorContext 0-1 String This is the context of the error, e.g. client or server. Warning Element Occurs Type Description warningCode 1-1 String This is the RM specified code for the warning

message. warningDescription 1-1 String This is the description associated with the warning

code warningCause 0-1 String This is the cause of the warning if known. warningResolution 0-1 String This is the description of the resolution and action

required to correct the warning if known. warningContext 0-1 String This is the context of the warning, e.g. client or

server.

7.2.3 Example Data

Full XML examples of SOAP requests and responses are provided in Section 14 at the end of this document. This section provides a simplified example shown focused on the integrationFooter only. Example Response Data for the Integration Footer Element Value errorCode E1043 errorDescription Tracking data not available errorCause It is not possible to provide information about events that occurred

more than [configurable variable] days ago errorResolution Please use the Royal Mail Track and Trace website to obtain data of

this age errorContext Null

of 40

7.3 Security Credentials

7.3.1 Description

There are no additional security credentials required apart from the initial security certificate and applicationID required to use any of the Royal Mail API’s.

of 40

8 API Service Operations 8.1 WSDL & XSD List This section includes the full definition on the Tracking Web Service – documented through the supporting WSDL and XSD files. The WSDL (Tracking_ API_V1.2.wsdl) and the XSD (Tracking_API_V1.2.xsd) for Tracking API are provided in supporting files.

8.2 getSingleItemHistory

8.2.1 Description

Provides a history of tracks for a single mail item.


Element Occurs Type Description integrationHeader 1-1 Object Integration Header as described in section 6.1 trackingNumber 1-1 String 13 digit barcode tracking number of the mail item

being queried.


The response will contain the integrationHeader as passed in the request plus the addition of the Tracking Details for each track followed by the integrationFooter. Element Occurs Type Description integrationHeader 1-1 Object Integration Header as described in section 6.1 trackDetails 0-N Object Contain details for each tracking scan for the mail

item. integrationFooter 0-1 Object Integration Footer as described in section 6.1

trackDetail Element Occurs Type Description trackDate 0-1 Date Date the mail item tracking scan was taken. trackPoint 0-1 String Location the mail item tracking scan was taken

from. trackTime 0-1 Time Time the mail item tracking scan was taken. trackTimeStr 0-1 String String representation of time the mail item tracking

scan was taken. This is only present if source scanning system only provides a string representation of the time e.g. “AM” or “PM”

header 0-1 String Status of the tracking scan as seen on the Royal Mail track and trace portal.

footer 0-N Object Contains eContent business messages as seen on the Royal Mail portal.

podMessage 0-1 String Message indicating if there may be a proof of delivery (signature image) associated with the tracking scan.

of 40

footer Element occurs Type Description footerID 0-1 String eBusiness Content message ID. footerText 0-1 String eBusiness Content message detail.

8.2.4 Example Data

Full XML examples of SOAP requests and responses are provided in Section 14 at the end of this document. This section provides a simplified example shown only. Example Request Data Element Value integrationHeader dateTime 2014-01-01T21:32:52 version 1.0 identification enduserID Null applicationId 0123456789 intermediaryId Null transactionId 9876543210 identification testFlag Null debugFlag Null integrationHeader trackingNumber FJ111111111GB

Example Response Data Element Value integrationHeader dateTime 2014-01-01T21:32:52 version 1.0 identification enduserID Null applicationId 0123456789 intermediaryId Null transactionId 9876543210 identification testFlag Null debugFlag Null integrationHeader trackdetail trackDate 2013-12-13 trackPoint London East Mail Centre trackTime 11:59:10 header Delivered footer footerID 1024 footerText Thank you for using this service. footer trackDetail integrationFooter errors Null warnings Null

of 40

Element Value integrationFooter

8.3 getSingleItemSummary

8.3.1 Description

Provides the latest track for a mail item.


Element occurs Type Description integrationHeader 1-1 Object Integration Header as described in section 6.1 trackingNumber 1-1 String 13 digit barcode tracking number of the mail item

being queried.


The response will contain the integrationHeader as passed in the request plus the latest tracking status of the mail item being queried followed by the integrationFooter. Element occurs Type Description integrationHeader 1-1 Object Integration Header as described in section 6.1 itemSummary 0-1 Object latest tracking status of the mail item being queried integrationFooter 0-1 Object Integration Footer as described in section 6.1

itemSummary Element occurs Type Description eventDate 0-1 Date Date the mail item tracking scan was taken eventTime 0-1 Time Time the mail item tracking scan was taken eventTimeStr 0-1 String String representation of time the mail item tracking


statusCode 0-1 String Status code for mail item’s last tracking scan summaryLine 0-1 String Summary message for mail item’s last tracking scan trackingNumber 0-1 String tracking number of the mail item being queried header 0-1 String Status for mail item’s last scan footer 0-1 Object Contains eContent business messages as seen on

the Royal Mail portal.


of 40

8.3.4 Example Data


Example Response Data Element Value integrationHeader dateTime 2013-12-30T21:32:52 version 1.0 identification enduserID Null applicationId 0123456789 intermediaryId Null transactionId 9876543210 identification testFlag Null debugFlag Null integrationHeader itemsummary date 2013-12-26 time 14:48:45 statusCode code EVAPA statusCode summaryLine The sender has advised us that item FJ111111111GB will be posted

into the Royal Mail network on the 2013-12-31. trackNumber FJ111111111GB header Please come back later footer footerID 1010 footerText Recorded Signed For items are only tracked after the item has been

delivered. Depending on whether the item was sent first or second class, this may be a few days after posting. Please try again later.

footer integrationFooter errors Null

of 40

Element Value warnings Null integrationFooter

8.4 getProofOfDelivery

8.4.1 Description

Provides the details captured at the point of delivery as proof that delivery has occurred. Note that a proof of delivery is only captured by the delivery track for those service offerings that require a signature on delivery. Please also note that for data protection reasons the API does not currently supply the signature image captured at the point of delivery



being queried.


The response will contain the integrationHeader as passed in the request plus the proof of delivery information of the mail item being queried if available followed by the integrationFooter. Element occurs Type Description integrationHeader 1-1 Object Integration Header as described in section 6.1 wSImageResponse 0-1 Object Contains details on proof of delivery. integrationFooter 0-1 Object Integration Footer as described in section 6.1

wSImageResponse Element occurs Type Description height 0-1 Float Height of the image. image 0-1 base64Bi

nary The signature image as captured. Note this is turned off and will not be supplied in the response.

printedName 0-1 String Printed name of the person who supplied the signature.

signatureTime 0-1 DateTime

Time the signature was captured.

trackingNumber 0-1 String Tracking number of the mail item being queried. width 0-1 Float Width of the image.

of 40

8.4.4 Example Data


Example Response Data Element Value integrationHeader dateTime 2014-01-01T21:32:52 version 1.0 identification enduserID Null applicationId 0123456789 I intermediaryId Null transactionId 9876543210 identification testFlag Null debugFlag Null wSImageResponse height 100 image <base 64 encoded image> printedName Joe Bloggs SignatureTime 11:48:12 trackNumber FJ111111111GB width 100 wSImageResponse integrationFooter errors Null warnings Null integrationFooter

of 40

8.5 getMultiItemSummary

8.5.1 Description

Provides the latest summary level tracking event data for up to 5 mail items at the same time.



being queried.


The response will contain the integrationHeader as passed in the request plus the proof of delivery information of the mail item being queried if available followed by the integrationFooter. Element occurs Type Description integrationHeader 1-1 Object Integration Header as described in section 6.1 itemSummary 1-5 Object latest tracking status of the mail items being queried integrationFooter 0-1 Object Integration Footer as described in section 6.1 itemSummary Element occurs Type Description eventDate 0-1 Date Date the mail item tracking scan was taken eventTime 0-1 Time Time the mail item tracking scan was taken eventTimeStr 0-1 String String representation of time the mail item tracking


statusCode.code 0-1 String Status code for mail item’s last tracking scan summaryLine 0-1 String Summary message for mail item’s last tracking scan trackingNumber 0-1 String Tracking number of the mail item being queried header 0-1 String Status for mail item’s last scan footer 0-1 Object Contains eContent business messages as seen on the

Royal Mail portal.


of 40

8.5.4 Example Data

Full XML examples of SOAP requests and responses are provided in Section 14 at the end of this document. This section provides a simplified example shown only. Example Request Data Element Value integrationHeader dateTime 2013-12-021T 21:32:52 version 1.0 identification enduserID Null applicationId 0123456789 intermediaryId Null transactionId 9876543210 identification testFlag Null debugFlag Null integrationHeader trackingNumbers trackingNumber FJ111111111GB trackingNumber FJ222222222GB trackingNumbers Example Response Data Element Value integrationHeader dateTime 2014-01-01T21:32:52 version 1.0 identification enduserID Null applicationId 0123456789 intermediaryId Null transactionId 9876543210 identification testFlag Null debugFlag Null integrationHeader itemSummaries itemSummary date 2013-12-20 time 12:03:00 statusCode code EVKSP statusCode summaryLine We have a record of item FJ111111111GB as being

delivered from London East Mail Centre on 2013-12-20. trackNumber FJ111111111GB header Delivered footer footerID 1024 footerText Thank you for using this service. footer

of 40

Element Value itemSummary itemSummary date 2013-12-12 time 14:37:00 statusCode code EVAPA statusCode summaryLine The sender has advised us that item FJ222222222GB will

be posted into the Royal Mail network on the 2013-12-23. trackNumber FJ222222222GB header Please come back later footer footerID 1010 footerText Recorded Signed For items are only tracked after the item

has been delivered. Depending on whether the item was sent first or second class, this may be a few days after posting. Please try again later.

footer itemSummary itemSummaries integrationFooter errors Null warnings Null integrationFooter

of 40

9 Error Handling 9.1 Overview The Tracking API service highlights issues in three ways:

• Technical Errors – Highlights fundamental problems with either the system or the request

• Business Errors – Indicates that while the request was correctly formatted, it contained invalid data that cannot be automatically corrected

• Warnings – Indicates that while the request was correctly formatted and the data was mostly accurate, there were minor corrections or assumptions that the system had to make to allow the request to be processed.

Please refer to the Reference Data section for the full list of all error and warning codes.

9.2 Technical Errors Technical Errors highlight that there is either a problem with the Royal Mail system or there is a fundamental problem with the messages being sent to Royal Mail by the customer. Examples of technical errors caused by the customer would include the use of an invalid security certificate or the submission of a request message that failed schema validation. Technical errors indicate that the request was not successful, and has not been processed by Royal Mail (e.g. getSingleItemHistory requests that receive a Technical Error will not result in a tracking enquiry being made on the mail tracking system). Technical errors may also be an indication of serious problems with the interaction between the customer and Royal Mail, and customer systems should be built in such a way that these errors are captured and reported to the relevant technical resources. Failure to do so may result in severe disruption to services.

9.3 Business Errors Business Errors indicate that the data provided in the request, while correctly formatted, is not valid. Examples of issues that would lead to a business error being received include attempting to enquire on a mail item where the barcode requested does not exist. Business errors indicate that the request was successful, and has been processed by Royal Mail but the request could not be satisfied due to incorrect data being supplied (e.g. getSingleItemSummary requests that receive a tracking number that doesn’t exist or the latest track is greater than 30 days old will result in a Business Error being returned from the mail tracking system).

9.4 Warnings There are currently no warning messages supplied by tracking API.

of 40

10 Protocol Specification 10.1 Overview All API service calls will be made using mutually authenticated HTTPS bound SOAP Web Services. The Tracking API exposes the services using SOAP version 1.1 with a document/ literal document-style encoding.

10.2 Transport HTTP over TLS is used for the transmission channel

10.3 WSDL and Schemas This section includes the full definition on the Shipping Web Service – documented through supporting WSDL and XSD files. The files themselves are provided separately. WSDL/XML Schema file Description Tracking_API_V1.2.wsdl WSDL describing the functionality offered by Royal Mail

Tracking API Tracking_API_V1.2.xsd Schema defining the data structures used by the Tracking

API CommonClassesV2_2.xsd Royal Mail (RMG) schema which defines common objects

such as “address” which are complex types with a defined structure based on RMG defined simple data types as well as reference data types.

DatatypesV2_2.xsd RMG defined simple types that are commonly required such as “date” and “name”. This schema is the foundation for the other schema files.

CommonIntegrationSchemaV1_9.xsd RMG schema which defines a common header definition to be used for request and response messages.

ReferenceDataV2_2.xsd RMG schema which defines a set of types for common reference data such as address fields that are defined using the RMG simple data types.

10.4 Service Endpoint https://api.royalmail.com/tracking/

https://api.royalmail.com/tracking/

of 40

11 Non Functional Characteristics 11.1 Availability

11.1.1 Service Hours

The Tracking API is available 24 hours per day x 365 days per year.

11.1.2 Maintenance Windows

Royal Mail Online Services Terms and Conditions define the maintenance window for this service.

11.1.3 Unavailability

In the unlikely event of the Tracking API being unavailable, customer systems should make provision to handle this appropriately.

11.2 Performance Performance testing has validated that the Tracking API responds to SOAP calls in less than 2 seconds on average when invoked from the edge of Royal Mail’s UK data centre. Performance will be slower during peak periods of activity (between 3 and 6, Monday to Friday). To avoid issues associated with slower response times during periods of heavy traffic, customers are strongly advised to spread their traffic out throughout the day where possible.

11.3 Security Security is provided via mutual authentication over a secure channel. Mutual authentication or two-way authentication refers to two parties authenticating each other suitably. It works by each party initially providing a “lock” to the other party. When communicating each party provides the “key” to their “lock” so the other side can verify the correct party is calling. In technology terms, it refers to a client or user authenticating themselves to a server and that server authenticating itself to the user in such a way that both parties are assured of the others' identity.

of 40

The “Lock” is a public key certificate issued by a trusted Certificate Authority (CA). Both of which Royal Mail and the customer will exchange with each other as needed. Each party then use their own private certificate to sign the communication channel. This signature is the “key” that then can be verified against the “lock” provided in the trusted public key certificate. When describing online authentication processes, mutual authentication is often referred to as website-to-user authentication, or site-to-user authentication. Typically, this is done for a client process and a server process without user interaction. Mutual SSL provides the same benefits as server only SSL, with the addition of authentication and non-repudiation of the client authentication, using digital signatures. Due to issues with complexity, cost, logistics, and effectiveness, most web applications are designed so they do not require client-side certificates. Certificate request procedure Customers who have already exchanged certificates with RMG can continue using their existing certificates. New customers (or existing customers who do not yet have a certificate) need to request access and exchange certificates in order to use the service. Tracking Secure Web Service Access and Data Transmission The customer system will be required to present known certificate security data each time a new connection to the Tracking Web Service is made. Customers will be requesting the necessary security credentials from RMG Certificate Authority (CA) to jointly verify credentials, namely:-

• Customer will raise a certificate signing request with the RMG Certificate Authority. RMG will provide the CA certificate and the signed client certificate. The certificates have to be valid and not expired.

of 40

• RMG Certificate Authority Certificate and public certificate. The certificates have to be valid and not expired.

Customers are required to install the RMG Root CA(s) on their system and to authenticate with the client certificate provided. Further, the customer is required to use the corresponding RMG Root CA to validate the RMG server certificate as part of their authentication process. The customer system should also check that the certificates are still valid i.e. have not expired.

of 40

12 Frequently Asked Questions

Will I get the same result from Tracking API as the RM Website Track-and-Trace function? Yes – the APIs use the same source tracking application and retrieval process as the website. The authentication has failed? What is the reason for this? Please check that your applicationID matches the one supplied by RMG. Which Account Number do I use as identification? The identification element requires your Bill-To account number as the applicationID. What should I use as a transactionID? You need to supply a value that is unique within your applicationID so that individual API requests can be identified. An incremental number is recommended. Is an eBay/Amazon plugin available? Unfortunately this is not available. Where can I find the latest versions of the Tracking API WSDL and supporting XSD files? We can email the latest version to you. Can Royal Mail complete the API programming for me? Royal Mail only provides user guides to enable an understanding of the Web Services and therefore cannot complete the programming for your business. What types of service offering can I look up via TAPI? Tracking API allows track-and-trace for the same service offerings as the Royal Mail website. Generally these are from the Special Delivery and RM Tracked product families. Why can’t I receive proof of delivery signatures from TAPI? We cannot provide the signature image via TAPI for reasons of customer privacy. How do I get the full proof of delivery information? If applicable, the name and receipt image of the person who signed for a mail item are available via the Royal Mail website. How long is tracking data available via the API? Tracking data is available via the API for 30 days. If you need tracking information that is older than this, please use the Royal Mail website, where data may be available for up to 12 months. I don’t have a business account with Royal Mail. Can I use the Tracking API? No – Tracking API is only available to Royal Mail account holders.

of 40

For a multiItemSummary how many items can I enquire on at once? There is currently a limit of 5 items on the getMultiItemSummary. Is there a getMultiItemHistory web service? No – a full history of tracks is only available for a single mail item. Why does a throttling rate error occur? As demand for Tracking API calls is unpredictable it is sometimes necessary to manage the volume of tracking requests hitting the tracking database. The number of requests that you have raised within a period has caused the request to be rejected at this time. Please try again later. Why are scan times sometimes provided as strings such as AM or PM rather than times? This representation of time is a feature of the source scanning system. For international scans, this source scanning system is not controlled by Royal Mail.

Royal Mail, the cruciform, the colour red and all ® are registered trademarks and all ™ are trademarks of Royal Mail Group Ltd. Tracking API Technical User Guide June 2014 © Royal Mail Group Ltd 2014. All rights reserved.

of 40

13 Appendix A – Reference Data 13.1 Technical Errors See section 9.2 for description

Fault code Fault string Fault actor detail

Exception Transaction Id Exception Code Exception Text

Server Internal Error

[Map applicationId from Request]

[Map transactionId from Request]

E0000 Internal Exception Occurred

Server Service Unavailable



E0001 Service Unavailable

Server Service Temporarily Unavailable



E0002 Service Temporarily Unavailable. Please try again later.

Server Unknown Service Error



E0003 Service is unavailable due to an unknown reason. Contact RMG Customer Experience Team.

Client Invalid Request



E0004 Failed Schema Validation

Server Unknown Service Error



E0005 No Response Received from Business Fulfilment System Web Service (Service is Unavailable or Timeout)

Client Authentication Failure



E0006 Authentication Failure

Server Authorisation Failure



E0007 Authorisation Failure

Server Internal Error



E0009 Business Fulfilment System Returned an Error Response

of 40

Fault code Fault string Fault actor detail

Exception Transaction Id Exception Code Exception Text

Server Service Unavailable



E0010 Configured Throttling Rate for Service Exceeded. Please try again later.

13.2 Business Error Codes See section 9.3 for description

Error Code Error Description Error Cause Error Resolution

E1142 Invalid barcode A mail item with that barcode cannot be located

Check barcode and resubmit

E1143 Tracking data not available

It is not possible to provide information about events that occurred more than [configurable variable] days ago

Please use the Royal Mail Track and Trace website to obtain data of this age.

E1144 Proof of Delivery is not available

Proof of Delivery information is not yet available

Please try again later. It can take up to 72 hours after delivery for the Proof of Delivery information to become available

E1145 Proof of Delivery is not available

Proof of Delivery is not available for this product

Please consult your Royal Mail account team to determine which products can be signed for

13.3 Warning Codes There are no warning codes associated with Tracking API.

of 40

14 Appendix B - XML Examples 14.1 getSingleItemHistory Request <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://www.royalmailgroup.com/api/track/V1" xmlns:v11="http://www.royalmailgroup.com/integration/core/V1"> <soapenv:Header/> <soapenv:Body> <v1:getSingleItemHistoryRequest> <v1:integrationHeader> <v11:dateTime>2014-01-06T02:49:45</v11:dateTime> <v11:version>1.0</v11:version> <v11:identification> <v11:applicationId>0123456789</v11:applicationId> <v11:transactionId>12</v11:transactionId> </v11:identification> </v1:integrationHeader> <v1:trackingNumber>FJ111111111GB</v1:trackingNumber> </v1:getSingleItemHistoryRequest> </soapenv:Body> </soapenv:Envelope> Response <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Body> <NS1:getSingleItemHistoryResponse xmlns:NS1="http://www.royalmailgroup.com/api/track/V1"> <NS1:integrationHeader> <NS2:dateTime xmlns:NS2="http://www.royalmailgroup.com/integration/core/V1">2008-09-29T02:49:45</NS2:dateTime> <NS3:version xmlns:NS3="http://www.royalmailgroup.com/integration/core/V1">1</NS3:version> <NS4:identification xmlns:NS4="http://www.royalmailgroup.com/integration/core/V1"> <NS4:dateTime>2014-01-06T02:49:45</NS4:dateTime> <NS4:version>1.0</NS4:version> <NS4:applicationId>0123456789</NS4:applicationId> <NS4:transactionId>12</NS4:transactionId> </NS4:identification> </NS1:integrationHeader> <NS1:trackDetail> <NS1:trackDate>2013-12-26</NS1:trackDate> <NS1:trackPoint>London East Mail Centre</NS1:trackPoint> <NS1:trackTime>14:48:45</NS1:trackTime> <NS1:header>Delivered</NS1:header> <NS1:footer> <NS1:footerID>1024</NS1:footerID> <NS1:footerText>Thank you for using this service</NS1:footerText> </NS1:footer> </NS1:trackDetail> <NS1:integrationFooter>

of 40

<NS7:errors xmlns:NS7="http://www.royalmailgroup.com/integration/core/V1"/> <NS8:warnings xmlns:NS8="http://www.royalmailgroup.com/integration/core/V1"/> </NS1:integrationFooter> </NS1:getSingleItemHistoryResponse> </soapenv:Body> </soapenv:Envelope>

14.2 getSingleItemSummary Request <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://www.royalmailgroup.com/api/track/V1" xmlns:v11="http://www.royalmailgroup.com/integration/core/V1"> <soapenv:Header/> <soapenv:Body> <v1:getSingleItemSummaryRequest> <v1:integrationHeader> <v11:version>1.0</v11:version> <v11:identification> <v11:applicationId>111111113</v11:applicationId> <v11:transactionId>9876543210</v11:transactionId> </v11:identification> </v1:integrationHeader> <v1:trackingNumber>FJ111111111GB</v1:trackingNumber> </v1:getSingleItemSummaryRequest> </soapenv:Body> </soapenv:Envelope> Response <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Body> <NS1:getSingleItemSummaryResponse xmlns:NS1="http://www.royalmailgroup.com/api/track/V1"> <NS1:integrationHeader> <NS3:version xmlns:NS3="http://www.royalmailgroup.com/integration/core/V1">1.0</NS3:version> <NS4:identification xmlns:NS4="http://www.royalmailgroup.com/integration/core/V1"> <NS4:applicationId>111111113</NS4:applicationId> <NS4:transactionId>9876543210</NS4:transactionId> </NS4:identification> </NS1:integrationHeader> <NS1:itemSummary> <NS1:eventDate>2013-12-26</NS1:eventDate> <NS1:eventTime>14:48:00</NS1:eventTime> <NS1:statusCode> <code>EVAPA</code> </NS1:statusCode> <NS1:summaryLine>The sender has advised us that item FJ108115259GB will be posted into the Royal Mail network on the 2013-12-27.</NS1:summaryLine> <NS1:trackingNumber>FJ111111111GB</NS1:trackingNumber> <NS1:header>Please come back later</NS1:header> <NS1:footer/> </NS1:itemSummary>

of 40

<NS1:integrationFooter> <NS7:errors xmlns:NS7="http://www.royalmailgroup.com/integration/core/V1"/> <NS8:warnings xmlns:NS8="http://www.royalmailgroup.com/integration/core/V1"/> </NS1:integrationFooter> </NS1:getSingleItemSummaryResponse> </soapenv:Body> </soapenv:Envelope>

14.3 getProofOfDelivery Request <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://www.royalmailgroup.com/api/track/V1" xmlns:v11="http://www.royalmailgroup.com/integration/core/V1"> <soapenv:Header/> <soapenv:Body> <v1:getProofOfDeliveryRequest> <v1:integrationHeader> <v11:version>1.0</v11:version> <v11:identification> <v11:applicationId>111111113</v11:applicationId> <v11:transactionId>9876543210</v11:transactionId> </v11:identification> </v1:integrationHeader> <v1:trackingNumber>JW034599725GB</v1:trackingNumber> </v1:getProofOfDeliveryRequest> </soapenv:Body> </soapenv:Envelope> Response <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Body> <NS1:getProofOfDeliveryResponse xmlns:NS1="http://www.royalmailgroup.com/api/track/V1"> <NS1:integrationHeader> <NS3:version xmlns:NS3="http://www.royalmailgroup.com/integration/core/V1">1.0</NS3:version> <NS4:identification xmlns:NS4="http://www.royalmailgroup.com/integration/core/V1"> <NS4:endUserId/> <NS4:applicationId>111111103</NS4:applicationId> <NS4:transactionId>9876543210</NS4:transactionId> </NS4:identification> </NS1:integrationHeader> <NS1:integrationFooter> <NS7:errors xmlns:NS7="http://www.royalmailgroup.com/integration/core/V1"> <NS7:error> <NS7:errorCode>E1143</NS7:errorCode> <NS7:errorDescription>Tracking data are not available for barcode reference JW034599725GB</NS7:errorDescription> <NS7:errorCause>It is not possible to provide information about events that occurred more than 300 days ago</NS7:errorCause>

of 40

<NS7:errorResolution>Please use the Royal Mail Track and Trace website to obtain data of this age</NS7:errorResolution> </NS7:error> </NS7:errors> <NS8:warnings xmlns:NS8="http://www.royalmailgroup.com/integration/core/V1"/> </NS1:integrationFooter> </NS1:getProofOfDeliveryResponse> </soapenv:Body> </soapenv:Envelope>

14.4 getMultiItemSummary Request <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:v1="http://www.royalmailgroup.com/api/track/V1" xmlns:v11="http://www.royalmailgroup.com/integration/core/V1"> <soapenv:Header/> <soapenv:Body> <v1:getMultiItemSummaryRequest> <v1:integrationHeader> <v11:dateTime>2013-12-28T02:49:45</v11:dateTime> <v11:version>1.0</v11:version> <v11:identification> <v11:applicationId>111111113</v11:applicationId> <v11:transactionId>9876543210</v11:transactionId> </v11:identification> </v1:integrationHeader> <v1:trackingNumbers> <v1:trackingNumber>FJ111111111GB</v1:trackingNumber> <v1:trackingNumber>JA222222222GB</v1:trackingNumber> <v1:trackingNumber>FJ333333333GB</v1:trackingNumber> <v1:trackingNumber>FJ444444444GB</v1:trackingNumber> <v1:trackingNumber>FL555555555GB</v1:trackingNumber> </v1:trackingNumbers> </v1:getMultiItemSummaryRequest> </soapenv:Body> </soapenv:Envelope> Response <soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"> <soapenv:Body> <NS1:getMultiItemSummaryResponse xmlns:NS1="http://www.royalmailgroup.com/api/track/V1"> <NS1:integrationHeader> <NS2:dateTime xmlns:NS2="http://www.royalmailgroup.com/integration/core/V1">2013-12-28T02:49:45</NS2:dateTime> <NS3:version xmlns:NS3="http://www.royalmailgroup.com/integration/core/V1">1.0</NS3:version> <NS4:identification xmlns:NS4="http://www.royalmailgroup.com/integration/core/V1">

<NS4:applicationId>111111113</NS4:applicationId> <NS4:transactionId>9876543210</NS4:transactionId> </NS4:identification> </NS1:integrationHeader> <NS1:itemSummaries>

of 40

<NS1:itemSummary> <NS1:eventDate>2013-12-20</NS1:eventDate> <NS1:eventTime>12:03:00</NS1:eventTime> <NS1:statusCode> <code>EVKSP</code> </NS1:statusCode> <NS1:summaryLine>We have a record of item FJ111111111GB as being delivered from London East Mail Centre on 2013-12-20.</NS1:summaryLine> <NS1:trackingNumber>FJ111111111GB</NS1:trackingNumber> <NS1:header>Delivered</NS1:header> </NS1:itemSummary> <NS1:itemSummary> <NS1:eventDate>2013-12-20</NS1:eventDate> <NS1:eventTime>11:59:00</NS1:eventTime> <NS1:statusCode> <code>EVKSP</code> </NS1:statusCode> <NS1:summaryLine>We have a record of item JA222222222GB as being delivered from London East Mail Centre on 2013-12-20.</NS1:summaryLine> <NS1:trackingNumber>JA222222222GB</NS1:trackingNumber> <NS1:header>Delivered</NS1:header> </NS1:itemSummary> <NS1:itemSummary> <NS1:eventDate>2013-12-12</NS1:eventDate> <NS1:eventTime>14:48:00</NS1:eventTime> <NS1:statusCode> <code>EVAPA</code> </NS1:statusCode> <NS1:summaryLine>The sender has advised us that item FJ333333333GB will be posted into the Royal Mail network on the 2013-12-29.</NS1:summaryLine> <NS1:trackingNumber>FJ333333333GB</NS1:trackingNumber> <NS1:header>Please come back later</NS1:header> </NS1:itemSummary> <NS1:itemSummary> <NS1:eventDate>2013-12-12</NS1:eventDate> <NS1:eventTime>14:48:00</NS1:eventTime> <NS1:statusCode> <code>EVAPA</code> </NS1:statusCode> <NS1:summaryLine>The sender has advised us that item FJ444444444GB will be posted into the Royal Mail network on the 2013-12-29.</NS1:summaryLine> <NS1:trackingNumber>FJ444444444GB</NS1:trackingNumber> <NS1:header>Please come back later</NS1:header> </NS1:itemSummary> <NS1:itemSummary> <NS1:eventDate>2013-12-12</NS1:eventDate> <NS1:eventTime>14:37:00</NS1:eventTime> <NS1:statusCode> <code>EVAPA</code> </NS1:statusCode> <NS1:summaryLine>The sender has advised us that item FL555555555GB will be posted into the Royal Mail network on the 2013-12-29.</NS1:summaryLine> <NS1:trackingNumber>FL555555555GB</NS1:trackingNumber> <NS1:header>Please come back later</NS1:header> </NS1:itemSummary> </NS1:itemSummaries>

of 40

<NS1:integrationFooter> <NS7:errors xmlns:NS7="http://www.royalmailgroup.com/integration/core/V1"/> <NS8:warnings xmlns:NS8="http://www.royalmailgroup.com/integration/core/V1"/> </NS1:integrationFooter> </NS1:getMultiItemSummaryResponse> </soapenv:Body> </soapenv:Envelope>

of 40

15 Appendix C - Character Set Allowable character set

tracking api technical user guide - royal mail...tracking api technical user guide the api spec t01...

Documents