V1.0 Page 1 of 18 18/05/2018

Key Differences between Royal Mail Shipping API V2 and Royal Mail API Shipping V2

Here is a quick guide to the features and benefits of Royal Mail API Shipping V2 and how they differ

from Shipping API V2.

For customers who are switching from Royal Mail Shipping API V2 to Royal Mail API Shipping V2,

here is a comparison of the features and benefits to help you navigate your switch more easily:

Shipping API V2 (SAPI) Royal Mail API Shipping V2

Creating and updating Passwords for API

Shipping API and DMO Passwords in Onboarding and Production can be created and updated by either you or Royal Mail Admin

Prior to migration into Production environments, you need to have identified your Shipping API Password that is embedded in your API header; and enter it into the relevant Pro Shipping Posting Location/ User as part of your Pro Shipping password resetting within 24 hours of receipt of your account confirmation email from us. The same API Usernames for Production environment are used in API Shipping as you used in Shipping API. This is configured by Royal Mail for you prior to the Account set up Email confirmation being sent to you. You are responsible for creating and updating the API Shipping Password in the relevant Posting Location in Royal Mail Pro Shipping Customer Admin role. If you change your API password in Royal Mail Pro Shipping you will need to update your API calls with the updated password. Please confirm with your API Developer that you have the ability to update your API Password in your system and this will automatically be updated in your API calls.

Updating accounts, services, contracts and Departments

Within DMO, updated Accounts, services and Department references are download automatically every night.

Within API Shipping you need to Refresh Services and Refresh Departments in Royal Mail Pro Shipping Customer Admin role to download initial data and updates from OBA. For Offline Barcoding customers, you will need to complete this task before Royal Mail can configure your Barcode Ranges

V1.0 Page 2 of 18 18/05/2018

Warning Messages

With Shipping API warning messages are provided if there are issues with your API request. Your API request is still processed

With API Shipping there are no warning messages returned in the API responses.

Performance Enhancements

Create Shipment call returns a single label, that then needs a Print Label call to create a shipment label

There are four performance enhancements that can be used, if enabled for API Shipping in the Royal Mail Pro Shipping GUI Customer Admin role: Maintenance> Labels Options (see Appendix for details):

Print Label response data included in the Create Shipment response

Print a Returns Shipment label as well as the Outward service in the Create Shipment response if combined Create Shipment/ Create Print label enabled

Print Customs Document label included in the Create Shipment Response if combined Create Shipment/ Create Print label enabled

Print Manifest document included in the Create Manifest response

Prior to making these changes in your Production API Shipping environment please discuss with your API Developer and also ensure you test these features in the On-boarding API environment as they may cause issues with your API integration.

V1.0 Page 3 of 18 18/05/2018

Let’s look into more detail specifically at the optional Customs Document feature (if enabled in Pro

Shipping:

Shipping API Royal Mail API Shipping

Within Shipping API: • Customs documents (CN22/23 and

Commercial Invoices) are enabled by RM Admin.

• Number of CN22 and CN23 copies are set by user in Admin>Printer settings

• Commercial Invoices are created if enabled in Admin>Printer settings in DMO

• CN23 documents are always created if enabled in Admin>Printer settings, else CN22 if value of goods is less than £270.

• The following fields are used in Customs Documents: exporterContact , exporterAddress, importContact and importAddress

Within Royal Mail API Shipping: • Numbers of CN22/ CN23 copies are

determined by Country destination, not by Shipper

• Commercial Invoices are not created • The following fields are not used in

Customs Documents: exporterContact , exporterAddress, importContact and importAddress

• “Area Code” field needs to be correct for the Country else error returned

• “Purpose of Shipment” field needs to be completed for a shipment even if Average Weight flag is set in Royal Mail Pro Shipping (so resulting in no Manifest creation for the Average Weight services)

Let’s look into more detail specifically at the optional Offline Barcode feature:

Shipping API Royal Mail API Shipping

Within Shipping API: • Request2Dbarcode is required to obtain an

initial range and when it nears expiry, subsequent ranges. Warning message email sent to designated customer email address when Offline barcode range (1D or 2D) nearing expiry

Within Royal Mail API Shipping: • You manage your own 2D barcode

ranges, and do not need to request ranges from API Shipping

• With managing the 2D barcode ranges, you need to ensure that the Unique Sequence number (8 hex characters) is unique per label generated on a specific account number.

• You manage the consumption of the 1D barcode range and subsequent next range request and no expiry warning email is sent to you.

• “offlineShipments” element” must be 13, not 35 characters

• ItemID element is now populated with the full 21 character value included in the 2D barcode referred to as the Channel Specific Segment - Unique Identifier in COSS Spec 03 – Barcodes and Tracking Numbers.

V1.0 Page 4 of 18 18/05/2018

Let’s look specifically at the ‘Daily Shipping Reporting’ process:

Despatch Manager Online Royal Mail Pro Shipping

• To access the daily shipping reporting you visit the End of Day - Manifest listing- and view this on screen or export as a CSV file.

• For Manifest listing - Use Daily Shipping Report in Maintenance screen and export as CSV file. This provides the same export data as DMO plus weight and format as well as being selectable by date.

And finally the ‘Shipment Search Report’ functionality:

Despatch Manager Online Royal Mail Pro Shipping

• There are standard/ customisable templates for generating reports

• All data up to 13 months can be accessed and included in report

• Optional scheduling and email lists for sharing reports

Within Pro Shipping the Shipment Search function allows you to select on: Date, Recipient, Country, Postcode, Post Town, Service, Posting Location, but NOT Tracking barcode number

You can view the report on screen or export

The reports can be run for a maximum time window of 31 days over last 13 months.

V1.0 Page 5 of 18 18/05/2018

Appendix – Optional API Shipping Performance Enhancements

This section shows the API response Screen shots with and without each of the optional

performance enhancements. This shows the additional fields that appear when an option is

enabled in the Pro Shipping Label Options API settings for API Shipping:

1) Create Shipment Response with and without Label data enabled

Create Shipment Request – Label Disabled (so as per Shipping API pre migration):

Soap UI Response:

V1.0 Page 6 of 18 18/05/2018

Create Shipment Request – Label Enabled (Include the Label Image in 'createShipment' response):

SOAP UI Response:

Difference between enabled and disabled:

status\status\statusCode\code - goes from ‘Allocated’ to ‘Printed’

status\Label - Base64 of label

V1.0 Page 7 of 18 18/05/2018

2) Create Manifest Response with and without Manifest document enabled

Create Manifest Request – Disabled (so as per Shipping API pre migration)::

SOAP UI Response:

Create Manifest Request – Enabled (Include the Manifest Image in 'createManifest' response)

V1.0 Page 8 of 18 18/05/2018

SOAP UI Response:

Difference between enabled and disabled:

completedManifestInfo\manifest - Base64 of label

3) Create Shipment Request (Include the Label Image in 'createShipment' response) and also

International Shipment (so include CN documentation CN23 in API response, but no

Commercial Invoice) are enabled

V1.0 Page 9 of 18 18/05/2018

SOAP UI Response:

Here the Label field includes both the Shipment label followed by the CN23 Customs document.

Label Field example:

V1.0 Page 10 of 18 18/05/2018

5) Create Shipment Response with outward shipment label, with and without Returns

shipment label

Return label included for domestic shipments is enabled:

V1.0 Page 11 of 18 18/05/2018

NOTE: outbound and returns are two base64 images.

Return label included for domestic shipments is disabled (as per Shipping API pre migration

V1.0 Page 12 of 18 18/05/2018

SOAP UI Response:

Create Shipment Request – Enabled (Include the Label Image in 'createShipment' response):

V1.0 Page 13 of 18 18/05/2018

SOAP UI Response:

Difference between enabled and disabled:

status\status\statusCode\code - goes from ‘Allocated’ to ‘Printed’ Return label included for

domestic shipments is enabled

status\Label - Base64 of label

4) Create Manifest response with and without Manifest document enabled

Create Manifest Request – Disabled:

V1.0 Page 14 of 18 18/05/2018

SOAP UI Response:

Create Manifest Request – Enabled (Include the Manifest Image in 'createManifest' response)

SOAP UI Response:

Difference between enabled and disabled:

completedManifestInfo\manifest - Base64 of label

V1.0 Page 15 of 18 18/05/2018

5) Create Shipment Request (Include the Label Image in 'createShipment' response) and

International Shipment (Include CN documentation in API response) are enabled

SOAP UI Response:

V1.0 Page 16 of 18 18/05/2018

Label:

V1.0 Page 17 of 18 18/05/2018

Return label included for domestic shipments is enabled:

NOTE: outbound and returns are two base64 images.

V1.0 Page 18 of 18 18/05/2018

Royal Mail, the cruciform, the colour red and all ® are registered trademarks and all ™ are

trademarks of Royal Mail Group Ltd. Royal Mail API Shipping_V2_ differences to Shipping API V2_

v1.0 18 May 2018 © Royal Mail Group Ltd 2018. All rights reserved.