5.2 S ECONDARY REPOSITORY AND R OUTER INTERFACE
5.2.3 Encoding
All messages are encoded in UTF-8 5.2.4 Secured communication
Communication between the Secondary repository and interacting participants of the tobacco industry is secured by TSL 1.2 encryption AES256 cypher. Cypher suites that are less secure are not supported. If the TLS version or cypher used proves to be corroded or vulnerable, Dentsu Aegis reserves the right to replace the affected item with a state-of-the-art item after prior announcement.
EU Secondary List of specifications, Version 1.4.4 62 / 84
The repository system uses OAuth 2.0 to authorize access to the web service methods. 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 and server to server communication.
The system uses the OAuth client credential flow. The client credentials flow is used as an authorization grant as the authorization scope is limited to the protected resources previously arranged with the authorization server (the server being the Secondary repository).
Access tokens are issued as credentials used to access protected resources. An access token is a string representing an authorization issued to the client. The string is opaque to the client and passed in the authentication header. Tokens represent specific scopes and durations of access, granted by the resource owner, and enforced by the resource server and authorization server. Tokens have an expiry of 3600 seconds (1 hour).
5.2.5 Version and backward compatibility
Dentsu Aegis provides an API versioning approach using a version identifier in the URL.
Example URL: https://{seconardayUrl}/v1
We currently see no reason to make a breaking change or enhancement that would require a V2 to be added. This convention is in place to facilitate all eventualities in the future.
Our goal would be to make releases to the API that are non-breaking by being backward compatible, for example adding additional return properties, not removing old ones.
5.2.6 System Reception Timestamp
In some cases, manufacturer systems can generate bursts of messages. A
number of messages can be produced during the same second and therefore will have the same EventTime and the same MessageTimeLong.
In order to implement efficiently the sequence validation controls, the System Reception_Time at a millisecond precision is defined.
The Reception_Time will be recorded and added by the Primary repository and Router.
The reception Time added by the router will be transmitted to the primaries.
Primary repositories should accept and transmit the field to the secondary repository.
EU Secondary List of specifications, Version 1.4.4 63 / 84
5.2.7 Message identification and RecallCode 5.2.7.1 Overview
The traceability system, and more precisely, the entry point system (Primary repository and Router) assigns a unique identifier to each message. This unique identifier is the RecallCode.
When the message is routed and transmitted to the Secondary repository via the primary repositories, the RecallCode issued by the Router is forwarded to the primary repository.
5.2.7.2 EPCIS eventID and RecallCode
In the case of the EPCIS interface, the EPCIS 1.2 protocol doesn’t allow the transmission of the identification information back to the sender. The eventID field provided by the sender will be used as RecallCode.
5.2.7.3 Message Recall
Economic operators have the possibility to recall requests, operational and transactional messages transmitted to the Secondary repository.
The reasons for recalling the original message may be:
1. Reported event did not materialise (only for messages related to dispatch events and trans-loading)
2. Message contained erroneous information 3. Other
5.2.7.4 RecallCode structure
ReallCode structure follows version 5 of the UUIDs standards from ISO/IEC 11578:1996.
5.2.7.5 Messages
The following table describes the messages that are subject to Recall.
Annex II Reference
ISU (2.1) Request for unit level UIs
IRU Data Request for unit level UIs
ISA (2.2) Request for reporting the issuance of Unique Identifiers at aggregated level
IRA Data Request for reporting the issuance of Unique Identifiers at aggregated level
EUA (3.1) Application of unit level UIs on unit packets
EPA (3.2) Application of aggregated level UIs on aggregated packaging EDP (3.3) Dispatch of tobacco products from a facility
ERP (3.4) Arrival of tobacco products at a facility
ETL (3.5) Trans-loading
EUD (3.6) Disaggregation of aggregated level UIs
EVR (3.7) Report of delivery carried out with a vending van to retail outlet EIV (4.1) Issuing of the invoice
EPO (4.2) Issuing of the order number EPR (4.3) Receipt of the payment
EU Secondary List of specifications, Version 1.4.4 64 / 84
5.2.7.6 Recall Process
The recall must include the message’s RecallCode that has been provided to the message sender in the acknowledgement of the original message. It must also contain the following information:
• Reason for recalling the original message
• Description of the reason for recalling the original message
• Any additional explanations on the reason for recalling the original message
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.
5.2.7.7 RecallCode Field
Technically the RecallCode is obtained from the original message’s “code”
property:
Example response:
{
"Code": "6854f9a6-a2b2-4c08-8000-0173f3c35567", "Message_Type": “EPA”,
"Error": false, "Errors": null }
Where the “Code” is the RecallCode.
5.2.8 Message response
A message transmission corresponds to a message request performed by a sender system and a message response provided by the destination system back to the sender system.
The Message response contains and http status and the body of the messages response.
5.2.8.1 Successful response or event acknowledgment
As per the Implementing Regulation, A message or event is considered reported upon the reception of the acknowledgement message (successful) transmitted back by the destination system.
The http status for the message positive response without any warning are 200 and 202.
A warning (http status 299) is considered as a successful response.
5.2.8.2 Negative response
The destination system is providing with a negative response if the reported event is not meeting the technical specifications.
Negative response http status is in the range of 400-499 and 500-599.
EU Secondary List of specifications, Version 1.4.4 65 / 84
5.2.8.3 Timeout
The destination system did not produce a response within the time that the sender system was prepared to wait. The sender system may repeat the request without modifications at any later time.
The absence of response (or the http timeout response) indicates that the message is not acknowledged.
5.2.8.4 Timeout handling
In case of a timeout for a certain request, the sender system should retransmit the original message (identical payload).
If the sender system changes the original message (by updating the Message Time Long for example), the receiving system will consider the message as a different message.
5.2.8.5 Successful response sample
HTTP Status 202
{
"Code": " 6854f9a6-a2b2-4c08-8000-0173f3c35567", "Message_Type": “EPA”,
"Error": false, "Errors": null,
"Checksum": "G6HF5H"
}
5.2.8.6 Error response sample
The system should provide the sufficient details to allow external systems, administrators to identify precisely the issue in order to act accordingly.
The response message can contain a list of error
"Errors": [
{ << Error >>}, { << Error >>}, { << Error >>}, ],
Each error contains the following information.
• Error_InternalID is the unique identification of the message processing and validation activity.
• Error_Code is the identifier of the type within the systems.
• Error_Descr is the description in human readable format containing specific error information
• Error_Data is the data for which the error is talking about. This can be used for EO_IDs, F_IDs, M_IDs and UIs.
o Note: use # as separator for the UI in case a list of UI is provided in the error data field.
Example of List of errors
{
EU Secondary List of specifications, Version 1.4.4 66 / 84 "Error_InternalID": "yndkFz7TBEO706frD38hzA",
"Error_Code": "INVALID_REQUEST_FORMAT",
"Error_Descr": "The EconomicOperatorIdentifier field is unknown."
"Error_Data": "123456789123456#123456789123455#123456789123444"
}
Security errors HTTP
status Error Code
401 Invalid security token
401 Expired security token
Processing errors HTTP
status Error Code
400 INVALID_REQUEST_FORMAT This error is returned when at least one of the mandatory fields are missing.
400 INVALID_MESSAGE_TYPE When the field “Message_Type” is out of the defined list.
400 INVALID_INPUT_FORMAT When the body of the message doesn’t contain a valid JSON.
500 SYSTEM_ERROR Internal system error.
Error body sample
{
"Error_InternalID": "yndkFz7TBEO706frD38hzA", "Error_Code": "INVALID_REQUEST_FORMAT",
"Error_Descr": "The EconomicOperatorIdentifier field is required."
"Error_Data": "54G7J }
],
"Checksum": "G6HF5H"
}
5.2.9 Forward Rejected Messages.
It is a requirement that the Secondary repository must store validation failures, this including failures that occur on the Primary repositories and the Router.
Primary repositories and Router will therefore forward the rejected messages to the Secondary repository.
5.2.9.1 Scope of Rejected Messages to be forwarded.
A rejected message is defined as a message that fails due to a business validation reason. The validation messages are described in the following sections:
• section Unique Identifiers validation
• section Identification Code validation
EU Secondary List of specifications, Version 1.4.4 67 / 84
• section Recall Validation
It is not expected that the Secondary repository is sent failed authentication attempts, badly formed messages or anything other than the validations listed in the above sections.
5.2.9.2 Message Rejection processing
In case the message fails the validation, the system should
• log the rejected message
• log the response information
• send an error message to the requesting system with the details
• forward the rejected message to the Secondary Repository 5.2.9.3 The message should contain
• The original request
• The optional base request sections
{
"EO_ID": "Z25Q1H44IB3002078572YSHR", "F_ID": "OVERSEEING9220693452TACTL", "Event_Time": "19032014",
"aUI": "testparent_sdgdg", "Aggregation_Type": 1, "Aggregated_UIs1": [
"123456789123456789"
],
"Aggregated_UIs2": null, "aUI_comment": "Comments", "Message_Type": "EPA",
"Error_Descr": "The EconomicOperatorIdentifier does not exist.", "ErrorData": "123456789123456789"
} ] } }
5.2.10 Message integrity and hash
The Repository system will verify the message checksum to ensure that the data was not tampered with between parts of the whole Repository system. Messages where the hash is not valid must not be accepted.
This integrity check ensures that the messages making up traffic cannot be altered in transit or within the parts of the Repository system, neither can messages be added or removed from the sequence, without detection.
The client adds a MD5 hash to the X-OriginalHash HTTP header.
This structure is then added to the message
EU Secondary List of specifications, Version 1.4.4 68 / 84
Message Header
X-OriginalHash 1234567890abcdefghijklmnopqrstuvwxyz Content-Type application/json
Authorization <Token>
HTTP status
Error Code
401 INVALID_SIGNATURE "The message signature does not match”
5.2.11Message size
5.2.11.1 Message size
The maximum message size is 6MB.
The limit on the HTTP header size is 10’240 bytes.
5.2.11.2 Maximum number of UI
The online sequence validation controls require the limitation of the number of UI (sum of the unit level UI and the aggregated level UI) per message for the following events
Message Type
Annex II Reference
Message description Number of UI (upUI + aUI) IDA (2.3) Request for deactivation of UIs 50 000
EUA (3.1) Application of unit level UIs on unit
packets 50 000
EPA (3.2) Application of aggregated level UIs
on aggregated packaging 50 000
EDP (3.3) Dispatch Event 50 000
ERP (3.4) Reception event 50 000
ETL (3.5) Trans-loading event 50 000
EUD (3.6) Message to report an UID
disaggregation 50 000
EVR (3.7) Report the delivery carried out with a vending van to retail outlet
50 000 EIV (4.1) Message to report an invoice 50 000
EPO (4.2) Purchase order 50 000
EPR (4.3) Payment record 50 000
5.2.12 Number of simultaneous connections
There is no limit for simultaneous connections between the Router and the Secondary repository.
5.2.13 Message Sequence
Message sequence must comply with the corresponding regulation.
EU Secondary List of specifications, Version 1.4.4 69 / 84
The Primary repository must report the messages reported by the manufacturer in the same sequence. The reporting of messages to the secondary repository is completed upon reception of an acknowledgement message by the Secondary repository.
Note: If the primary repository reports two messages affecting the same group of UIs without waiting for the acknowledgment from the Secondary
repository, both messages are considered to be reported simultaneously and NOT in sequence. By “affecting the same group of UIs” it refers either explicitly mentioned UIs between the messages or implicitly calculated UIs based on previous messages (i.e. hierarchy related UIs).
5.2.14 Buffering and Burst transmissions
Messages should be transmitted continuously by the different systems without buffering.
In case of technical buffering caused by technical maintenance activities, the transmitting system should implement mechanism to ensure the correct sequencing of the events.
5.2.15 Message Retransmission limitation
A message that was positively acknowledged must not be retransmitted a second time.
5.2.16 Connectivity Test Message
A Connectivity Test Message (CTM) is implemented on the interface PR2RT. This message is sent by the Router to check the availability and the security
configuration of the endpoint.
Interface
acronym Hosting system Description
PR2RT Primary
repository Secure interface published by Primary repository providers for Router
communication 5.2.17Duplicate message validation
Retransmission of successful messages introduce an unnecessary load and negatively impact the data visualization and reporting.
A validation of duplicate successful message is included in order to eliminate such duplicate retransmission of successful messages.
5.2.17.1 New Message validation
Upon reception of a message, the first entry point (the Router or the Primary repository) validates the messages and assign a unique RecallCode.
If the message passes the validation and is accepted (returning a successful response Status 200 or 202), the message is processed by the system and is not expected to be received again.
EU Secondary List of specifications, Version 1.4.4 70 / 84
In case the successful message is retransmitted (identical payload) to the system, the system will return a duplicate message validation error (adding the Recallcode corresponding to the original successful message) (Status 400).
Note: in case the message validation fails, the transmitting system is able to send the same message.
5.2.17.2 Routed or forwarded message validation
When the message is routed or forwarded, the message contains a RecallCode.
The system will maintain the list of all successful RecallCode corresponding to the successful messages.
In case the incoming message RecallCode indicate that the message has been processed successfully, the system returns a validation error.
5.3 EPCIS and EDI Support
5.3.1 Overview
GS1 EPCIS and EDI provide optional message formats, which deliver equivalent data when used with GS1 aggregate level or aggregate and unit level identifiers.
This permits one message to support traditional retail supply chain business or end-to-end traceability requirements and to support EU 2018/574 reporting.
At
https://www.gs1.org/docs/epc/FightingIllicitTradeEPCIS_Application_Standard.p df , GS1 has published a GS1 EPCIS Application Standard for Fighting Illicit Trade, particularly in the context of EU 2018/574.
5.3.2 PRODUCT MOVEMENT EVENTS
Ref Ref Description EPCIS EUA (3.1) Application of unit
level UIs on unit packets
EPCIS Object Event
(business step “Commissioning”) EPA (3.2) Application of
aggregated level UIs on aggregated packaging
EPCIS Aggregation Event (business step
“Packing”)
EDP (3.3) Dispatch Event EPCIS Object Event
(business step “Shipping”) ERP (3.4) Reception event EPCIS Object Event
(business step “Arriving”)
ETL (3.5) Trans-loading event EPCIS Object Event (business step
“transloading”) EUD (3.6) Message to report an
UID disaggregation EPCIS Aggregation Event (business step “Unpacking”) EVR (3.7) Report the delivery
carried out with a vending van to retail outlet
EPCIS Object Event (business step “Arriving”)
5.3.3 TRANSACTIONAL EVENTS
Ref Ref Description EDI EIV (4.1) Message to report an
invoice EDI: Invoice
EU Secondary List of specifications, Version 1.4.4 71 / 84
EPO (4.2) Purchase order EDI: Order EPR (4.3) Payment record EDI: Settlement
5.3.4 ERROR HANDLING MESSAGE
Ref Ref Description EPCIS RCL (5.0) Recall messages
5.3.5 EPCIS Recall Management
EPCIS negation of a previous event by means of a subsequent, identical event that contains an ErrorDeclaration, and whose eventID is equal to the eventID of the prior (erroneous/recalled) event.
EU Secondary List of specifications, Version 1.4.4 72 / 84
5.4 Identifier Code Verification Service
5.4.1 Overview
The purpose of this service is to allow the ID Issuers and manufacturers to check:
• the validity of the EOID, FID and MID.
• the validity of the relation between EOID, FID and MID, or EOID and FID.
5.4.2 Interface Interface
acronym Hosting
system Description
SU2II Secondary
repository Secure interface published by the Secondary repository for Identifier Code verification purposes
5.4.3 Verification Result
The service validates the existence and the validity of the EOID, FID and the MID.
• If the EOID, FID and MID are defined in the EU Wide Register and marked as active, the response value will be true.
• If the EOID, FID and MID are not defined in the EU Wide Register or marked as inactive, the response value will be false.
The service validates the relationship of the EOID, FID and the MID.
• If the EOID, FID and the MID are valid and If the relation between the EOID, FID and the MID is defined in the EU Wide Register, the response will be true.
5.5 Primary repository endpoint
5.5.1 Overview
The Primary repository should expose an endpoint that will be used by the Router to transmit the described messages. All messages follow the
specifications detailed in the List of specifications and Data dictionary documents.
5.5.2 Methods of interaction.
The Primary repository will present an http based RestAPI with JSON parameters.
HTTP POST method is used for all calls.
5.5.3 Message format.
The message format is described in the Data Dictionary document, along with some message examples.
EU Secondary List of specifications, Version 1.4.4 73 / 84
5.5.4 Message response
All messages responses must follow the format described in the Secondary repository and Router interface.
5.5.5 Endpoint
Only one endpoint is expected, so all messages are transmitted to that single endpoint
5.5.6 Secured communication
The Primary repository system uses basic authentication or OAuth 2.0 to authorize access to the web service methods.
5.5.7 RecallCode management
RecallCodes must be supported according to the description provided in the Interface section of this document.
5.5.8 Message integrity and hash
The Primary repository system will verify the message checksum to ensure that the data has not tampered with between parts of the whole Repository system as described in the Secondary repository and Router interface.
5.6 II2MN II2DW interfaces
5.6.1 Overview
The ID Issuer defines the communication between the EO and the ID issuer corresponding to interfaces II2MN and II2DW.
5.6.2 Interface Interface
acronym Hosting
system Description II2MN ID issuer
System Secure interface published to Manufacturers and Importers
II2DW ID issuer
System Secure interface published to Distributors and Wholesalers
5.6.3 Synchronous and asynchronous support
The interface allows implementing a synchronous version, where the ID Issuer system will return the result of a request within the same call. This approach is recommended when the business process and the internal validation are fully automated.
The interface also allows implementing an asynchronous version, where the initial call will trigger a request. The ID Issuer system will return a request code for each of these requests and then send a message to transmit the response to the original request.
5.6.4 Extensibility
The interface presents an extensibility field in all messages corresponding to interfaces II2MN and II2DW.
EU Secondary List of specifications, Version 1.4.4 74 / 84
6 Unique Identifier
6.1 Clarification on Structure of unit-level unique identifiers
6.1.1 Clarification on Structure of unit-level unique identifiers (after encoding into a data carrier)
The purpose of this section is to clarify the use of data qualifiers as part of the UI, considering the Implementing Regulation 2018/574 and the applicable international ISO norms.
Please see the following table illustrating the structure of the UI (after encoding it into a data carrier), and the roles of ID issuers and Economic operators in generating and/or applying different data elements and, where applicable, data qualifiers.
(1) (2) (3) (4) (5) (6) (7) (8) (9)
Unique
Identifier Symbology
Identifier Mandatory Data
Identifier Mandatory Data