UK National Tobacco Track Trace Gateway Technical Specification

UK National Tobacco
Track & Trace

Gateway
Technical
Specification
18/12/20
© De La Rue International Limited 2020
CONFIDENTIAL
Preface Contact information
This document is not a statement of In the case of questions, comments
work nor is it a customer sales contract. or requests for clarification regarding
Any proposal issued to the customer will this document, please contact:
be subject to De La Rue’s standard
terms and conditions unless otherwise
agreed in writing. De La Rue International Limited
De La Rue House, Viables, Jays Close,
Basingstoke, RG22 4BS, United
Copyright Kingdom
The copyright in this work is vested in
De La Rue International Limited or Or
De La Rue Authentication Solutions,
hereinafter called De La Rue, and the De La Rue Authentication Solutions
document is issued for the purpose only 1750 N 800 W, LOGAN, UT 84321,
for which it is supplied. It shall not be United States
reproduced in whole or in part or used
for any tendering or manufacturing
purposes except under an agreement
and with the consent in writing of De La Document information
Rue, and then only on the condition that
this notice is included in any such
reproduction. All data provided and all Customer ref:
designs remain the property of De La HMRCGatewayTechSpec1.64
Rue.
No information as to the contents or Submission date:

subject matter of this document or any 18 December 2020
part thereof arising directly or indirectly
therefore shall be given orally or in
writing or communicated in any manner
whatsoever to any third party being an
individual firm or company or any
employee thereof without the prior
consent in writing of De La Rue.
©De La Rue International Limited 2020,

all rights reserved.
Trademarks
De La Rue and the Founder’s Head
device are trademarks of De La Rue
Holdings Limited. All other names and
terms used in this document may be
trademarks belonging to De La Rue’s
licensors or third parties.
02
CONFIDENTIAL
Contents
1. Introduction ......................................................................................................... 6
1.1. Purpose of the document .................................................................................. 6
1.2. Audience .......................................................................................................... 6
1.3. Definitions of terms and abbreviations ............................................................... 6
2. General ............................................................................................................... 7
2.1. Data transmission to the UK National Gateway .................................................. 7
2.2. Data requests to UK UID Issuer ......................................................................... 8
2.3. Access Mechanism ........................................................................................... 8
2.3.1. Authorization ................................................................................................. 8
2.3.1.1. Retry Mechanism...................................................................................... 11
2.4. Recall code ..................................................................................................... 11
2.5. Data Types ..................................................................................................... 11
2.6. Authorized formats (long / short) for UIDs ........................................................ 13
3. XML messages ................................................................................................. 14
3.1.1. Formats ....................................................................................................... 14
3.1.2. HTTP Header............................................................................................... 14
3.1.3. Message Header ......................................................................................... 15
3.1.4. Message Body ............................................................................................. 15
3.1.4.1. Common fields ......................................................................................... 16
3.1.5. Response details ......................................................................................... 16
3.1.5.1. HTTP code 200 ........................................................................................ 16
3.1.5.2. HTTP code 299 ........................................................................................ 16
3.1.5.3. HTTP code 400 ........................................................................................ 17
3.1.5.4. HTTP code 401 ........................................................................................ 19
3.1.5.5. HTTP code 500 ........................................................................................ 20
3.2. Message Content ........................................................................................... 20
3.2.1. Message 2.3................................................................................................ 20
03
CONFIDENTIAL
3.2.2. Message 3.0................................................................................................ 23
3.2.3. Message 3.1................................................................................................ 24
3.2.4. Message 3.2................................................................................................ 25
3.2.5. Message 3.3................................................................................................ 27
3.2.6. Message 3.4................................................................................................ 30
3.2.7. Message 3.5................................................................................................ 32
3.2.8. Message 3.6................................................................................................ 35
3.2.9. Message 3.7................................................................................................ 36
3.2.10. Message 4.1 ............................................................................................ 37
3.2.11. Message 4.2 ............................................................................................ 40
3.2.12. Message 4.3 ............................................................................................ 42
3.2.13. Message 5 ............................................................................................... 45
4. JSON messages ............................................................................................... 46
4.1. Message Structure.......................................................................................... 46
4.1.1. Formats ....................................................................................................... 46
4.1.2. HTTP Header............................................................................................... 46
4.1.3. Message Type ............................................................................................. 46
4.1.4. Message Body ............................................................................................. 47
4.1.5. Response details ......................................................................................... 47
4.1.5.1. Basic information block concerning the response ...................................... 47
4.1.5.2. Basic error block description .................................................................... 48
4.1.5.3. Common codes ........................................................................................ 49
Success code ........................................................................................................... 49
Error codes ............................................................................................................... 49
4.2. Message Content............................................................................................ 51
4.2.1. Message IRU ............................................................................................... 51
4.2.2. Message IRA ............................................................................................... 54
4.2.3. Message 2.3 (IDA)....................................................................................... 56
4.2.4. Message 3.0................................................................................................ 57
04
CONFIDENTIAL
4.2.5. Message 3.1................................................................................................ 58
4.2.6. Message 3.2................................................................................................ 59
4.2.7. Message 3.3................................................................................................ 60
4.2.8. Message 3.4................................................................................................ 61
4.2.9. Message 3.5................................................................................................ 62
4.2.10. Message 3.6 ............................................................................................ 63
4.2.11. Message 3.7 ............................................................................................ 63
4.2.12. Message 4.1 ............................................................................................ 64
4.2.13. Message 4.2 ............................................................................................ 65
4.2.14. Message 4.3 ............................................................................................ 65
4.2.15. Message 5 ............................................................................................... 66
5. Message Validation ........................................................................................... 67
05
CONFIDENTIAL
1. Introduction
1.1. Purpose of the document
The purpose of this document is to describe the different interfaces provided by
the UK National Tobacco Track and Trace Gateway (UK National Gateway) to all
economic operators.
This document doesn’t describe internal technical details, and communications

between components of the UK National Track and Trace ecosystem.
1.2. Audience
The audience of this document is everyone who needs to implement messages
to be sent to the UK National Gateway.
1.3. Definitions of terms and abbreviations
Definitions will be the same as, or very similar to, those described in Article 2 of
the Tobacco Products Directive 2014/40/EU and in Article 2 and 3 of the
Commission Implementing Regulation (EU) 2018/574. They are classified in
alphabetical order.
Aggregated packaging is any packaging containing more than one Unit packet
of tobacco products.
Data carrier is a means of representing data in machine readable form.
Economic operators are any natural or legal person who is involved in the trade
of tobacco products, including for export, from the manufacturer to the last
economic operator before the first retail outlet. This includes, but is not limited
to, manufacturers, importers, wholesalers and distributors, as well as transport
companies or providers of courier services.
Facility is any location, building or vending machine where tobacco products are
manufactured, stored, or placed on the market.
First retail outlet is the Facility where tobacco products are placed on the market
for the first time, including vending machines used for the sale of tobacco
products.
ID Issuer is an entity responsible for generating and issuing the Unique identifier
(UI) for Unit packet and Aggregated packaging of tobacco products.
06
CONFIDENTIAL
Importer of tobacco or related products is the owner of, or a person having the
right of disposal over, tobacco or related products that have been brought into
the territory of the Union.
Machine is the equipment used for the manufacture of tobacco products which
is integral to the manufacturing process.
Manufacturer is any natural or legal person who manufactures a product or has

a product designed or manufactured and markets that product under their name
or trademark.
Offline flat-files are the electronic files established and maintained by each ID
Issuer that contains data in a plain text format allowing for the extraction of the
information encoded in the Unique identifier (UI) (excluding the time stamp) used
at the Unit packet and Aggregated packaging levels without accessing the
Repositories system.
Registry means the record established and maintained by each ID Issuer of all
the Identifier codes generated for Economic operators, Operators of first retail
outlets, Facilities and Machines, along with the corresponding information.
Retail outlet is any outlet where tobacco products are placed on the market,
including by a natural person.
Trans-loading is any transfer of tobacco products from one vehicle to another

during which tobacco products do not enter and exit a Facility.
Unique identifier (UI or UID) is the alphanumeric code enabling the identification
of a Unit packet (upUI) or an Aggregated packaging (aUI) of tobacco product.
Unit packet is the smallest individual packaging of a tobacco or related product

that is placed in the market.
Vending van is a vehicle used for the delivery of tobacco products to multiple
retail outlets in quantities that have not been predetermined in advance of the
delivery.
2. General
2.1. Data transmission to the UK National Gateway
All economic operators are subject to send messages to the UK National
Gateway using:
07
CONFIDENTIAL
- either XML messages as described in section 3
- either JSON messages as described in section 4
2.2. Data requests to UK UID Issuer

Economic operators must send messages to the UK UID Issuer as described by
the UID Issuer (out of scope of this document).
2.3. Access Mechanism

All connections to the UK National Gateway are secured by HTTPS TLS 1.2. All
interfaces are standard REST interfaces.
2.3.1. Authorization
The authorization mechanism used in the solution is based on the industry-
standard OAuth 2.0 (https://oauth.net/2/).
OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0

supersedes the work done on the original OAuth protocol created in 2006.
OAuth 2.0 focuses on client developer simplicity while providing specific
authorization flows for web applications, desktop applications, mobile phones,
and living room devices.
In this chapter, we will highlight the two authentication and authorization

processes used to connect to UK Gateway applications.
For Technical Users

This first authentication method mainly concerns users of "service" type, referred
to in this document as technical users.
08
CONFIDENTIAL
Example:
Technical User (Service Account) requests for an authentication token from the
Worldline Authentication Provider as follow:
curl -d "client_id=<CLIENT_ID>" \ -d "client_secret=<CLIENT_SECRET>" \

-d "grant_type=client_credentials" \
"http://<URL_OAUTH_PROVIDER>/auth/realms/<REALM>/protocol/openidconn
ect/token"
Note: CLIENT_ID, CLIENT_SECRET, URL_OAUTH_PROVIDER and REALM are

provided by Worldline and are strictly personal.
The Worldline Authentication Provider answers as follow:
{
"access_token": "<BEARER_TOKEN>",
"expires_in": 300,
"refresh_expires_in": 1800,
"refresh_token": "<REFRESH_TOKEN>",
"token_type": "bearer"
}
Once received, copy the value of BEARER_TOKEN and make your call to the
Worldline API Gateway as follow:
curl -H "Authorization: Bearer <BEARER_TOKEN>" \

"http://<URL_GATEWAY>/call"
Note: Your BEARER_TOKEN is available only during the “expire_in” duration (in
seconds). Once expired, you will have to ask for another token.
Refresh Token
Use of the refresh token is optional as the Gateway does not provide a user
interface externally and does not maintain state between calls. However, a
refresh token is included with the authentication response and this can be used
when a new access token is required, if desired. The caller may make a POST
request to the Worldline Authentication Provider using a grant_type of
refresh_token along with the refresh token, the CLIENT_ID and the
CLIENT_SECRET.
09
CONFIDENTIAL
For Human Users (only applicable for authorized users)
This second authentication method mainly concerns human users requesting

access to the web GUI through a web browser.
10
CONFIDENTIAL
2.3.1.1. Retry Mechanism
All client systems of the solution must implement a retry-mechanism feature in
order to ensure a smooth integration.
The following figure shows a typical retry-mechanism process.
2.4. Recall code

The UK National Gateway responses must contain a unique identifier, called
recall_code, which can be used for the recall functionality.
This recall code follows the following format: EOID-UUID (Economic operator id
followed by a universally unique identifier).
Here is an example of recall_code: AWL0001-c1df56cf-b802-426b-8cbe-

6b8177ded4b5
2.5. Data Types
Data Type
Description Example
Administrative Reference Code (ARC) or any

ARC successive code adopted under the Excise '15GB0123456789ABCDEF0'
Movement and Control System (EMCS)
Aggregated level unique identifier coded with the
aUI invariant set of ISO646:1991 Max length: 100
'0' (false/disabled)
Boolean Boolean value
'1' (true/enabled)
11
CONFIDENTIAL
Country name coded with ISO-3166-1:2013 alpha-
Country 'DE'
2 (or its latest equivalent).
Currency name coded with ISO 4217:2015 (or its
Currency 'GBP'
latest equivalent)
UTC (Coordinated Universal Time) date
Date corresponding to the following format: YYYY-MM- '2019-05-20'
DD
Decimal Number values, decimal allowed '1' or '2.2' or '3.33'
Economic operator identifier code corresponding to

EOID the format established by the ID issuer coded with
the invariant set of ISO646:1991
Tobacco facility identifier code corresponding to the
FID format established by the ID issuer coded with the
invariant set of ISO646:1991
Integer Rounded number values, no decimal numbers '1' or '22' or '333'
Machine identifier code corresponding to the format

MID established by the ID issuer coded with the invariant
set of ISO646:1991
Movement Reference Number (MRN) is a unique
customs registration number. It contains 18 digits
and is composed of the following elements:
last two digits of the year of formal acceptance of
export movement (YY),
MRN country name coded with ISO-3166-1:2013 '11IT9876AB88901235'
alpha-2 (or its latest equivalent) of the country to
which the declaration was sent,
unique identifier for entry/import per year and
country, and check digit.
Excise number composed of:

(a) country name coded with ISO-3166-1:2013
SEED alpha-2 (or its latest equivalent) (e.g. 'LU') and (b) 'LU00000987ABC'
eleven alphanumeric characters, if needed, padded
to the left with zeroes (e.g. '00000987ABC').
Individual transport unit code (e.g. SSCC)
ITU generated in accordance with ISO15459-1:2014 '001234560000000018'
(or its latest equivalent)
Text Alphanumeric values coded with ISO8859-15:1999 'abcde12345'
UTC (Coordinated Universal Time) in the following

Time(L) '2019-07-16T19:20:30Z'
format: YYYY-MM-DDThh:mm:ssZ
UTC (Coordinated Universal Time) in the following
Time(s) '19071619'
format: YYMMDDhh
Tobacco Product Identifier (TP-ID) – numeric
TPID identifier '02565-16-00230'
CEG system in the format: NNNNN-NN-NNNNN
Product number – numeric identifier used to identify

product presentations (e.g. GTIN (Global Trade
PN '00012345600012'
Identification Number) of the product)
12
CONFIDENTIAL
Unit packet level unique identifier coded with the
invariant set of ISO646:1991 and composed of
three blocks: LECNIzzzz000010000SLE20070218
ID Issuer's prefix in accordance with
upUI(L) ISO154592:2015, middle block in the format
established by the ID issuer and timestamp
following the Data Type: Time(s) Max length: 50
Unit packet level unique identifier coded with the

invariant set of ISO646:1991 and composed of two LECNIzzzz00001
blocks:
ID issuer's prefix in accordance with ISO15459-
upUI(s)
2:2015 and serialisation element in the format
established by the ID issuer (i.e. UI made visible in
the human readable format on the unit packets)
upUI(M) Unit packet level unique identifier coded with the

invariant set of ISO646:1991 and composed of 2
blocks: ID Issuer's prefix in accordance with
ISO154592:2015, middle block in the format LECNIzzzz000010000SLE
established by the ID issuer
UTC (Coordinated Universal Time) year in the
Year '2024
following format: YYYY
2.6. Authorized formats (long / short) for UIDs

The following table provides a list of supported upUI formats – any changes in
the code structure imposed by a competent ID Issuer must require modifications
in this list.
Long format Short Format

(^LEAT1.{8})(.*)([0-9]{8})$ (^LEAT1.{8})
(^QCLUXX.{12})(.*)([0-9]{8})$ (^QCLUXX.{12})
(^LEBGR.{9})(.*)([0-9]{8})$ (^LEBGR.{9})
(^LEAKD.{11})(.*)([0-9]{8})$ (^LEAKD.{11})
(^LEGR1.{9})(.*)([0-9]{8})$ (^LEGR1.{9})
(^LESTC.{9})(.*)([0-9]{8})$ (^LESTC.{9})
(^LEWL2.{8})(.*)([0-9]{8})$ (^LEWL2.{8})
(^QCALL.{9})(.*)([0-9]{8})$ (^QCALL.{9})
(^KPL2F.{9})(.*)([0-9]{8})$ (^KPL2F.{9})
(^QCBDR.{10})(.*)([0-9]{8})$ (^QCBDR.{10})
(^LEDTC.{9})(.*)([0-9]{8})$ (^LEDTC.{9})
(^QCSGSE.{11})(.*)([0-9]{8})$ (^QCSGSE.{11})
(^LX.{9})(.*)([0-9]{8})$ (^LX.{9})
(^LEHU1.{9})(.*)([0-9]{8})$ (^LEHU1.{9})
(^LERTC.{7})(.*)([0-9]{8})$ (^LERTC.{7})
(^KLTT.{9})(.*)([0-9]{8})$ (^KLTT.{9})
(^WAA0.{11})(.*)([0-9]{8})$ (^WAA0.{11})
(^LEWL1.{8})(.*)([0-9]{8})$ (^LEWL1.{8})
13
CONFIDENTIAL
(^KPL1.{9})(.*)([0-9]{8})$ (^KPL1.{9})
(^PWPS.{9})(.*)([0-9]{8})$ (^PWPS.{9})
(^LEITA.{8})(.*)([0-9]{8})$ (^LEITA.{8})
(^LECNI.{9})(.*)$ (^LECNI.{9})
(^3P.{13})(.{14})([0-9]{8})$ (^3P.{13})
(^3P.{14})(.{14})([0-9]{8})$ (^3P.{14})
(^3P.{13})([0-9]{8})$ (^3P.{13})
(^20.{13})(.{14})([0-9]{8})$ (^20.{13})
(^20.{14})(.{14})([0-9]{8})$ (^20.{14})
(^1E.{13})(.{14})([0-9]{8})$ (^1E.{13})
(^1E.{14})(.{14})([0-9]{8})$ (^1E.{14})
(^QCGDLR.{10})(.{4})([0-9]{8})$ (^QCGDLR.{10})
(^QCGDLR.{9})(.*)([0-9]{8})$ (^QCGDLR.{9})
3. XML messages
3.1. Message Structure
For each message, the structure has been maintained to match the current EU
TPD structure to ensure compatibility. All elements used inside the message are
described by; the column ‘Priority’ specifies if this element is required (M) or
optional (O); the column ‘Cardinality’ specifies if this element is a single-value
element (S) or a multiple-value elements (M).
Endpoint for message submission: /v1/gateway/ext/event

HTTP Method: POST
3.1.1. Formats
All XML messages have the following structure:
<TPDMessage>
<Header>
…
</Header>
<Body>
…
</Body>
</TPDMessage>
3.1.2. HTTP Header
Field Data Cardinality Priority Values

Type
Content-Type string S M text/xml
Authorization string S M Bearer {{access_token}}
14
CONFIDENTIAL
{{access_token}} refers to access_token value provided in the response of the
authentication request (see 2.3 - Access Mechanism for additional details)
3.1.3. Message Header

The message header contains global information regarding the complete
message.
List of fields:

Type
Message_Signature String S M For further usage.
Must contain:
<Message_Signature></Message_Signature>
Example:
<TPDMessage>
<Header>
<Message_Signature></Message_Signature>
</Header>
3.1.4. Message Body

The Message Body contains one (and only one) message to be transferred to
the UK National Gateway
Tag Description
Message_23 Message 2.3 – Deactivation of UIs
Message_30 Message Pairing
Message_31 Message 3.1 – Commissioning
Message_32 Message 3.2 – Aggregation
Message_33 Message 3.3 – Shipment
Message_34 Message 3.4 – Arrival
Message_35 Message 3.5 – Transloading
Message_36 Message 3.6 – disaggregation
Message_37 Message 3.7 – Delivery to Retail Outlet
Message_41 Message 4.1 – Invoice
Message_42 Message 4.2 - Order
Message_43 Message 4.3 – Payment
Message_5 Message 5 – Recall
15
CONFIDENTIAL
3.1.4.1. Common fields
Field Value Priority Comment / Example

Message_ID Unique identifier M Identifier provided by the sender
of the message must be unique. Sender may
resend the same message using
the same message_ID in case of
acknowledge has not been
received by the sender
3.1.5. Response details

Here are described all HTTP response codes returned by the XML message
submission endpoint.
3.1.5.1. HTTP code 200

Success: The submitted message has been accepted by the UK Gateway.
Field Comments Data Cardinality Priority Values

Type
recall_code The unique ID String S M for messages

generated by the of type 3.x or
UK Gateway that type 4.x
can be used for the
recall functionality
Example:
{
"recall_code": "AWL0001-c1df56cf-b802-426b-8cbe-6b8177ded4b5"
}
3.1.5.2. HTTP code 299

Success: The submitted message has been accepted on the UK National
Gateway, but a warning is raised.
16
CONFIDENTIAL
Type
recall_code The unique ID String S M for
generated by the messages
UK Gateway that of type 3.x
can be used for or type
the recall 4.x
functionality
path The path of the String S M
URI on which the
error occurs
code The HTTP integer( S M
response status $int32)
returned
date The UTC date String S M
time when the
error occurs
warnings List M M
reason The reason of string S M
why the error
has been raised
code string S M SHIPMENT_WITHIN_24_HOURS
OPERATION_WITHIN_24_HOURS
RETRY_SUCCESSFULL
Example:
{
"code": 299,
"path": "/v1/gateway/ext/event",
"date": "2020-12-06T16:45:07.782Z",
"warnings": [
{
"reason": “Message ID of previous rejected messages",
"code": "RETRY_SUCCESSFULL"
}
],
"recall_code": "AWL0001-c1df56cf-b802-426b-8cbe-6b8177ded4b5"
}
3.1.5.3. HTTP code 400
17
CONFIDENTIAL
Bad request: The submitted document is not valid or the message contains
invalid data.
Field Comments Data Type Cardinality Priority Values

URI on which
the error
occurs
code The HTTP integer( S M
response $int32)
status returned

time when the
error occurs
errors List M M
reason The reason of string S M

why the error
has been
raised
code string S M INVALID_REQUEST_FORMAT
INVALID_MESSAGE_TYPE
INVALID_INPUT_FORMAT
REQUIRED_FIELD_FAILED_VALIDATION
MULTIPLE_UID
UI_NOT_VALID
UI_NOT_EXIST
UI_EXPIRED
MAX_LENGTH_FAILED_VALIDATION
REQUIRED_FIELD_FAILED_VALIDATION
NON_COMPATIBLE_UIS
NOT_THE_SAME_NUMBER_OF_ITEMS
UI_DEACTIVATED
CLAIM_VALIDATION_FAILED
CODE_NOT_EXIST
MULTIPLE_AGGREGATION
UIS_APPLICATION_ERROR
LOCATION_MISMATCH OUT_OF_SEQUENCE
UI_SEQUENCE_ERROR
ARRIVAL_NOTALLOWED
MESSAGE_ALREADY_RECEIVED if there is
another error 400 in the same event
RETRY_SUCCESSFULL
Example:
{
"code": 400,
18
CONFIDENTIAL
"date": "2018-12-06T16:45:07.782Z",
"errors": [
{
"reason": "#: required key [UKMessage] not found",
"code": "INVALID_REQUEST_FORMAT"
},
{
"reason": "[CCQA10000UID2412546546,
CCQA10000UID2514521458]",
"code": "UI_NOT_VALID"
},
{
"reason": "[CCQA10000UID2412546547,
CCCCQA10000UID2514521459]",
"code": "UI_EXPIRED"
}
]
}
3.1.5.4. HTTP code 401

Unauthorized: the token is invalid or expired
path The path of String S M

the URI on
which the
error occurs
code The HTTP integer($int32 S M
response )
status
returned
date The UTC String S M
date time
when the
error occurs
errors List M M
code string S M SECURITY_INVALID_OR_EXPIRED_TOKEN
19
CONFIDENTIAL
Example:
{
"code": 401,
"date": "2019-03-12T15:57:54.516Z",
"errors": [
{
"code": " SECURITY_INVALID_OR_EXPIRED_TOKEN "
}
]
}
3.1.5.5. HTTP code 500

If an unexpected exception occurs on server side.

URI on which
the error occurs
code The HTTP integer($int32) S M

response status
returned

time when the
error occurs
errors List M M
code string S M INTERNAL_SERVER_ERROR
3.2. Message Content

3.2.1. Message 2.3
Destruction of products or aggregation of products.
Message_ID see 3.1.4.1
Time of event occurrence

Event_Time Time(s) S M
The time that the message

Message_Time_Long is first submitted to the Time(L) S M
Gateway, Long format.
EO_ID Economic operator EOID S M
identifier code of the
submitting entity
20
CONFIDENTIAL
Deact_Type Deactivation of unit packet Integer S M 1 Unit packet level UIs
or 2 Aggregated level UIs
aggregated level UIs
Deact_Reason1 Identification of the reason Integer S M 1 Product destroyed
for deactivation 2 Product stolen
3 UI destroyed
4 UI stolen
5 UI unused
6 Other
Deact_Reason2 Description of other reason Text S M, if
Deact_Rea
son1=
6
Deact_Reason3 Additional description of Text S O
the reason
Deact_upUI List of unit packet level UIs upUI(s) M M, if
to be deactivated Deact_Typ
e=1
Deact_aUI List of aggregated level UIs aUI M M, if
to be deactivated Deact_Typ
e=2
Additional technical message validations:

None
Remark:
UIDs specified in “Deact_upUI” are human-readable codes (not machine-
readable codes generated by ID Issuers)
Example (XML):
<TPDMessage>
<Body>
<Message_23>
<Message_ID>AAAAA11123</Message_ID>
<Event_Time>18062210</Event_Time>
<Message_Time_Long>2020-03-
31T23:16:45Z</Message_Time_Long>
<EO_ID>AWL0001</EO_ID>
21
CONFIDENTIAL
<Deact_Type>2</Deact_Type>
<Deact_Reason1>6</Deact_Reason1>
<Deact_Reason2>Someone did a mistake</Deact_Reason2>
<Deact_Reason3>We do not know who</Deact_Reason3>
<Deact_aUI>
<aUI>AWLvnaOzT29Q18063008</aUI>
<aUI>AWLXHTtio71j18063008</aUI>
</Deact_aUI>
</Message_23>
</Body>
</TPDMessage>
<TPDMessage>
<Body>
<Message_23>
<Deact_Type>1</Deact_Type>
<Deact_Reason1>6</Deact_Reason1>
<Deact_Reason2>Someone did a mistake</Deact_Reason2>
<Deact_Reason3>We do not know who</Deact_Reason3>
<Deact_upUI>
<upID>AWLvnaOzT29z18063008</upID>
<upID>AWLXHTtio71t18063008</upID>
</Deact_upUI>
</Message_23>
</Body>
</TPDMessage>
22
CONFIDENTIAL
3.2.2. Message 3.0
Pairing between printed codes and virtual paired codes

Type
EO_ID Economic operator identifier code of the EOID S M

submitting entity
Message_Time_Long The time that the message is first submitted to Time(L) S M

the Gateway, Long format.
Event_Time Time of event occurrence Time(s) S M
upUI List of paired codes S M
upID Code pairing detail M M
Printed_Code Unit packet level UID printed on packs upUI(L) S M
Paired_Code Paired UID upUI(M) S M
Example (XML):
<TPDMessage>
<Body>
<Message_30>
<Message_Time_Long>2020-03-31T23:16:45Z</Message_Time_Long>
<upUI>
<upID>
<Printed_Code>LECNIzzzz000010000SLE2020073010</Printed_Code>
<Paired_Code>QCGDLRabcd000010000UK</Paired_Code>
</upID>
<upID>
</upID>
<upID>
</upID>
23
CONFIDENTIAL
</upUI>
</Message_30>
</Body>
</TPDMessage>
3.2.3. Message 3.1

UIDs are printed on products.
Field Comments Data Type Cardin ality Priority Values
The time that the message is first

Message_Time_Long submitted to the Gateway, Long Time(L) S M
format.
EO_ID Economic operator identifier code of EOID S M
the submitting entity
F_ID Facility identifier code FID S M
upUI_1 List of unit packet level UIs to be upUI(L) M M

recorded (full length)
upUI_2 List of corresponding unit packet level upUI(s) M M
UIs to be recorded (as visible in human
readable format) indicated in the same
order as upUI_1
upUI_comment Comments by the reporting entity Text S O
Technical message validations:

1. Number of elements in list upUI_1 = Number of elements in list upUI_2
Remarks:
- Maximum: 10000 upUI_1 per message
Example:
<TPDMessage>
<Body>
<Message_31>
<F_ID>AWL1001</F_ID>
<upUI_1>
24
CONFIDENTIAL
<upID>AWLvnaOzT29QL9UM2018063008</upID>
<upID>AWLXHTtio71jL9UM2018063008</upID>
</upUI_1>
<upUI_2>
<upID>AWLvnaOzT29Q</upID>
<upID>AWLXHTtio71j</upID>
</upUI_2>
<upUI_comment>Something</upUI_comment>
</Message_31>
</Body>
</TPDMessage>
3.2.4. Message 3.2
Message used to report aggregation between children and parent.
Data Type Cardinality

Field Comments Priority Values
Economic operator identifier code

EO_ID EOID S M
of the submitting entity
Message_Time_Long The time that the message is first Time(L) S M
submitted to the Gateway, Long
format.
aUI Aggregated level UI aUI S M
1 aggregation of only
unit packet level UIs
2 aggregation of only
3 aggregation of both
Aggregation_Type Identification of aggregation type Integer S M
unit packet and
List of unit packet level UIs subject M, if

to aggregation Aggregatio
Aggregated_UIs1 upUI(L) M
n_Ty pe =
1 or 3
List of aggregated level UIs subject M, if
to further aggregation Aggregatio
Aggregated_UIs2 aUI M
n_Ty pe =
2 or 3
aUI_comment Comments by the reporting entity Text S O

N/A
25
CONFIDENTIAL
Example:
<TPDMessage>
<Body>
<Message_32>
<aUI>01326884000100821WAJPW9KP2MGG</aUI>
<Aggregation_Type>3</Aggregation_Type>
<Aggregated_UIs1>
</Aggregated_UIs1>
<Aggregated_UIs2>
</Aggregated_UIs2>
<aUI_comment>A Comment</aUI_comment>
</Message_32>
</Body>
</TPDMessage>
26
CONFIDENTIAL
3.2.5. Message 3.3
Dispatch of tobacco products from a facility
Field Comments Data Type Cardinality Prio Values

submitting entity
Event_Time Intended time of event Time(s) S M
occurrence
Message_Time_Long The time that the Time(L) S M
message is first submitted
to the Gateway, Long
format.
F_ID Dispatch facility identifier FID S M
code
Destination_ID1 Indication of destination Integer S M 1. Non UK dest.
type: if the destination 2. UK destination other than
facility is located on the VM – fixed quantity
UK territory and if it is delivery
delivery to a vending 3. UK VM(s)
machine (VM) or by 4. UK destination other than
means of a vending van
VM – delivery with VV
(VV) delivering to multiple
retail outlets in quantities
that
have not been
predetermined in advance
of the delivery
Destination_ID2 Destination facility FID S M, if

identifier code Destination_ID
1=2
Destination_ID3 Destination facility FID M M, if
identifier code(s) – Destination_ID
possible multiple vending 1=3
machines
Destination_ID4 Destination facility List of FID M M, if Example :
identifier code(s) Destination_ID <Destination_ID4>
1=4 <F_ID>LECNI505787</F_I
D>
<F_ID>LECNI505788</F_I
D>
</Destination_ID4>
Destination_ID5 Destination facility's full Text S M, if
address: street, house Destination_ID
number, postal code, city 1=1
27
CONFIDENTIAL
Destination_ID5_A Text O
ddress_Name
Destination_ID5_A Text M, if
ddress_StreetOne Destination_ID
1 =1
ddress_StreetTwo
Destination_ID5_A Text M, if
ddress_City Destination_ID
1 =1
ddress_PostCode
Transport_mode Mode of transport by Integer S M 0 Other
which the product leaves 1 Sea Transport
the facility. 2 Rail transport
3 Road transport
4 Air transport
5 Postal consignment
6 Fixed transport
installations
7 Inland waterway transport
Transport_vehicle Identification of the vehicle Text S M 'n/a' is

(i.e. number plates, train permitted value if
number, plane/flight Transport_mode = 0
number, ship and product
name or movement takes place
other identification) between adjacent
facilities and is delivered
manually
Transport_cont1 Indication if the transport Boolean S M – No

is – Yes
containerised and uses an
individual transport unit
code (e.g. SSCC)
Transport_cont2 Individual transport unit ITU S M, if
code of the container Transport
_cont1=1
Transport_s1 Indication if the dispatch Boolean S M – No
takes place with the – Yes
logistic/postal operator
who operates its own
track and trace system
accepted by the country
of the dispatch facility.
Only for small quantities of
tobacco products (net
weight of the products
dispatched below 10kg)
destined for exports to
third countries
28
CONFIDENTIAL
Transport_s2 The logistic operator's Text S M, if
tracking number Transport
_s1=1
EMCS Dispatch under the Excise Boolean S M 0 No
Movement and Control 1 Yes
System (EMCS)
EMCS_ARC Administrative Reference ARC S M, if
Code (ARC) EMCS = 1
SAAD Dispatch with a simplified Boolean S M 0 No
accompanying 1 Yes
document.
SAAD_number Reference number of the Text S M, if

declaration and/or SAAD = 1
authorization which has to
be given by the competent
authority in the country of
destination before the
movement starts
Exp_Declaration Indication if the Boolean S M 0 No

Movement Reference 1 Yes
Number (MRN) has been
issued by the customs
office
Exp_DeclarationNu Movement Reference MRN S M, if
mber Number (MRN) Exp_Declaration
=1
UI_Type Identification of UI types in Integer S M 1 only unit packet

the dispatch level UIs
(recorded at the highest 2 only aggregated
level of level UIs 3 both unit packet
available aggregation) and aggregated level UIs
upUIs List of unit packet level upUI(L) M M, if
UIs subject to the dispatch UI_Type
= 1 or 3
aUIs List of aggregated level aUI M M, if
UIs subject to the dispatch UI_Type
= 2 or 3
Dispatch_comment Comments by the Text S O
reporting entity

N/A
Example:
29
CONFIDENTIAL
Shipping of 2 master cases from F_ID AWL1001 to F_ID AWL2001 by the truck
with plate number NCH618.
<TPDMessage>
<Body>
<Message_33>
<Destination_ID1>2</Destination_ID1>
<Destination_ID2>AWL2001</Destination_ID2>
<Transport_mode>3</Transport_mode>
<Transport_vehicle>NCH618</Transport_vehicle>
<Transport_cont1>0</Transport_cont1>
<Transport_s1>0</Transport_s1>
<EMCS>0</EMCS>
<SAAD>0</SAAD>
<Exp_Declaration>0</Exp_Declaration>
<UI_Type>2</UI_Type>
<aUIs>
<aUI>01326884000100821WAJPW9KP2MGG18063008</aUI>
<aUI>01326884000100821PX0WAJA0GKP218063008</aUI>
</aUIs>
<Dispatch_comment>Comment</Dispatch_comment>
</Message_33>
</Body>
</TPDMessage>
3.2.6. Message 3.4

A truck arrives with products or aggregation of products (it is for importation of goods or
transfer from another site).

F_ID Arrival facility identifier code FID S M
30
CONFIDENTIAL
format.
Product_Return Indication if the arriving products Boolean S M 0 No

are a return following complete or 1 Yes
partial non-delivery
UI_Type Identification of UI types Integer S M
received
(recorded at the highest level of
available aggregation)
upUIs List of unit packet level UIs received upUI(L) M M, if

UI_Type
= 1 or 3
aUIs List of aggregated level UIs received aUI M M, if
UI_Type
= 2 or 3
Arrival_comment Comments by the reporting entity Text S O

N/A
Example:
<TPDMessage>
<Body>
<Message_34>
<Product_Return>0</Product_Return>
<aUIs>
</aUIs>
<Arrival_comment>Comment</Arrival_comment>
</Message_34>
</Body>
</TPDMessage>
31
CONFIDENTIAL
3.2.7. Message 3.5
Change of transport type
Field Comments Data Type Cardin Priority Values

ality
EO_ID Economic EOID S M

operator identifier
code of the
submitting entity
Event_Time Intended time of Time(s) S M

event occurrence

message is first
submitted to the
Gateway, Long
format.
Destination_ID1 Indication if the Boolean S M 0 No
destination 1 Yes
facility is
located in the UK
territory
Destination_ID2 Destination FID S M, if

facility identifier Destination_ID
code 1=1
Destination_ID3 Destination Text S M, if

facility's full Destination_ID 1 =
address 0
Destination_ID3_Address_Name Text O
Destination_ID3_Address_StreetO ne Text M, if
Destination_ID 1 =
0
Destination_ID3_Address_StreetT wo Text O
Destination_ID3_Address_City Text M, if
Destination_ID 1 =
0
Destination_ID3_Address_PostCo de Text O
32
CONFIDENTIAL
Transport_mode Mode of transport Integer S M 0-7
to which the
product is
transloaded, see:
Commission
Regulation
(EC) No
684/2009, Annex
II, Code List
7
Transport_vehicle Identification of Text S M

the vehicle (i.e.
number plates,
train number,
plane/flight
number, ship
name or other
identification)
Transport_cont1 Indication if Boolean S M 0 No

the transport 1 Yes
is
containerised
and uses an
individual
transport unit
code (e.g.
SSCC)
Transport_cont2 Individual ITU S M, if
transport unit Transport_cont
code of the 1=1
container
EMCS Dispatch under Boolean S M 0 No

the Excise 1 Yes
Movement and
Control System
(EMCS)
EMCS_ARC Administrativ e ARC S M, if EMCS = 1

Reference Code
(ARC)
UI_Type Identification of Integer S M
UI types subject
to the
transloading
(recorded at the
highest level of
available
aggregation)
upUIs List of unit upUI(L M M, if UI_Type = 1
packet level UIs ) or 3
33
CONFIDENTIAL
subject to the
transloading
aUIs List of aUI M M, if UI_Type = 2

aggregated level or 3
UIs subject to
the transloading
Transloading_comment Comments Text S O
by the reporting
entity

N/A
Example:
<TPDMessage>
<Body>
<Message_35>
<Destination_ID1>1</Destination_ID1>
<Destination_ID2>AWL2001</Destination_ID2>
<Transport_mode>3</Transport_mode>
<Transport_vehicle>ABC123</Transport_vehicle>
<Transport_cont1>0</Transport_cont1>
<EMCS>0</EMCS>
<aUIs>
</aUIs>
<Transloading_comment>Comment</Transloading_comment>
</Message_35>
</Body>
</TPDMessage>
34
CONFIDENTIAL
3.2.8. Message 3.6
When aggregation is disaggregated a message 3.6 can be used but is not mandatory.
EO_ID Economic operator's identifier EOID S M
F_ID Facility's identifier FID S M

format.
aUI Aggregated level UI subject to aUI S M
disaggregation
disaUI_comment Comments by the reporting entity Text S O

N/A
Example (XML):
<TPDMessage>
<Body>
<Message_36>
<disaUI_comment>Some Comment</disaUI_comment>
</Message_36>
</Body>
</TPDMessage>
35
CONFIDENTIAL
3.2.9. Message 3.7
A vending van has delivered products to a retail outlet.

F_ID Facility identifier code of retail outlet FID S M

format.
UI_Type Identification of UI types delivered Integer S M 1 only pack
(recorded at the highest level of UIDs
available aggregation) 2 only
aggregate
UIDs
3 both
upUIs List of unit packet level UIs delivered upUI(L) M M, if
UI_Type
= 1 or 3
aUIs List of aggregated level UIs delivered aUI M M, if
UI_Type
= 2 or 3
Delivery_comment Comments by the reporting entity Text S O

N/A
Example:
<TPDMessage>
<Body>
<Message_37>
<upUIs>
</upUIs>
<Delivery_comment>Some Comment</Delivery_comment>
</Message_37>
</Body>
</TPDMessage>
36
CONFIDENTIAL
3.2.10. Message 4.1
Invoice message
Message_ID (only for XML see 3.1.4.1

messages)
submitting entity
Event_Time Time of event Time(s) S M

occurrence
message is first
submitted to the
Gateway, Long
format.
Invoice_Type1 Type of the invoice Integer S M 1 Original

2 Correction
3 Other
Invoice_Type2 Description of the Text S M, if
other type of the Invoice_Type1=
invoice 3
Invoice_Number Number of the invoice Text S M
Invoice_Date Date of the invoice Date S M
Invoice_Seller Identity of the seller EOID S M
Invoice_Buyer1 Indication if the Boolean S M 0 No

buyer is located in 1 Yes
the UK
Invoice_Buyer2 Identity of the buyer EOID S M, if

Invoice_Buyer1 =
1
Buyer_Name Buyer's registered Text S M, if
legal name Invoice_Buyer1
=0
Buyer_Address Buyer's address – Text S M, if

street name, house Invoice_Buyer1
number, postal code, =0
city
Buyer_Address _Name Text O
37
CONFIDENTIAL
Buyer_Address_StreetOne Text M, if
Invoice_Buyer1 = 0
Buyer_Address_StreetTwo Text O
Buyer_Address_City Text M, if
Invoice_Buyer1= 0
Buyer_Address_PostCode Text O
Buyer_CountryReg Buyer's country of Country S M, if

registration Invoice_Buyer1 =
0
Buyer_TAX_N Buyer's tax registration Text S M, if
number Invoice_Buyer1 =
0
First_Seller_EU Indication if the invoice Boolean S M 0 No
is issued by the first 1 Yes
seller in the UK, i.e. the
UK manufacturer or the
importer, and the
product is destined for
the UK market.
The field remains as
“First_Seller_EU” to
remain compatible with
EU message structures.
Product_Items_1 List of TPIDs TPID M M, if
corresponding to the First_Seller_EU=
product items listed on 1
the invoice
Product_Items_2 List of product numbers PN M M, if
corresponding to the First_Seller_EU=
product items listed on 1
the invoice (in the same
order as
Product_Items_1)
Product_Price Net unit packet price per Decimal M M, if

each pair of First_Seller_EU=
TPID and product 1
number
(in the same order as
Product_Items_1
)
Invoice_Net Total net amount of the Decimal S M
invoice
Invoice_Currency Currency of the invoice Currency S M
38
CONFIDENTIAL
covered by
the invoice (recorded at
the highest level of
available aggregation)
upUIs List of unit packet level upUI(L) M M, if UI_Type = 1 or
UIs covered by the 3
invoice
aUIs List of aggregated level aUI M M, if UI_Type = 2 or
UIs covered by the 3
invoice
Invoice_comment Comments by the Text S O
reporting entity

1. Number of elements in list Product_Items_1 = Number of elements in list
Product_Items_2 = Number of elements in list Product_Price
Example:
<TPDMessage>
<Body>
<Message_41>
<Invoice_Type1>1</Invoice_Type1>
<Invoice_Number>0444322020100000831885</Invoice_Number>
<Invoice_Date>2019-05-20</Invoice_Date>
<Invoice_Seller>1</Invoice_Seller>
<Invoice_Buyer1>1</Invoice_Buyer1>
<Invoice_Buyer2>AWL0002</Invoice_Buyer2>
<First_Seller_EU>1</First_Seller_EU>
<Product_Items_1>
<tpid>02565-16-00230</tpid>
<tpid>02565-16-00231</tpid>
</Product_Items_1>
<Product_Items_2>
<pn>12121212121212</pn>
<pn>12121212121232</pn>
</Product_Items_2>
<Product_Price>
<price>12.2</price>
<price>13.2</price>
</Product_Price>
<Invoice_Net>1223.2</Invoice_Net>
<Invoice_Currency>GBP</Invoice_Currency>
<aUIs>
</aUIs>
39
CONFIDENTIAL
<Invoice_comment>A Comment</Invoice_comment>
</Message_41>
</Body>
</TPDMessage>
3.2.11. Message 4.2

sales order

messages)
EO_ID Economic operator identifier EOID S M
code of the submitting entity

Message_Time_Long The time that the message is Time(L) S M
first submitted to the Gateway,
Long format.
Order_Number Number of the purchase order Text S M
Order_Date Date of the purchase order Date S M

covered by
the purchase order (recorded at
the highest
level of available aggregation)
upUIs List of unit packet level UIs upUI(L) M M, if

covered by the purchase order UI_Type
= 1 or 3
aUIs List of aggregated level U the aUI M M, if
purchase order UI_Type
= 2 or 3
Order_comment Description of the reason for Text S O
delayed recording of the
purchase order
Additional technical message validations: N/A
Example (XML):
<TPDMessage>
<Body>
<Message_42>
<Order_Number>0444322020100000831885</Order_Number>
<Order_Date>2018-05-20</Order_Date>
40
CONFIDENTIAL
<aUIs>
</aUIs>
<Order_comment>A Comment</Order_comment>
</Message_42>
</Body>
</TPDMessage>
41
CONFIDENTIAL
3.2.12. Message 4.3
Partial or total payment of one or several invoices.
Field Comments Data Type Cardin Priority Values

ality
messages)
EO_ID Economic EOID S M
operator
identifier code of
the submitting
entity

occurrence

message is first
submitted to the
Gateway, Long
format.
Payment_Date Date of the Date S M
payment
receipt
Payment_Type Type of payment Integer S M 1 – bank

transfer 2 –
bank card 3 –
cash 4 –
other
Payment_Amount Amount of the Decimal S M

payment
Payment_Currency Currency of the Currency S M
payment
Payment_Payer1 Indication if the Boolean S M – No
payer is located – Yes
in the UK
Payment_Payer2 Identity of the EOID S M, if

payer Payment_Payer1=1
Payer_Name Payer's Text S M, if

registered legal Payment_Payer1=0
name
Payer_Address Payer's address Text S M, if
– street name, Payment_Payer1=0
house number,
postal code and
city
42
CONFIDENTIAL
Payer_Address _Name Text O
Payer_Address_StreetOne Text M, if
Payment_Payer1 =
0
Payer_Address_StreetTwo Text O
Payer _Address_City Text M, if

Payment_Payer1 =
0
Payer_Address_PostCode Text O
Payer_CountryReg Payer's country Country S M, if

of registration Payment_Payer1=0
Payer_TAX_N Payer's tax Text S M, if

registration Payment_Payer1=0
number
Payment_Recipient Identity of the EOID S M
recipient
Payment_Invoice Indication if the Boolean S M – No
payment – Yes
corresponds to
the existing
invoice
Invoice_Paid Number of the Text S M, if

invoice paid with Payment_Invoic e = 1
the payment
UI_Type Identification of Integer S M, if 1 – only unit

UI types covered Payment_Invoice = packet level
by the payment 0 UIs 2 – only
(recorded at the aggregated
highest level of level UIs 3 –
available both unit
aggregation) packet and
aggregated
level UIs
upUIs List of unit upUI(L) M M, if

packet level UIs Payment_Invoice =
covered by the 0 and UI_Type
payment = 1 or 3
43
CONFIDENTIAL
aUIs List of aUI M M, if
aggregated level Payment_Invoice =
UIs covered by 0 and UI_Type
the payment = 2 or 3
Payment_comment Comments Text S O

by the reporting
entity

N/A
Example (XML):
<TPDMessage>
<Body>
<Message_43>
<Payment_Date>2018-07-30</Payment_Date>
<Payment_Type>1</Payment_Type>
<Payment_Amount>1223.2</Payment_Amount>
<Payment_Currency>GBP</Payment_Currency>
<Payment_Payer1>1</Payment_Payer1>
<Payment_Payer2>AWL0002</Payment_Payer2>
<Payment_Recipient>AWL0001</Payment_Recipient>
<Payment_Invoice>0</Payment_Invoice>
<Invoice_Paid>0444322020100000831885</Invoice_Paid>
<aUIs>
</aUIs>
<Payment_comment>A comment</Payment_comment>
</Message_43>
</Body>
</TPDMessage>
44
CONFIDENTIAL
3.2.13. Message 5
Recall of a message

Type
EO_ID Economic operator identifier EOID S M

code of the submitting entity
Message_Time_ The time that the message is Time(L S M

Long first submitted to the )
Recall_CODE Message recall code Text S M

provided to the message
sender in the
acknowledgement of the
original message to be
recalled
Recall_Reason1 Reason for recalling the Intege S M 1 reported event
original message r did not materialise
(only for message
types 3-3 and 3-5)
2 message
contained
erroneous
information
3 other
Recall_Reason2 Description of the reason for Text S M, if
recalling the original Recall_Reason1
message =3
Recall_Reason3 Any additional explanations Text S O
on the reason for recalling
the original message
Notice: A recall with respect to operational and logistic events results in flagging
the recalled message as cancelled but does not lead to the deletion of the
existing database record.
45
CONFIDENTIAL
4. JSON messages
4.1. Message Structure
For each message, all elements used inside the message are described; the
column ‘M/O’ specifies if this element is required (M) or optional (O)
Endpoint for message submission: /v1/gateway/event
4.1.1. Formats
All messages are formatted using standard JSON representation
4.1.2. HTTP Header

Type
Content-Type string S M text/json
Authorization string S M Bearer {{access_token}}
{{access_token}} refers to access_token value provided in the response of the

authentication request (see 2.3 - Access Mechanism for additional details)
4.1.3. Message Type

The following table summarizes the JSON formatted messages.
Message_Type TYPE Description

IRU 2.1 Response for reporting the issuance of serial numbers at aggregated level.
IRA 2.2 Response for reporting the issuance of serial numbers at aggregated level.
IDA 2.3 Message 2.3 – Deactivation of UIs
PAR 3.0 Message 3.0 – Pairing of UIs
EUA 3.1 Message 3.1 - Commissioning
EPA 3.2 Message 3.2 - Aggregation
EDP 3.3 Message 3.3 - Shipment
ERP 3.4 Message 3.4 - Arrival
ETL 3.5 Message 3.5 - Transloading

EUD 3.6 Message 3.6 - disaggregation
EVR 3.7 Message 3.7 – Delivery to Retail Outlet
EIV 4.1 Message 4.1 - Invoice

EPO 4.2 Message 4.2 - Order
EPR 4.3 Message 4.3 - Payment
RCL 5.0 Message 5 - Recall
46
CONFIDENTIAL
4.1.4. Message Body
The Message Body contains one (and only one) message to be transferred to
the UK Gateway.
All messages must contain this basic information block concerning the request:
Field Data
Description Cardinality Priority Values
Type
Message_Type The identifier of the type of See 4.1.3 for list of
Text S M
message message types
Code The internal code of
acknowledgment of the
Text S M property is nullable
message. Used for recall
too.
The Code should be set to null for the initial request
4.1.5. Response details
4.1.5.1. Basic information block concerning the response

Message_Type The identifier of the
type of message that See 4.1.3 for list
Text S M
the response refers of message types
to
Error Indicates the failure of
0-No
the Boolean S M
1-Yes
message reception
Errors Array containing
Error_Code,
M if Error
Error_Data (string), Text S See 4.1.5.2
=1
Error_Descr,
Error_InternalID
Code Unique identifier of the
message. Used for Text S M
recall too.
Checksum The calculated
checksum of the Text S M
data received
47
CONFIDENTIAL
4.1.5.2. Basic error block description
Data Type Description Type
Error_Code Error code describing the error.

Text(30)
Error_Data Text field containing error

related data such as values
of attributes, list of UIs For all lists, use the #
character as separator.
Text()
Error_Descr Description of the error code. Text()
Error_InternalID Optional internal ID of the error. This internal

ID can be used for maintenance or audit
purpose.
Text(50)
Example:
{
…
"Errors": [
{
"Error_Code": "UI_NOT_EXIST",
"Error_Descr": "Text describing the error code",
"ErrorData":
"CF12D12AB887#CFEEAB2AB887#CFEED12AB887#AB1212AB6395"
}
],
…
}
48
CONFIDENTIAL
4.1.5.3. Common codes
Success code
HTTP Status 202 : the submitted message has been accepted by the UK
National Gateway
Example:
{
"Code": "873345b2-882f-4064-91f0-90669b46c30a",
"Message_Type": "DFA",
"Error": false,
"Errors": null,
"Checksum": "G6HF5H"
}
Error codes
HTTP
Error Code Error Description
Status
299 Check that the Events are
reported within 24 hours from the
OPERATION_WITHIN_24_HOURS
occurrence of the event:
299 A dispatch event has been sent
SHIPMENT_WITHIN_24_HOURS more then 24 hours before the
actual intended event time
401 Invalid or Expired security token
Please note that in this case
SECURITY_INVALID_OR_EXPIRED_TO the code or internal ID is not
KEN returned, as the message has
not reached the processing
service yet.
400 This error is returned when at
INVALID_REQUEST_FORMAT least one of the mandatory fields
are missing
400 When the field “Message_Type”
INVALID_MESSAGE_TYPE
is out of the defined list.
400 When the body of the message
INVALID_INPUT_FORMAT
doesn’t contain a valid JSON.
400 REQUIRED_FIELD_FAILED_VALIDATIO Check that mandatory fields are
N not missing and fields are
compliant with the defined format
400 A same UID is not present
MULTIPLE_UID
several times in the message
49
CONFIDENTIAL
400 the upUI exists in the repository
UI_NOT_VALID and has never been applied.
the aUI is not used
400 UI_NOT_EXIST check if the upUI exists
400 UI_EXPIRED upUI is not expired
400 MAX_LENGTH_FAILED_VALIDATION Message size exceed
400 Check that mandatory fields are
REQUIRED_FIELD_FAILED_VALIDATIO
not missing and fields are
N
compliant with the defined format
400 Check if ordered list of long
NON_COMPATIBLE_UIS upUIs matches with list of short
upUIs
400 Check if the list of long upUIs has
NOT_THE_SAME_NUMBER_OF_ITEMS the same number of items that
the list of short upUIs
400 Check that the UID is not
UI_DEACTIVATED
deactivated
400 Caller is not allowed to call this
CLAIM_VALIDATION_FAILED
method
400 Custom code provided when
CODE_NOT_EXIST recall message send for
unknown recall code
400 MULTIPLE_AGGREGATION check that the aUI is not used
400 check that the upUI has never
been applied no 3.1 message on
this upUI, based on the upUI(s))
UIS_APPLICATION_ERROR check that the FID of the
message is the same defined in
the 2.1 message received form
the ID Issuer for this upUI
400 Check that last message
received for aggregated UIs has
LOCATION_MISMATCH
the same FID as the location FID
in the current message
400 Check that the upUi is not
already sent in a 32 with a
OUT_OF_SEQUENCE
Message_Time_Long after the
pending one
400 Check that the aUi last message
is not a 33 or 37 and check in 32
UI_SEQUENCE_ERROR
if the upUI/aUI are not child of a
shipped aUI
400 Principle 5: The reporting on the
Arrival should be done on the
ARRIVAL_NOTALLOWED
same UI that have been reported
during the Dispatch/Transloading
50
CONFIDENTIAL
process. This is a consequence
of principle 4. This means that an
Arrival Event that contains child
UI of UI reported during the
Dispatch/Transloading Event will
be rejected. The same UI must
be reported.
400 Check if for all UIs related to the
event identified by RecallCode is
the very last unrecalled event
RECALL_NOT_LAST_EVENT
occurred on all such UI including
related implicitly disaggregated
parents.
400 Check for each AUids in 3.2, 3.3,
3.4, 3.5, 3.7 are activated, not
UI_ALREADY_DISAGGREGATED
disaggregated, and not
aggregated.
400 Printed codes have been used in
PRINTED_CODES_ALREADY_USED
another pairing
400 Paired codes have been used in
PAIRED_CODES_ALREADY_USED
another pairing
500 SYSTEM_ERROR Internal system error.
4.2. Message Content
4.2.1. Message IRU

Request for reporting the issuance of serial numbers at unit packet level

Type
BasicInfo_Req see 3.1.4.1

occurrence
The time that the
message is first
Message_Time_Long submitted to the Time(L) S M
Gateway, Long
format.
submitting entity
(either
manufacturer or
importer)
51
CONFIDENTIAL
Process_Type Indication if the Boolean S M 0 – No (only for
production process fully hand made
involves machinery products) 1 –
Yes
M_ID Machine identifier MID S M, if Process
code _Type
=1
P_Type Type of tobacco Integer S M See

product TobaccoProductT
ype
P_OtherType Description of other Text S M, if P_Type = 11 (other

type of tobacco product)
P_CN Combined Text S O

Nomenclature (CN)
code
P_Brand Brand of tobacco Text S M

product
P_weight Average gross Decimal S M

weight of unit packet,
including packaging,
in grams with
0,1 gram accuracy
TP_ID The identification TPID S M, if:

number of • Intended_Market is an
EU Country (including NI)
with EU-CEG Data;
• Intended_Market is an
UK Country (excluding
NI) with UK-CEG Data
TP_PN Tobacco product PN S M, if:

number used in the • Intended_Market is an
EU-CEG system EU Country (including NI)
with EU-CEG Data;
• Intended_Market is a UK
Country (excluding NI)
with UK-CEG Data;
• Otherwise with a Unique
Product Identifier (i.e.
GTIN or EAN)
52
CONFIDENTIAL
Intended_Market Intended country of Country S M
retail sale.
Intended_Route1 Indication if the Boolean S M 0 – No

product is intended 1 – Yes
to be moved across
country boarders
with terrestrial
transport.
Intended_Route2 The first country of Country S M, if Intended
terrestrial transport _Route1
after the product =1
leaves the country of
manufacturing or the
country of
importation.
Import Indication if the Boolean S M 0 – No
product is imported 1 – Yes
Req_Quantity Requested quantity Integer S M

of unit packet level
UIs – for the current
IRU message
Order_Req_Quantity Total Order Integer S O

Request quantity
of unit packet level
UIs.
Order_number Optional EO Request Text(50) S O
Order Number
P_OtherID Optional Product ID Text(20) S O
upUI List of unit packet upUI(s) M M

level UI issued by the
ID Issuer.
Example:
{
"EO_ID":"QCUKR+1AB020054",
"F_ID": "QCUKR<1AB020054000049",
"Event_Time":"19032014",
"Message_Time_Long":"2019-03-20T14:16:45Z",
"Process_Type":0,
"M_ID":"Machine Id A",
"P_Type":2,
"P_OtherType":null,
"P_CN": "FG7H68FHF"
"P_Brand":"Product brand A",
53
CONFIDENTIAL
"P_Weight":10.0,
"TP_ID":"1234",
"TP_PN":"1234",
"Intended_Market":"BG",
"Intended_Route1":1,
"Intended_Route2":"BG",
"Import":false, "Req_Quantity":2,
"upUI":["DANXXXXXXXXXXXX1PR0123456789","DANXXXXXXXXXXXX2PR0123456789"],
"Code": null, "Message_Type":"IRU"
}
4.2.2. Message IRA

Request for reporting the issuance of serial numbers at aggregated level –
request
BasicInfo_Req see 3.1.4.1
Time of event occurrence

Event_Time Time(s) S M
Message_Time_Long The time that the message Time(L)

is first submitted to the
S M
submitting entity
Req_Quantity Requested quantity of Integer S M

aUI List of aggregated level UIs aUI M M
Example:
{
"EO_ID": "QCUKR+1AB020054", "F_ID": "QCUKR<1AB020054000049",
"Event_Time" : "19032014", "Message_Time_Long":"2019-03-20T14:16:45Z",
"Req_Quantity": 2,
"aUI": ["DANXXXXXXXXXXXX1FA000001", " DANXXXXXXXXXXXX2FA000001" ],
"Message_Type": "IRA",
"Code": "873345b2-882f-4064-91f0-90669b46c30a",
}
54
CONFIDENTIAL
55
CONFIDENTIAL
4.2.3. Message 2.3 (IDA)
Changes the status of the UIs list in the request to “deactivated”
Message content:
- Same message content as XML Message 2.3, except no message_id field
- Message_type: IDA Example:
{
"EO_ID": "QCUKR+1AB020054",
"Event_Time" : "19032014",
"Deact_Type": 1,
"Deact_Reason1": 1, "Deact_Reason2": "reason one",
"Deact_Reason3":
"reason two",
"Deact_upUI": [
"DANXXXXXXXXXXXX1PR0123456789" ],
"Deact_apUI": [ "DANXXXXXXXXXXXX1FA000001" ],
"Message_Type": "IDA",
"Code": "873345b2-882f-4064-91f0-90669b46c30a",
}
Response:
common success response and error responses (see 4.1.5.3)
56
CONFIDENTIAL
4.2.4. Message 3.0
Pairing between printed code and virtual paired code
Message content:
- Message_type: PAR
{
"Event_Time": "19032014",
"upUI": {
"upID": [
{
"Printed_Code": "DANXXXXXXXXXXXX1PR012345678919030110",
"Paired_Code": "QCDLRXXXXXXXXXXX10FA000001"
},
{
"Printed_Code": "DANXXXXXXXXXXXX1PR012345678919030110",
"Paired_Code": "QCDLRXXXXXXXXXXX10FA000001"
}
]
},
"Message_Type": "PAR",
"Code": "873345b2-882f-4064-91f0-90669b46c30a"
}
Response:
57
CONFIDENTIAL
4.2.5. Message 3.1
Commissioning of UIDs
Message content:
- Message_type: EUA
{
"F_ID": "QCUKR<1AB020054000049",
"Event_Time": "19032014",
"upUI_1": [
"DANXXXXXXXXXXXX1PR012345678919030110",
"DANXXXXXXXXXXXX2PR012345678919030110"
],
"upUI_2": [
"DANXXXXXXXXXXXX1",
"DANXXXXXXXXXXXX2"
],
"upUI_comment": "Comments",
"Message_Type": "EUA",
"Code": "873345b2-882f-4064-91f0-90669b46c30a",
}
Response:
58
CONFIDENTIAL
4.2.6. Message 3.2
Aggregation of UIDs
Message content:
- Message_type: EPA
Technical message validations:

- same validations as for XML Message 3.2
Example:
{
"F_ID": "QCUKR<1AB020054000049",
"Event_Time": "19032014",
"Aggregation_Type": "1",
"aUI" : "DANXXXXXXXXXXXX1FA00000119030110",
"Aggregated_UIs1": [
"DANXXXXXXXXXXX10FA00000119030110"
],
"Aggregated_UIs2": [
],
"aUI_comment": "Comments",
"Message_Type": "EPA",
"Code": "873345b2-882f-4064-91f0-90669b46c30a"
}
Response:
59
CONFIDENTIAL
4.2.7. Message 3.3
Record that the UIs listed in the call have been dispatched from the economic
identifier
Message content:
- Message_type: EDP
N/A
Example:
{
"F_ID": "QCUKR<1AB020054000049",
"Event_Time": "19032014",
"Destination_ID1": "1",
"Destination_ID2": "FacilityIdB",
"Destination_ID3": [ " FacilityIdB ", " FacilityIdB " ],
"Destination_ID4": [ " FacilityIdB” ],
"Destination_ID5": "FacilityIdA",
"Transport_vehicle": "1",
"Transport_cont1": 1,
"Transport_cont2": "1",
"Transport_s1": 1,
"Transport_s2": "1", "EMCS": false,
"EMCS_ARC": null,
"SAAD": 1,
"SAAD_number": 1,
"Exp_Declaration": 1,
"Exp_DeclarationNumber": 1,
"UI_Type": 3,
"upUIs": [ "DANXXXXXXXXXXXX1PR012345678919030110",
"aUIs": [ "DANXXXXXXXXXXXX1FA00000119030110" ],
"Dispatch_comment": "Comments",
"Message_Type": "EDP",
"Code": "873345b2-882f-4064-91f0-90669b46c30a"
}
Response:
60
CONFIDENTIAL
4.2.8. Message 3.4
Record that the UIs listed in the call have been received to an economic
identifier.
Message content:
- Message_type: ERP

N/A
Example :
{
"F_ID": "QCUKR<1AB020054000049",
"Event_Time": "19032014", "Message_Time_Long":"2019-03-
20T14:16:45Z",
"Product_Return": "true",
"UI_Type": "1",
"upUIs": [
],
"aUIs": [
],
"Arrival_comment": "Comments",
"Message_Type": "ERP",
"Code": "873345b2-882f-4064-91f0-90669b46c30a"
}
Response: common success response and error responses (see 4.1.5.3)
61
CONFIDENTIAL
4.2.9. Message 3.5
Event to show that UIs have been moved from one transport mechanism to
another.
Message content:
- Message_type: ETL

N/A
Example:
{
"Event_Time": "19032014",
"Destination_ID1": 1,
"Destination_ID2": "FGHZ7G",
"Destination_ID3": "",
"Transport_mode": 1,
"Transport_vehicle": 1,
"Transport_cont1": 1,
"Transport_cont2": "code",
"EMCS": 1,
"EMCS_ARC": "ref",
"UI_Type": 1,
"upUIs": [
],
"aUIs": [
],
"Transloading_comment": "Comments",
"Message_Type": "ETL",
"Code": "873345b2-882f-4064-91f0-90669b46c30a"
}
Response:
62
CONFIDENTIAL
4.2.10. Message 3.6
Event showing that an aggregation no longer exists
Message content:
- Message_type: EUD
Example:
{
"F_ID": "QCUKR<1AB020054000049",
"Event_Time": "19032014",
"aUI": "DANXXXXXXXXXXX10FA00000119030110",
"disaUI_comment": "Comments",
"Message_Type": "EUD",
"Code": "873345b2-882f-4064-91f0-90669b46c30a"
}
4.2.11. Message 3.7

Event sent when UIs have been distributed via a van delivery.
Message content:
- Message_type: EVR
Example:
{
"F_ID": "QCUKR<1AB020054000049",
"Event_Time": "19032014",
"Message_Time_Long":"2019-03-20T14:16:45Z", "UI_Type": 1,
"upUIs": [
],
"aUIs": [
],
"Delivery_comment": "Comments",
"Message_Type": "EVR",
63
CONFIDENTIAL
"Code": "873345b2-882f-4064-91f0-90669b46c30a"
}
Response:
4.2.12. Message 4.1

Added invoice details to a UI
Message content:
- Message_type: EIV
{
"Event_Time": "19032014",
"Invoice_Type1": 1,
"Invoice_Type2": "other type",
"Invoice_Number": "INV000001",
"Invoice_Date": "2018-08-23T07:32:20.7878086+00:00",
"Invoice_Seller": "SellerId",
"Invoice_Buyer1": false,
"Invoice_Buyer2": null,
"Buyer_Name": "Buyer1",
"Buyer_Address": "BuyerAddress",
"Buyer_CountryReg": "LU",
"Buyer_TAX_N": "TAX0001",
"First_Seller_EU": 1,
"Product_Items_1": [ "11111-1111111","11111-1111112" ],
"Product_Items_2": [ "01234567891234","01234567891235" ],
"Product_Price": [ "16.99", "19.99" ],
"Invoice_Net": 10099.99,
"Invoice_Currency": "GBP",
"UI_Type": 1,
"aUIs": [ "DANXXXXXXXXXXX10FA00000119030110" ],
"Invoice_comment": "Comments",
"Message_Type": "EIV",
"Code": "873345b2-882f-4064-91f0-90669b46c30a"
}
Response:
64
CONFIDENTIAL
4.2.13. Message 4.2
Adds a purchase order event to a UI
Message content:
- Message_type: EPO
Example:
{
"Event_Time": "19032014",
"Order_Number": "1234",
"Order_Date": "2018-08-23T07:32:20.7878086+00:00",
"UI_Type": 1,
"aUIs": [ "DANXXXXXXXXXXX10FA00000119030110" ],
"Order_comment": "Comments",
"Message_Type": "EPO",
"Code": "873345b2-882f-4064-91f0-90669b46c30a"
}
Response:
4.2.14. Message 4.3

Adds a payment record event to a UI
Message content:
- Message_type: EPR
Example:
{
"Event_Time": "19032014",
"Payment_Date": "2018-08-23T07:32:20.7878086+00:00",
"Payment_Type": 1,
"InvoiceType": 1,
65
CONFIDENTIAL
"UI_Type": 1,
"Payment_Amount": 1.99,
"Payment_Currency": "GBP",
"Payment_Payer1": true,
"Payment_Payer2": "PayerId", "Payer_Name": "PayerNmae",
"Payer_Address": "Address",
"Payer_CountryReg": "UK",
"Payer_TAX_N": "TaxId",
"Payment_Recipient": "PaymentRecipient",
"Payment_Invoice": 1,
"Invoice_Paid": "test" ,
"aUIs": [ "DANXXXXXXXXXXX10FA00000119030110",
"DANXXXXXXXXXXX20FA00000119030110" ],
"Payment_comment": "Comments",
"Message_Type": "EPR",
"Code": "873345b2-882f-4064-91f0-90669b46c30a"
}
Response:
4.2.15. Message 5
Given a recall id (“Code” in the return of any message) The caller can mark that
event invalid.
This is possible for message types 2-1, 2-2, 3-1 to 3-7, 4-1, 4-2 and 4-3)
Message content:
- Same content as XML Message 5, except no message_id field
- Message_type: RCL
Example:
{
"EO_ID":"QCUKR+1AB020054",
"Recall_CODE":"6854f9a6-a2b2-4c08-8000-0173f3c35567",
"RecallReason1":1,
"RecallReason2":1,
"RecallReason3":"Comments",
"Message_Type":"RCL",
"Code": "873345b2-882f-4064-91f0-90669b46c30a"
}
Response:
66
CONFIDENTIAL
5. Message Validation
When receiving a message, the UK National Gateway performs the following

validation rules. Some of the following rules may generate warnings rather than
exceptions under certain conditions, e.g. when scanning products manufactured
prior to the UKs exit from the EU once the UK has left the EU.
Validation Concerned In Control

Error Code Validation performed
type messages repo? reference
SECURITY_INVALID_OR_ Security VAL_SEC_TOKEN
Invalid or Expired security token All messages No
EXPIRED_TOKEN
Technical Check that message size does not VAL_MSG_JSON
exceed 6 MB and HTTP header size
does not exceed 1KB
MAX_LENGTH_ For 2.3, 3.x and 4.x : Check that

All messages No
FAILED_VALIDATION the number of UIs (sum of the unit
level UI and the aggregated level
UI) per message is under 50 000
For 3.1 : only check the number of
short upUIs is under 50 000
Technical Yes (in VAL_MSG_JSON
the VAL_MSG_XML
Check that the message contains a
INVALID_INPUT_FORMAT All messages invalid
valid JSON / XML
reposito
ry)
Technical Yes (in VAL_MSG_TYPE
the
Check that the type of message
INVALID_MESSAGE_TYPE All messages invalid
field is in the defined list
reposito
ry)
Technical Check that mandatory fields are not Yes (in VAL_FIE_MAN
missing and fields are compliant the VAL_FIE_FORMAT
REQUIRED_FIELD_FAILED
with the defined format (data type, All messages invalid VAL_FIE_REF
_VALIDATION
cardinality, value). The whole reposito
message is checked. ry)
Technical Yes (in VAL_FIE_FORMAT
Check if ordered list of long upUIs
the
matches with list of short upUIs.
NON_COMPATIBLE_UIS 3.1 invalid
Note that upUI(s) is the upUI(L)
reposito
with the timestamp (YYMMDDhh)
ry)
Technical Yes (in VAL_FIE_FORMAT
Check if the list of long upUIs has the
NOT_THE_SAME_NUMBER
the same number of items that the 3.1 – 4.1 invalid
_OF_ITEMS
list of short upUIs reposito
ry)
Technical Check that the same UID is not VAL_UI_MULT_MS
present several times in the G
2.3 – 3.1 –
message Yes (in
3.2 – 3.3 –
For 3.2 messages, the validation on the
3.4 – 3.5 –
MULTIPLE_UID the parent UI should also be invalid
3.6 – 3.7 –
performed in order to avoid first reposito
4.1 – 4.2 –
level cyclical reference: check that ry)
4.3
parent UI is not present in the
childUI list.
Functional upUI validity : check that the upUI Yes (in VAL_UI_EXIST_A
UI_NOT_VALID exists in the repository (based on 3.1 the PP
upUI(s) received via a 2.1 message) invalid
67
CONFIDENTIAL
reposito
ry)
Functional upUI application : VAL_UI_FID_APP
- check that the upUI has never
Yes (in
been applied no 3.1 message on this
the
UIS_APPLICATION_ERRO upUI, based on the upUI(s))
3.1 invalid
R - check that the FID of the message
reposito
is the same defined in the 2.1
ry)
message received form the ID Issuer
for this upUI
Functional aUI validity : check that the aUI is VAL_UI_ORD_AG
Yes (in
not used (no 3.2 message on this G_MULT
3.2 (for the
aUI) OR if it has been used (existing
MULTIPLE_AGGREGATION aggregation invalid
3.2 message on this aUI) it is
aUI) reposito
disaggregated (last message for this
ry)
aUI is a 3.6 message)
Functional The UID exists in the repository : VAL_UI_EXIST_U
- for 2.3 : check that the upUI is in 2.3 – 3.2 PUI
database (received from ID Issuer) (for VAL_UI_EXIST_A
Yes (in
or the aUI exists in a 3.2 message aggregated UI
the
- for 3.x: check that the upUI exists UIs) – 3.3 – VAL_UI_EXIST_U
UI_NOT_EXIST invalid
in a 3.1 message or the aUI exists in 3.4 – 3.5 – PUI_SEQ
reposito
a 3.2 message 3.6 – 3.7 – VAL_UI_EXIST_A
ry)
- for 4.x : check that the upUI exists 4.1 – 4.2 – UI_SEQ
in a 3.1 message or the aUI exists in 4.3
a 3.2 message
Functional Yes (in VAL_UI_EXPIRY
upUI is not expired : check that
the
application date (timestamp) doesn’t
UI_EXPIRED 3.1 invalid
exceed the 6 months period after
reposito
the code has been issued
ry)
Functional Check that the UID is not VAL_UI_ORD_DE
deactivated (no 2.3 message on this ACTIVATED
UID) VAL_UI_ORD_RE
Yes (in ACTIVATION
2.3 – 3.1 –
Check that the UID don’t have a the
3.2 – 3.3 –
UI_DEACTIVATED parent, in the whole hierarchy, invalid
3.4 – 3.5 –
deactivated with reason Product reposito
3.6 – 3.7
destroyed or Product stolen (no 2.3 ry)
message on the UID parents
hierarchy with Deact_Reason1 = 1
or 2)
Functional Check that the aUI has not be VAL_UI_ORD_DI
previously disaggregated (no SAGG
existing 3.6 message for this aUI VAL_UI_ORD_IM
between the last 3.2 message and PLDISAGG
this one)
Implicit disaggregation check:

Check that all aUI belonging to the
3.2 (for Yes (in
hierarchy of this aUI (child,
aggregated the
UI_ALREADY_DISAGGREG grandchild, etc) have not been
UIs) – 3.3 – invalid
ATED deactivated (last message is a 2.3
3.4 – 3.5– reposito
message, not recalled), aggregated
3.7 ry)
(last message is a 3.2 message, not
recalled), disaggregated (last
message is a 3.6 message, not
recalled) or moved (last message is
a 3.3, 3.4, 3.6 or 3.7, not recalled)
or arrived as a product return (last
message is a 3.4 with
Product_Return = 1) (not recalled)
Functional VAL_UI_ORD_AG
For 3.2 or 3.6 message : Yes (in
3.2– 3.3 – G_FID
LOCATION_MISMATCH Check that last message received for the
3.6 VAL_UI_ORD_DI
aggregated UIs (3.1, 3.2, 3.4 or 3.6) invalid
SPATCH
68
CONFIDENTIAL
has the same FID as the location FID reposito
in the current message ry)
For 3.3 message :
Check that the 3.1 or 3.2 or 3.4
message related to the UI (last one
of these messages) has the same
FID as the dispatch FID of the
current message
Functional Yes (in VAL_UI_ORD_SE
This is a generic sequence validation the QUENCE
3.2-3.3-3.5-
UI_SEQUENCE_ERROR error, to avoid illogical sequence of invalid
3.7
events. reposito
ry)
Functional For 3.2 message :
Check that the children of the
aggregation message were
previously aggregated, with a Yes (in
younger message_time_long. If this the
OUT_OF_SEQUENCE happens, then the incoming 3.2 invalid
message is not valid. reposito
This control prevents the ry)
transmission of out-of-sequence
aggregation messages, which would
provoke implicit disaggregation.
Functional When Product_Return field = 0 : VAL_UI_ORD_AR
Check that each UI is part of a prior RIVAL
reported dispatch or transloading VAL_UI_ORD_AR
event (last message is a 3.3 or 3.5 RIVAL_RETURN
message).
Exception: this control is not
performed for imported products
(upUI) or aUI containing only Yes (in
imported upUIs (The message 2.1’ the
ARRIVAL_NOTALLOWED contains the import flag information) 3.4 invalid
reposito
When Product_Return field = 1: ry)
Check that each UI is part of a prior
reported dispatch or transloading
event (last message is a 3.3, 3.5 or
3.7 message). Prior reported
dispatch could be done on the
parent UI (including all the parent
hierarchy).
Functional Check that the message is not sent VAL_EVT_TIME
more than 24 hours before shipment
(based on the reception date and
SHIPMENT_WITHIN_24_H
"Event_Time”) 3.3 – 3.5 Yes
OURS
This validation only generates a
warning – message is accepted
OPERATION_WITHIN_24_ Functional Check that the Events are reported VAL_EVT_24H
HOURS within 24 hours from the occurrence
of the event: Record Time must not
3.1 – 3.2 –
be more than 24 hours after the
3.7 – 4.1 – Yes
Event Time date.
4.2 – 4.3
This validation only generates a
warning – message is accepted
CODE_NOT_EXIST Functional Yes (in VAL_RECALL_EXI
the ST
Check that the recall code exists 5 invalid
reposito
ry)
RECALL_NOT_LAST_EVEN Functional Yes (in VAL_RECALL_LAS
Check, for all UIs related to the
T 5 the T
event to recall, if it is the very last
invalid
69
CONFIDENTIAL
unrecalled event (including related reposito
implicitly disaggregated parents) ry)
If recall is done on a
transaction event (message
type 4.x), test is not
performed.
MESSAGE_ALREADY_REC Functional Test is performed on the unicity of VAL_MSG_DUPLI
EIVED the message. CATE
Manufacturer or Importer is alerted
if the same message is processed Only for XML
twice by sending a message id in the messages
message. including No
A message sent but rejected message_ID
(neither 200 nor 299) can be field
replayed with the same message ID.
In that case, the warning
RETRY_SUCCESSFULL will be raised.
Functional Yes (in
the
PRINTED_CODES_ALREAD Printed codes have been used in
3.0 invalid
Y_USED another pairing
reposito
ry)
Functional Yes (in
the
PAIRED_CODES_ALREADY Paired codes have been used in
3.0 invalid
_USED another pairing
reposito
ry)
RETRY_SUCCESSFULL Functional This test is the same as
MESSAGE_ALREADY_RECEIVED, but
this one is only a warning if same
messageID is used, but never All messages Yes
accepted previously.
It’s typically the case for a replay.

Technical Check that caller is allowed to call
this method
CLAIM_VALIDATION_FAIL
Particularly used for : All messages No
ED
- message 3.1 from Router (only
allowed from Manufacturer)
SYSTEM_ERROR - Internal system error. All messages No
70
CONFIDENTIAL

UK National Tobacco Track Trace Gateway Technical Specification

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

UK National Tobacco Track Trace Gateway Technical Specification

Uploaded by

Copyright:

Available Formats

UK National Tobacco

Track & Trace

No information as to the contents or Submission date:

©De La Rue International Limited 2020,

This document doesn’t describe internal technical details, and communications

1.3. Definitions of terms and abbreviations

Data carrier is a means of representing data in machine readable form.

Manufacturer is any natural or legal person who manufactures a product or has

Trans-loading is any transfer of tobacco products from one vehicle to another

Unit packet is the smallest individual packaging of a tobacco or related product

2.2. Data requests to UK UID Issuer

2.3. Access Mechanism

OAuth 2.0 is the industry-standard protocol for authorization. OAuth 2.0

In this chapter, we will highlight the two authentication and authorization

For Technical Users

curl -d "client_id=<CLIENT_ID>" \ -d "client_secret=<CLIENT_SECRET>" \

Note: CLIENT_ID, CLIENT_SECRET, URL_OAUTH_PROVIDER and REALM are

The Worldline Authentication Provider answers as follow:

curl -H "Authorization: Bearer <BEARER_TOKEN>" \

This second authentication method mainly concerns human users requesting

The following figure shows a typical retry-mechanism process.

2.4. Recall code

Here is an example of recall_code: AWL0001-c1df56cf-b802-426b-8cbe-

2.5. Data Types

Administrative Reference Code (ARC) or any

Economic operator identifier code corresponding to

Machine identifier code corresponding to the format

Excise number composed of:

UTC (Coordinated Universal Time) in the following

Product number – numeric identifier used to identify

Unit packet level unique identifier coded with the

upUI(M) Unit packet level unique identifier coded with the

2.6. Authorized formats (long / short) for UIDs

Long format Short Format

Endpoint for message submission: /v1/gateway/ext/event

3.1.2. HTTP Header

Field Data Cardinality Priority Values

3.1.3. Message Header

Field Data Cardinality Priority Values

3.1.4. Message Body

Field Value Priority Comment / Example

3.1.5. Response details

3.1.5.1. HTTP code 200

Field Comments Data Cardinality Priority Values

recall_code The unique ID String S M for messages

3.1.5.2. HTTP code 299

3.1.5.3. HTTP code 400

Field Comments Data Type Cardinality Priority Values

path The path of the String S M

date The UTC date String S M

reason The reason of string S M

3.1.5.4. HTTP code 401

Field Comments Data Type Cardinality Priority Values

path The path of String S M

code string S M SECURITY_INVALID_OR_EXPIRED_TOKEN

3.1.5.5. HTTP code 500

Field Comments Data Type Cardinality Priority Values

path The path of the String S M

code The HTTP integer($int32) S M

date The UTC date String S M

code string S M INTERNAL_SERVER_ERROR

3.2. Message Content

Field Comments Data Type Cardinality Priority Values

Message_ID see 3.1.4.1