Upload
others
View
5
Download
0
Embed Size (px)
Citation preview
Sig
na
ture
an
d d
ate
Dup
l. In
v.
No.
Rep
l. In
v.
No.
Sig
na
ture
an
d d
ate
Ori
g.
Inv.
No.
2020
AGREED BY APPROVED BY General Director
CRPT, OOO _______________/ / _______________/ /
______________ 2020 ______________ 2020
OMS-PRODUCTION 3.1
Special Software
Programmer's Guide
Revision 20
RU 15861920.620111-01 33 01
Approval list
2
2
Sig
natu
re a
nd d
ate
Dupl. Inv.
No.
Repl. Inv.
No.
Sig
natu
re a
nd d
ate
Orig.
Inv. N
o.
2020
APPROVED
RU 15861920.620111-01 33 01-AL
OMS-PRODUCTION 3.1
Special Software
RU 15861920.620111-01 33 01
Programmer's Guide
Revision 20
RU 15861920.620111-01 33 01
Sheets 149
2
ANNOTATION
This document «OMS-Production 3.1. Special Software. Programmer’s Guide» RU
15861920.620111-01 33 01 is intended to introduce the functions of application programming
interface of special software (SSW) of automated system “OMS-Production 3.1” (OMS-
Production 3.1 AS). The document is developed as per GOST 19.504-79 “Unified System for
Program Documentation. Programmer’s Guide”.
This document uses the following designations:
1) Elements of screen entry forms are designated as ‹Field›, ‹Button› or ‹Menu item›;
2) PC keyboard keys are designated as [Key]. Combinations of simultaneously pressed
keys are designated as [Key1+Key2].
3) Values to be entered by user into the screen-entry-form elements, as well as system
console commands, are designated as values.
3
CONTENTS
1. PROGRAM PURPOSE ............................................................................................................ 5
1.1.Program Purpose ................................................................................................................. 5
1.2.Program Functions .............................................................................................................. 5
2. PROGRAM APPLICATION ENVIRONMENT ......................................................................... 6
2.1.Applied Hardware ................................................................................................................ 6
2.1.1. Required characteristics of PC for the operation of software component from OMS-Production 3.1 AS SSW executed at OMS-Production 3.1 AS SSW HWC ................... 6
2.1.2. Required characteristics of PC to use “Web-Interface Module” software component from OMS-Production 3.1 AS SSW ...................................................................... 6
2.2.Software required for program functioning ....................................................................... 7
2.2.1. Software required for the functioning of software component from OMS-Production 3.1 AS SSW executed at OMS-Production 3.1 AS SSW HWC ............................ 7
2.2.2. Software required for the functioning of “Web-Interface Module” software component from OMS-Production 3.1 AS SSW ...................................................................... 7
2.3.Software required for program operation .......................................................................... 7
2.3.1. General requirements to request signing ........................................................... 7
2.3.2. Generating GS1 DataMatrix .................................................................................. 9
2.3.3. Requirements JSON-format processing ............................................................. 9
3. PROGRAM CHARACTERISTICS ......................................................................................... 10
3.1.Applicability Indicators ..................................................................................................... 10
3.2.Operation Mode.................................................................................................................. 11
3.3.Means of Correct Operation Control and Self-Restorability of Program ...................... 11
3.3.1. Means of Correct Operation Control ................................................................. 11
3.3.2. Self-Restorability Means .................................................................................... 11
4. PROGRAM CALL.................................................................................................................. 12
4.1.Introduction ........................................................................................................................ 12
4.2.OMS-Method Call Sequences ........................................................................................... 12
4.3.Description of MC-Emission Process .............................................................................. 14
4.3.1. Process “01.01.00.00 Create MC-Emission Order” .......................................... 14
4.3.2. Process “01.02.00.00 Obtain MC-Array Status from Order” ............................ 17
4.3.3. Process “01.03.00.00 Obtain MC from Order” .................................................. 19
4.3.4. Process “01.04.00.00 Send Report on MC-Utilization” .................................... 20
4.4.MC Storage Buffer in OMS ................................................................................................ 22
4.5.OMS API Extensions .......................................................................................................... 23
4.5.1. Method “Create Marking Code Emission Order” ............................................. 24
4.5.2. Method “Send Report on MC Disposal / Rejection”......................................... 45
4.5.3. Method “Send Report on MC-Aggregation” ..................................................... 49
4.5.4. Method “Send Report on MC-Utilization (Application)” .................................. 55
4.5.5. Method “Close the Suborder by the GTIN Specified” ...................................... 64
4.5.6. Method “Obtain MC from Order” ....................................................................... 66
4.5.7. Method “Obtain MC-Array Status from Order” ................................................. 69
4.5.8. Method “Obtain the status of orders” ............................................................... 73
4.5.9. Method “Obtain the Aggregation Information” ................................................ 76
4.5.10. Method “Obtain the Report Processing Status” .............................................. 80
4.5.11. Method “Send APCS Log Files” ........................................................................ 82
4.5.12. Method “Check OMS Availability” ..................................................................... 84
4.5.13. Method “Obtain Security Marker by Username and Password” ..................... 86
4.5.14. Method “Obtain OMS and API Version” ............................................................ 88
4.5.15. Method “Obtain the List of Marking Code Package Identifiers” ..................... 89
4.5.16. Method “Re-obtain Marking Codes from the Marking Code Order” ............... 92
4
4.5.17. Method “Send Report on the Utilization and Automatic Introduction into Circulation” 95
4.5.18. Method “Request for the Document Number of Report on Introduction into Circulation” 102
5. INPUT AND OUTPUT DATA ............................................................................................... 104
5.1.Nature, Arrangement and Initial Preparation of Input and Output Data ...................... 104
5.1.1. Information Sources ......................................................................................... 104
5.1.2. Methods of Data Collection, Transmission, Control and Correction Arrangement .......................................................................................................................... 104
5.2.Format, Description and Encoding Method of the Input and Output Data when Using API106
5.3.Guides Accessible via API .............................................................................................. 107
5.3.1. Guides to Control the Marking Codes ............................................................. 107
6. MESSAGES ........................................................................................................................ 115
6.1.Messages to the Operator transmitted via GUI ............................................................. 115
6.1.1. Information windows ........................................................................................ 115
6.2.Error Format and Codes .................................................................................................. 116
6.2.1. Error format ....................................................................................................... 116
6.2.2. Description of Errors ........................................................................................ 116
7. MATRIX OF PROVISION OF OMS API 2.0 SERVICES BY OMS SOFTWARE PACKAGE COMPONENTS ....................................................................................................................... 118
8. OMS API 2.0 USE EXAMPLES ........................................................................................... 120
8.1.Signing Requests with the Electronic Digital Signature .............................................. 120
8.1.1. Library “CryptoPro JCP” .................................................................................. 120
8.1.2. Example with the Use of Library to Sign the Request ................................... 124
APPENDIX .............................................................................................................................. 126
LIST OF TERMS ..................................................................................................................... 134
LIST OF ABBREVIATIONS .................................................................................................... 141
LIST OF FIGURES .................................................................................................................. 142
LIST OF TABLES .................................................................................................................... 144
5
1. PROGRAM PURPOSE
1.1. Program Purpose
The specialized software is intended to enable the performance of target functions of
OMS-Production 3.1 AS including:
1) Ordering emission of marking codes.
2) Provision of emitted marking codes for application to products.
3) Verification of MC application.
4) Aggregation of ready and packed products with applied identification means (IM).
5) Writing-off of rejected products.
1.2. Program Functions
OMS-Production 3.1 AS SSW enables the following functions:
1) Obtaining orders and providing emitted marking codes.
2) Obtaining notifications on the use (application) of marking codes and recording
marking code status in the Goods Group System.
3) Obtaining notifications on the aggregation of marking codes and recording packed
products aggregation in the Goods Group System.
4) Obtaining notifications on the rejection of marking codes and rejected products
registration in the Goods Group System.
6
2. PROGRAM APPLICATION ENVIRONMENT
2.1. Applied Hardware
2.1.1. Required characteristics of PC for the operation of software component
from OMS-Production 3.1 AS SSW executed at OMS-Production 3.1 AS
SSW HWC
In order to operate a software component from OMS-Production 3.1 AS SSW executed
at OMS-Production 3.1 AS SSW HWC, the following hardware (HW) shall be used:
1) CPU: Intel x86 architecture, clock rate of 3 GHz;
2) Platform: 64-bit;
3) RAM capacity: 16 Gb;
4) Hard-disk drive: 100 GB;
5) Network interface: Ethernet 100 Mbit/s.
Minimum network interface settings for OMS:
1) 1 static IP address;
2) Netmask;
3) Default gateway;
4) DNS settings.
Access to OMS-server:
1) In firewall, SSH-port shall be open (22 by default or another configured by network
administrator), as well as ports for Web-console of Imagenarium software and Web-
interface of OMS-software.
In order to ensure fail-safety, it is recommended to use three clustered physical or
virtual machines. Machines shall have identical configuration. All machines shall have the same
SSH-ports.
2.1.2. Required characteristics of PC to use “Web-Interface Module” software
component from OMS-Production 3.1 AS SSW
To operate the information services provided by OMS-Production 3.1 AS SSW, the
following hardware (HW) shall be used:
1) Non-shared HW:
7
− user AWS with the functional role of “OMS Operator / Administrator” (OMS Operator /
Administrator AWS) that is a PC with characteristics relevant to the recommended
requirements of Microsoft Windows OS 8.1 and later editions, and a network adapter
providing information-and-communication channel with HWC, OMS-Production 3.1 AS.
2.2. Software required for program functioning
2.2.1. Software required for the functioning of software component from OMS-
Production 3.1 AS SSW executed at OMS-Production 3.1 AS SSW HWC
In order to use the system, the server / virtual machine shall have the following basic
programs and components installed:
1) Operating system Linux CentOS 7;
2) SSH Server (authentication mode by name and password);
3) Command-line utility and system program packages: (bash, ifconfig, sysctl, curl, yum,
systemctl, yum-config-manager, unzip).
In order to install OMS-Production 3.1 AS SSW, operating system Linux CentOS 7 shall
be installed, and SSH Server, command-line utility and system program packages, as listed
above shall be set up.
2.2.2. Software required for the functioning of “Web-Interface Module” software
component from OMS-Production 3.1 AS SSW
To operate the information services provided by “Web-Interface Module” software
component from OMS-Production 3.1 AS SSW, the following general software components are
required:
1) Microsoft Windows OS 8.1 and later editions;
2) Web-browser:
− Mozilla Firefox 40 and later versions.
− Internet Explorer 9 and later versions.
− Google Chrome 37 and later versions.
2.3. Software required for program operation
2.3.1. General requirements to request signing
In order to ensure legal value of sent messages by means of OMS API 3.0 interface,
optional parameter X-Signature has been added to the HTTP-header of request to OMS to
include a detached digital signature of request data (GCP’s detached signature is included into
HTTP-header within X-Signature parameter, in Base64 encoding).
8
Signature format is a detached signature in CMS-format. The Cryptographic Message
Syntax, CMS [IETF RFC 5652], is used for digital signature, hashing, authentication and
arbitrary message encryption. CMS utilizes encryption algorithms according to standards
GOST 28147-89, GOST R 34.10-2012 and GOST 34.11-2012, as well as to the document of
Technical Committee “Cryptographic Data Security” (TK 26), ““Information Technology.
Cryptographic Data Security. Standardization Recommendations. Use of Algorithms of GOST
28147-89, GOST R 34.11 and GOST R 34.10 in CMS-Format Cryptographic Messages”.
CMS-values are generated by means of ASN.1 language as per GOST R ISO/IEC
8824-1 using basic encoding rules (BER) as per GOST R ISO/IEC 8825-1.
For testing purposes, a test Certifying Center LLC CRYPTO-PRO will be supported
(https://www.cryptopro.ru/certsrv/).
The circulation participant generates a request, signs it and generates a detached
signature using GCP-certificate. The GCP's detached signature is included into HTTP-header
within X-Signature parameter, in Base64 encoding. Then, circulation participant sends the
request to Operator’s System.
Data Used to Sign HTTP-Requests:
1) For an HTTP-message of GET-type, the signature will utilize the path, including
request string parameters (REQUEST_PATH + QUERY STRING, e.g.
/ordrs?param=..), without consideration of host-name, port or HTTP-headers;
2) For an HTTP message of POST type, signature uses data posted within the message
body and request string parameters (if any).
Circulation participant can also sign orders and reports via OMS user interface.
Currently for such goods groups as “Items of clothing, bed, table, bath and kitchen
linens”, “Footwear”, “Perfume and eau de toilette”, “New pneumatic rubber tires and tire
casings”, “Photo cameras (except cine cameras), flash lights and flash bulbs”, “Dairy products”,
“Bicycles and bicycle frames”, “Wheelchairs”, in cases when order is not signed via API, it shall
be signed via user interface.
When OMS, within an HTTP-header, receives “X-Signature” parameter containing
a detached signature of request and/or message-body parameters, it runs signature validation
and, in case the signature is valid, processes the query, or else returns an error. See below for
an example of detached digital signature included in request.
Table 1 – Example of Request with Handover of a Detached Signature
Description
POST /api/v3/{extension}/orders HTTP/1.1 Accept: application/json clientToken: <-- security marker --> Content-Type: application/json;charset=UTF-8 X-Signature: MIIE5QYJKoZIhvcNAQcCoIIE1jCCBNICAQExDjAMBggqhQMHAQECAgUAMAs GCSqGSIb3DQEHAaCCA64wggOqMIIDWaADAgECAhMSADtoj1yy/t4ybprnAAEAO2iPMAgG
9
Description
BiqFAwICAzB/MSMwIQYJKoZIhvcNAQkBFhRzdXBwb3J0QGNyeXB0b3Byby5ydTELMAkGA1 UEBhMCUlUxDzANBgNVBAcTBk1vc2NvdzEXMBUGA1UEChMOQ1JZUFRPLVBSTyBMTEM xITAfBgNVBAMTGENSWVBUTy1QUk8gVGVzdCBDZW50ZXIgMjAeFw0xOTA5MjkxMzIzMjda Fw0xOTEyMjkxMzMzMjdaMIGuMScwJQYJKoZIhvcNAQkBFhhteWxvbmdsb25nbmFtZUBnbW FpbC5jb20xFTATBgNVBAMMDFZsYWRpbWlyV2ViMjENMAsGA1UECwwEaG9tZTENMAsGA 1UECgwEaG9tZTETMBEGA1UEBwwK0J/QtdC90LfQsDEsMCoGA1UECAwj0J/QtdC90LfQtdC 90YHQutCw0Y8g0L7QsdC70LDRgdGC0YwxCzAJBgNVBAYTAlJVMGYwHwYIKoUDBwEBAQ EwEwYHKoUDAgIkAAYIKoUDBwEBAgIDQwAEQBsvZTPYdD+mZxp1TU8iWNXsC6o5M9YcLJ w4AIludme1J4K9iEjYf/I/rmbjf43Ds2/CKYs/tyvSBSBn2KzBnaOjggF3MIIBczAPBgNVHQ8BAf8E BQMDB/AAMBMGA1UdJQQMMAoGCCsGAQUFBwMDMB0GA1UdDgQWBBSpoGfZxUJ4YK4 RcSViA3G5FkFTrDAfBgNVHSMEGDAWgBROgz4Uae/sXXqVK18R/jcyFklVKzBcBgNVHR8EV TBTMFGgT6BNhktodHRwOi8vdGVzdGNhLmNyeXB0b3Byby5ydS9DZXJ0RW5yb2xsL0NSWV BUTy1QUk8lMjBUZXN0JTIwQ2VudGVyJTIwMigxKS5jcmwwgawGCCsGAQUFBwEBBIGfMIGc MGQGCCsGAQUFBzAChlhodHRwOi8vdGVzdGNhLmNyeXB0b3Byby5ydS9DZXJ0RW5yb2xs L3Rlc3QtY2EtMjAxNF9DUllQVE8tUFJPJTIwVGVzdCUyMENlbnRlciUyMDIoMSkuY3J0MDQGC CsGAQUFBzABhihodHRwOi8vdGVzdGNhLmNyeXB0b3Byby5ydS9vY3NwL29jc3Auc3JmMAg GBiqFAwICAwNBAHIfklsYgixUVKVy75nXFgOK1vnJjJYj3RjK3fwsQFbfmRwkzBVXHF0R/FIvbM mUgTNLC7+Gw3kEsRCZ2tu5yeMxgf0wgfoCAQEwgZYwfzEjMCEGCSqGSIb3DQEJARYUc3V wcG9ydEBjcnlwdG9wcm8ucnUxCzAJBgNVBAYTAlJVMQ8wDQYDVQQHEwZNb3Njb3cxFzAV BgNVBAoTDkNSWVBUTy1QUk8gTExDMSEwHwYDVQQDExhDUllQVE8tUFJPIFRlc3QgQ2Vu dGVyIDICExIAO2iPXLL+3jJumucAAQA7aI8wDAYIKoUDBwEBAgIFADAMBggqhQMHAQEDAg UABEBqxixPd0wnkxB22kdt4fMhdgoH2TaGqwY3u3ZD62LK4WHDX1NbN18mIODeAXOuuZLPz TlWWSKyrHXRBsruvPc0= Content-Length: 783 {body content is omitted}
2.3.2. Generating GS1 DataMatrix
In accordance with the requirements of GS1 General Specification, correct generation of GS1 DataMatrix requires insertion of indication of symbols—ASCII232 in the beginning of the obtained marking code string prior to conversion to DataMatrix; otherwise, technical means will not recognize the code correctly and will be unable to process it correctly. Links to specifications are given below:
1) GS1 General Specification (https://www.gs1.org/docs/barcodes/GS1_General_Specifications.pdf); 2) GS1 DataMatrix Guideline (https://www.gs1.org/docs/barcodes/GS1_DataMatrix_Guideline.pdf ).
2.3.3. Requirements JSON-format processing
As the marking code contains special symbols, circulation participant, while integrating their solutions, shall correctly process JSON-format with tools compliant with RFC 8259, and never process it as Plain Text. The use of tools compliant with RFC 8259 within such solutions ensures marking codes with special symbols are transferred and obtained correctly (special symbols are screened).
Likewise, if circulation participants use XML format in their solutions, the special
symbols contained in a string shall be converted in accordance with XML specifications.
10
3. PROGRAM CHARACTERISTICS
3.1. Applicability Indicators
OMS-Production 3.1 AS SSW ensures implementation of OMS-Production 3.1 target
functions in accordance with the following system applicability indicators:
1) For the list of applicability indicators which OMS 3.1 shall be compliant with, see
Table 2.
Table 2 — List of Applicability Indicators which the System shall be Compliant with
Applicability indicators which OMS shall be compliant with
Indicator value
Quantity of goods items per one marking code order Note*: For goods group category “Medicines for human use”, the quantity of goods items per one marking code order shall not exceed one (1 marking code order = 1 GTIN).
Not exceeding 10
Quantity of marking codes for one goods item (GTIN) per marking code order
Not exceeding 150,000 marking codes
Quantity of marking codes per marking code application report
Not exceeding 30,000 marking codes
Quantity of marking codes per marking code disposal / rejection report.
Not exceeding 30,000 marking codes
11
3.2. Operation Mode
OMS-Production 3.1 AS SSW operation mode is 24/7/365.
3.3. Means of Correct Operation Control and Self-Restorability of Program
3.3.1. Means of Correct Operation Control
Correct operation of OMS-Production 3.1 AS SSW is controlled by means of:
1) Internal diagnostic tools.
2) Validation of corresponding program.
3.3.2. Self-Restorability Means
OMS-Production 3.1 AS SSW is self-restored by means of:
1) Internal restoration tools.
2) Automatic backup tools.
3) Built-in tools of operating system.
12
4. PROGRAM CALL
4.1. Introduction
API REST controller authenticates clients using the so-called client token sent by client
in HTTP-request header. The security marker (ClientToken) is sent in client token HTTP-header
“clientToken”.
Some API-methods use HTTP POST method during data submission. In such cases,
additional HTTP-header indication “Content-Type: application/json” shall be used.
OMS API methods use OMS-identifier “omsId” as parameters; OMS-identifier “omsId” is
available in OMS-settings.
For valid MC-symbols, see Table 3. These symbols shall be used in the following
groups of marking codes data: “Serial Number”, “Key Identifier”, “Verification Code”.
Table 3 – Valid MC-Symbols
Valid MC-symbols. Valid characters IC
ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789!"%&'()*+,-./_:;=<>?
4.2. OMS-Method Call Sequences
The sequence of OMS-method call during the creation of a new MC-order is as follows:
1) Check OMS availability (see cl. 4.5.12).
2) Create marking code emission order (see cl. 4.5.1).
3) Obtain MC-array status from the order (see cl. 4.5.7).
4) Obtain MC from the order (see cl. 4.5.6).
5) Send report on MC-utilization (see cl. 4.5.4).
6) Send report on MC-aggregation (see cl. 4.5.3).
7) Send report on MC-disposal / rejection (see cl. 4.5.2).
For the diagram of OMS-method call sequence, see Figure 1.
OMS API also provides auxiliary methods:
1) Obtain report processing status (see cl. 4.5.10).
2) Send APCS log files (see cl. 4.5.11).
3) Obtain order status (see cl. 4.5.8).
4) Obtain security marker by username and password (see cl. 4.5.13).
5) Close suborder by GTIN specified (see cl. 4.5.5).
6) Obtain OMS and API version (see cl. 4.5.14).
7) Obtain the list of marking code packet identifiers (see cl. 4.5.15).
13
8) Re-obtain marking codes from marking code order (see cl. 4.5.16).
9) Send report on the utilization and automatic introduction into circulation (see
cl. 4.5.17).
10) Request number of report document on introduction into circulation (see cl. 4.5.18).
11) Obtain information on aggregation (see cl. 4.5.9).
Note: if any marking codes are unused when closing an order, a report on marking
code cancellation will be generated and sent.
Automated process control system
(АСУТП)
OMS(СУЗ)
1. Ping OMS (omsId)
HTTP code 200 : omsId
2. Create order for emission IC (omsId, order)
HTTP code 200 : omsId, orderId, expectedCompletionTime
3. Get IC buffer status (omsId, orderId, gtin)
HTTP code 200 : bufferInfo
4. Get ICs from the order (omsId, orderId, gtin, quantity, lastBlockId)
HTTP code 200 : omsId, codes, blockId
5. Send IC utilisation report to OMS(omsId, utilisationReport)
HTTP code 200 : omsId, reportId
6. Send IC aggregation report to OMS (omsId, aggregationReport)
HTTP code 200 : omsId, reportId
7. Send report of dropout IC to OMS (omsId, dropoutReport)
HTTP code 200 : omsId, reportId
OMS-Method Call Sequence
Figure 1
14
4.3. Description of MC-Emission Process
This subsection provides general description of marking code emission process.
General MC-emission process includes four key stages:
1) “01.01.00.00 Create MC-Emission Order”;
2) “01.02.00.00 Obtain MC-Array Status from Order”;
3) “01.03.00.00 Obtain MC from Order”;
4) “01.04.00.00 Send Report on MC-Utilization”.
The process of sending reports on aggregation and disposal / rejection is similar to
the process “01.04.00.00 Send Report on MC-Utilization”.
4.3.1. Process “01.01.00.00 Create MC-Emission Order”
For the diagram of MC-emission order creation process, see Figure 2.
01.01.00.00 «Create order for emission IC»
Emission Registrar Emission ServerAutomated process control
system OMS
Order for emission IC
Create a request containing an order
for issuing IC
Get the result of processing the
request
Yes
Create response message
Check request
Any mistakes?
No
Any mistakes?
Request an IC issued by the Emission Server
No
Create a business order for the emission
of IC
Order for emission IC
Check request
Process order of emission IC
Check order of emission IC
Any mistakes?
No
Create error message
Yes
Yes
Завершение
Any mistakes?
Check for errors
Log an error in the log
Yes
No
Check for errors
Any mistakes?
Create error message
Yes
Get the result of processing the
request
Log an error in the log
Check for errors
Create IC array
No
Create response message
Log an error in the log Assign an order ID
Calculate order ready time
Create pool IC
Waiting for order ready
Request an IC In the Emission Registrar
01.02.00.00 «Get IC buffer status»
Waiting for order ready
Save business order data
Process “Create MC-Emission Order”
Figure 2
Description:
1) APCS generates an order and sends it to OMS;
2) OMS verifies the request and sends order to Emission Registrar;
15
3) Emission Registrar generates a request containing the MC-emission order and sends
it to Emission Server;
4) Upon obtaining request containing MC-emission order, Emission Server verifies
the request.
− In case of any errors within the request, Emission Server registers them in a log;
− Emission Server generates an error message and sends it to Emission Registrar;
− Moving to Step 8) of main scenario.
5) In case of no errors, Emission Server verifies MC-emission order.
− In case of any errors within the request, Emission Server registers them in a log;
− Emission Server generates an error message and sends it to Emission Registrar;
− Moving to Step 8) of main scenario.
6) In case of no errors within the MC-emission order, Emission Server assigns
an identifier to the order and calculates order completion time;
− Emission Server sends the order for processing (the action is asynchronous);
7) Emission Server generates a response message and sends it to Emission Registrar;
8) Emission Registrar verifies request processing result;
9) Emission Registrar performs check for errors:
− In case of any errors within the message, Emission Server registers them in a log;
− Emission Registrar generates an error message and sends it to OMS;
− Moving to Step 12) of main scenario.
10) In case of no errors, Emission Registrar generates an empty MC-pool;
− Emission Registrar waits for the order completion time and requests emitted MC from
Emission Server (the action is asynchronous).
11) Emission Registrar sends a response message to OMS;
12) OMS obtains request processing result from Emission Registrar;
13) OMS performs check for errors;
− In case of any errors, OMS registers them in a log;
− OMS generates an error message and sends it to APCS;
− Moving to Step 16) of main scenario.
14) In case of no errors, OMS creates an MC-array;
− OMS waits for the order completion time and requests emitted MC from Emission
Registrar (the action is asynchronous).
15) OMS generates a response message and sends it to APCS;
16) APCS obtains request processing result from OMS;
16
17) APCS performs check for errors;
− In case of any errors, APCS registers them in a log;
− The process is terminated.
18) In case of no errors, APCS saves order data;
− APCS initiates process 01.02.00.00 “Obtain MC-Array Status from Order” (the action
is asynchronous).
19) The process is terminated.
17
4.3.2. Process “01.02.00.00 Obtain MC-Array Status from Order”
For the diagram of MC-array status obtainment process, see Figure 3.
01.02.00.00 «Get IC buffer status»
Automated process control system OMS
Order ID and GTIN
Create a IC status request from a business order
Request IC s tatus from business order
Check request
End
Any mistakes?
Check for errors
Log an error in the log
YesNo
Check for errors
Any mistakes?
Create error message
Yes
Get information about the IC array
No
Create response message
Waiting for order ready
01.03.00.00 «Get ICs from the order»
Yes
Is the CM buffer s tatus «PENDING»?
Log an error in the log
Is the IC buffer status «ACTIVE»?
No
No
Yes
The response message includes information about the buffer and IC arrays.
Process “Obtain MC-Array Status from Order”
Figure 3
Description:
1) APCS waits for order completion time;
2) APCS generates a request to obtain MC-array status and sends it to OMS;
3) OMS verifies the request;
4) OMS performs check for errors:
− In case of any errors within the request, OMS registers them in a log;
− OMS generates an error message and sends it to APCS;
18
− Moving to Step 7 of main scenario.
5) OMS obtains information on MC-array;
6) OMS generates a response message and sends it to APCS;
7) APCS receives response message;
8) APCS performs check for errors:
− In case of any errors within the request, APCS registers them in a log;
− The process is terminated.
9) In case of no errors, APCS checks that MC-buffer status is “PENDING”:
− In case the MC-buffer status is “PENDING”, APCS initiates repeated request for MC-
array status.
− Moving to Step 1 of main scenario.
10) In case of no errors, APCS checks that MC-buffer status is “ACTIVE”:
− In case MC-buffer status is not “ACTIVE”, the process is terminated
11) In case MC-buffer status is “ACTIVE”, APCS initiates process 01.03.00.00 “Obtain
MC from Order” (the action is asynchronous);
12) The process is terminated.
19
4.3.3. Process “01.03.00.00 Obtain MC from Order”
For the diagram of MC obtainment from business order process, see Figure 4.
01.03.00.00 «Get ICs from the order»
Automated process control system OMS
Order Id, GTIN and number of codes requested
Create a request to receive ICs from a
business order
Request IC from Business order
Check request
End
Any mistakes?
Check for errors
Log an error in the log
YesNo
Check for errors
Any mistakes?
Create error message
Yes
Generate an array of emitted IC
No
Create response message
Yes
Is there more IC in the order?
Log an error in the log
Need to download IC from your order?
Yes
No
No
Process response message
The Response message includes information about the buffer and arrays of IC
Emitted KM are loaded by blocks, when the next block is loaded, the request must specify the parameter "lastBlockId"- the Id of the code block issued in the previous request.
Process “Obtain MC from Order”
Figure 4
Description:
1) APCS generates a request to obtain MC from business order and sends it to OMS;
2) OMS verifies the request;
3) OMS performs check for errors:
− In case of any errors within the request, OMS registers them in a log;
− OMS generates an error message and sends it to APCS;
− Moving to Step 6 of main scenario.
4) OMS generates an array of emitted MC;
5) OMS generates a response message and sends it to APCS;
6) APCS receives response message;
20
7) APCS performs check for errors:
− In case of any errors within the request, APCS registers them in a log;
− The process is terminated.
8) APCS processes the received message.
9) APCS checks for any other MC in the order.
− In case there are no other MC in the order, the process is terminated.
10) In case the order contains other MC, APCS checks whether the remaining MC
should be downloaded.
− In case the MC remaining in the order should be downloaded, APCS re-initiates
process 01.03.00.00 “Obtain MC from Order”;
− Moving to Step 1 of main scenario.
11) In case the remaining MC do not have to be downloaded, the process is terminated.
4.3.4. Process “01.04.00.00 Send Report on MC-Utilization”
For the diagram of MC-utilization report sending process, see Figure 5.
01.04.00.00 «Send IC utilisation report to OMS»
Emission Registrar Emission ServerAutomated process
control system OMS
Marking Information System
Report
Generate a request containing a report
Get the result of processing the
request
Yes
Report
Create response message
Check request
Any mistakes?
No
Any mistakes?
No
IC utilisation report
Create request
IC utilisation report
Check request
Create error message
Yes
Any mistakes?
Check for errors
Log an error in the log
Yes No
Check for errors
Any mistakes?
Create error message
Yes
Get the result of processing the
request
Log an error in the log
Check for errors
No
Create response message
Log an error in the log
Assign a report id
Create response message
Process report
Create error message
Log an error in the log
If there are no errors, the response message
contains the report identifier.
Process “Send Report on MC-Utilization”
Figure 5
Description:
1) APCS generates a request containing MC-utilization report and sends it to OMS;
21
2) OMS verifies the request and sends the request containing MC-utilization report to
Emission Registrar;
3) Emission Registrar generates a request containing the MC-utilization report and
sends it to Emission Server;
4) Upon obtaining request containing MC-utilization report, Emission Server verifies
the request.
− In case of any errors within the request, Emission Server registers them in a log;
− Emission Server generates an error message and sends it to Emission Registrar;
− Moving to Step 7 of main scenario.
5) In case of no errors, Emission Server assigns an identifier to the report;
− Emission Server sends the report for processing to TT IS (the action is
asynchronous);
6) Emission Server generates a response message and sends it to Emission Registrar;
7) Emission Registrar verifies request processing result;
8) Emission Registrar performs check for errors:
− In case of any errors within the message, Emission Server registers them in a log;
− Emission Registrar generates an error message and sends it to OMS;
− Moving to Step 10 of main scenario.
9) In case of no errors, Emission Registrar generates a response message and sends it
to OMS;
10) OMS obtains request processing result from Emission Registrar;
11) OMS performs check for errors;
− In case of any errors, OMS registers them in a log;
− OMS generates an error message and sends it to APCS;
− Moving to Step 13 of main scenario.
12) In case of no errors, OMS generates a response message and sends it to APCS;
13) APCS obtains request processing result from OMS;
14) APCS performs check for errors;
− In case of any errors, APCS registers them in a log;
− The process is terminated.
15) In case of no errors, APCS saves report identifier, the process is terminated.
22
4.4. MC Storage Buffer in OMS
In order to ensure the necessary performance for high-speed manufacturing lines, OMS
stores a small buffer with marking codes for each item of nomenclature in the order. The size of
code block available from OMS for a certain nomenclature item in one instance is limited to the
size of buffer. It can be adjusted to the manufacturing needs. For the structure of marking code
storage in OMS, see Figure 6. This storage structure ensures fail safety of marking codes
emission unit at manufacturing site.
Emission Registrar 2
MC Storage
MC Order
GTIN 1
MC Buffer
GTIN 2
MC Buffer
GTIN 3
MC Buffer
Suborder 1
Suborder 2
Emission Task 1.1
Emission Task 1.2
Emission Task 2.1
Emission Task 2.2
Emission Registrar 1
MC Storage
Suborder 3
Emission Task 3.1
Emission Task 3.2
MC Order Distribution between ERs
Figure 6
23
4.5. OMS API Extensions
OMS API supports extensions for pharmaceutical, tobacco and light industries. OMS
API extensions are accessible via URL.
OMS API URL-structure has the following parameters:
http://<server-name>[:server-port]/api/v2/{extension}/
these parameters have the following purpose:
1) server-name – server name or IP-address.
2) server-port – connection port.
3) extension – URL-parameter defining access to extensions of OMS API.
The URL-parameter extension that determines access to extensions of goods groups
has the following default values:
1) light – URL-parameter extension for light industry.
2) pharma – URL-parameter extension for pharmaceutical industry.
3) tobacco – URL-parameter extension for tobacco industry.
4) tires – URL-parameter extension for tire manufacturers.
5) photo – URL-parameter extension for photo products manufacturers.
6) perfum – URL-parameter extension for perfumery products manufacturers.
7) milk – URL-parameter extension for dairy manufacturers;
8) bicycle – URL-parameter extension for bicycle and bicycle-frame manufacturers;
9) wheelchairs – URL-parameter extension for wheelchair manufacturers.
24
4.5.1. Method “Create Marking Code Emission Order”
This method is used to create and send marking code emission orders. OMS generates
a security marker (token) during OMS-client registration. Security marker (token) is sent to
server within HTTP-header with name “clientToken”.
Notes*:
1) one goods item (GTIN) within one marking code order shall not exceed 150,000
marking codes, and the quantity of goods items per one marking code order shall not exceed 10
(1 order = 10 GTIN).
For pharmaceutical industry, the quantity of goods items per one order shall not exceed 1
(1 business order = 1 GTIN).
2) the quantity of active orders cannot exceed 100 at once. Active orders include those
orders with status READY that have at least one sub-order (MC-buffer) with status ACTIVE,
PENDING or EXHAUSTED.
A queue can also contain not more than 100 orders. These orders include orders with
statuses CREATED, PENDING, APPROVED.
If one of the limits is reached, no orders can be created.
3) due to cl. 2, this method cannot be called from one source more often than 100 times
per second.
4.5.1.1. Request
REST Request Parameters
URL: http://<server-name>[:server-
port]/api/v2/{extension}/orders?omsId={omsId}
Method:POST
Content-type:application/json
clientToken:{clientToken}
For request string parameters, see Table 4.
Table 4 – Request String Parameters
Parameter Description Type Mandatory
omsId Unique OMS identifier String (UUID) Yes
For the description of JSON format of request for creation and sending of order for MC
emission (object “Order”), see Table 5.
Table 5 – Description of JSON Format of Request for Creation and Sending of MC Emission Order, object “Order”
Field Description Type Mandatory
products List of goods. JSON Array of OrderProduct
(Table 6) Yes
25
For the description of format of object “OrderProduct", see Table 6.
Table 6 – Format of Object “OrderProduct”
Field Description Type Mandatory
gtin Product GTIN String (14) [0-
9]{14} Yes
quantity MC quantity Integer ($int32)
Yes
serialNumberType Serial number generation method.
String (Guide No. 2)
Yes
serialNumbers
Serial number array. Specify this field if value is “serialNumber = SELF_MADE” (see section 5.3.1.2).
JSON Array of String*
No Conditionally mandatory
templateId MC template identifier Integer ($int32)
(Guide No. 5) Yes
Note: for the “Tobacco Products” goods group, the initially set generation scheme and
MC-template structure for the exact goods type (GTIN) defined by attribute “serialNumberType”
cannot be changed later.
26
4.5.1.1.1 Extensions for Tobacco Industry
For the description of extension for object “OrderProduct” for tobacco industry, see
Table 7.
Table 7 – Description of Extension for Object “OrderProduct” for Tobacco Industry
Field Description Type Mandatory
mrp Maximum retail price String (4-6) Yes
Note*: Field “mrp” (Maximum retail price) is mandatory, the maximum retail price shall be
indicated in kopecks, up to ones, e.g. if the price is 105 rubles and 1 kopeck, that makes 10501.
For a carton this is the sum of all packs, also in kopecks.
For the description of extension for object “Order” for tobacco industry, see Table 8.
Table 8 – Description of Extension for Object “Order” for Tobacco Industry
Field Description Type Mandatory
factoryId Factory identifier. (Global location number)
String Yes
factoryName Factory name String No
factoryAddress Factory address String No
factoryCountry Factory country String Yes
productionLineId Production line identifier String Yes
productCode Product code (SKU) String Yes
productDescription Product description String Yes
poNumber Production order number String No
expectedStartDate Start date for production under this order.
String (yyyy-mm-dd)
No
27
For an example of REST-request (for tobacco industry), see Figure 7.
POST /api/v2/tobacco/orders?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Content-Length: 718 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Type: application/json;charset=UTF-8 Host: localhost:8080 { "products":[ { "gtin":"01334567894339", "quantity" : 20, "serialNumberType" : "SELF_MADE", "serialNumbers" : [ "Z9bmNYR", "8i8PjF3", "JTyZqzO", "cXypJQe", "GTRnsaw", "5SIMTDk", "s6oi9Dp", "3TgycS6", "B4ZHoMZ", "5rnFx84", "JeOzqDR", "WyDWOLm", "HbkGP2s", "iO7yrJf", "cr6ZTiq", "1WrGk77", "52pCNKw", "Wkyrj8D", "ZnAMQTE", "kJMXFAB" ], "templateId" : 3, "mrp" : 31055}], "factoryId":"Identifier", "factoryName":"Tobacco Fac", "factoryAddress":"Address", "factoryCountry":"Country", "productionLineId":"1", "productCode":"6789", "productDescription":"Simple ", "poNumber":"12345", "expectedStartDate":"2019-03-01" }
Example of REST Request (for Tobacco Industry)
Figure 7
28
4.5.1.1.2 Extensions for Light Industry—Goods Group Category “Items of Clothing, Bed,
Table, Bath and Kitchen Linen”
For the description of extension for object “Order” for goods group category “Items of
Clothing, Bed, Table, Bath and Kitchen Linen”, see Table 9.
Table 9 – Description of Extension for Object “Order” for Goods Group Category “Items of Clothing, Bed, Table, Bath and Kitchen Linen”
Field Description Type Mandatory
contactPerson Contact person String Yes
releaseMethodType Method of goods release into circulation
Guide No. 1 Yes
createMethodType IM creation method Guide No. 4 Yes
productionOrderId Production order identifier String No
contractNumber Number of contract with operator (this field is not used) *
String No
contractDate Date of contract with operator (this field is not used) *
String (yyyy-mm-dd)
No
Note*: the values “CROSSBORDER” in catalog “Method of Goods Release into
Circulation” is invalid for goods category “Items of Clothing, Bed, Table, Bath and Kitchen Linen”
Starting from 1/1/2020, fields “contractNumber” and “contractDate” will be excluded (these fields
are marked as not used).
For the description of “OrderProduct” object extension for light industry of goods group
category “Items of clothing, bed, table, bath and kitchen linen”, see the table below (Table 10).
Table 10 – Description of “OrderProduct” Object Extension for Light Industry of Goods Group Category “Items of Clothing, Bed, Table, Bath and Kitchen Linen”
Field Description Type Mandatory
cisType Marking code type Guide No. 13 Yes
29
For the description of REST-request for goods group category “Items of Clothing, Bed,
Table, Bath and Kitchen Linen”, see Figure 8.
POST /api/v2/light/orders?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Type: application/json;charset=UTF-8 Content-Length: 783 Host: localhost:8080 { "products" : [ { "gtin" : "01334567894339", "quantity" : 20, "serialNumberType": "SELF_MADE", "serialNumbers": [ "QIQ8BQCXmSJJe", "GLTP9kqZn5QRt", "2Xg3Cz3KFIjDI","ETpOsXYzKgFJf","TrjipM76LBfkO","ZyLajXcsKCKEt", "zXo2z7aAib4f3","kDEGDIQemE9IE","sFHNXi4Ss6D4D","iOpbrH3AAObaw", "LL8GyS1szEs8b","DZSzdNOoBZgsW","mpF7K5pY5jBIo","9xiZObR1Lf8tb", "zFH93Lrww6dn5","9siRZSs7Jrobq","tp6CYNzDSnk9a","961RmCQ3GFFNQ", "xmWOa5g7zbgFm","M3fAgZdGrStA8"], "templateId": 10, "cisType": "UNIT" } ], "contactPerson":"Иванов П.А.", "releaseMethodType": "PRODUCTION", "createMethodType": "SELF_MADE", "productionOrderId": "08528091-808a-41ba-a55d-d6230c64b332", "contractNumber":"4689725647", "contractDate":"2019-09-12"
Example of REST Request for Light Industry, Goods Group Category “Items of Clothing, Bed, Table, Bath and Kitchen Linen”
Figure 8
30
4.5.1.1.3 Extensions for Light Industry—Goods Group Category “Footwear”
For the description of extension for object “Order” for light industry, goods group category
“Footwear”, see Table 11.
Table 11 – Description of Extension for Object “Order” for Light Industry, Goods Group Category “Footwear”
Field Description Type Mandatory
contactPerson Contact person String Yes
releaseMethodType Method of goods release into circulation
Guide No. 1 Yes
createMethodType IM creation method Guide No. 4 Yes
productionOrderId Production order identifier String No
contractNumber Number of contract with operator (this field is not used) *
String No
contractDate Date of contract with operator (this field is not used) *
String (yyyy-mm-dd)
No
remainsAvailable
Attribute of goods manufactured / purchased prior to 7/1/2020 (date of prohibition on circulation of unmarked goods of the GG). Mandatory when specifying the introduction-into-circulation method “REMAINS” (leftovers marking). Valid values:
− true for goods manufactured / purchased prior to 7/1/2020;
− false for others. Note: an order with introduction-into-circulation method "REMAINS" for the goods group "Footwear" can be created only for those goods that were purchased / manufactured prior to 7/1/2020
boolean No
Conditionally mandatory
remainsImport
Attribute of foreign-made goods imported into the Russian Federation after 7/1/2020 (date of
boolean No
Conditionally mandatory
31
Field Description Type Mandatory
prohibition on circulation of unmarked goods of the GG). Mandatory when specifying the introduction-into-circulation method “REMAINS” (“Leftovers marking”). Valid values:
− true – imported goods (imported into the Russian Federation after 7/1/2020);
− false for others. Note: for imported goods (imported into the Russian Federation after 7/1/2020), an order with introduction-into-circulation method "REMAINS” will be creatable till 8/1/2020, otherwise till 9/1/2020
Note*: Starting from 1/1/2020, fields “contractNumber” and “contractDate” will be
excluded (these fields are marked as not used).
Example of REST-request for light industry, goods group category “Footwear”.
For the description of extension for object “OrderProduct” for GG “Footwear”, see
Table 12.
Table 12 – Description of Extension for Object “OrderProduct” for GG “Footwear”
Field Description Type Mandatory
exporterTaxpayerId Exporter’s TIN/UNB (or equivalent)
String No*
Note*: The field “exporterTaxpayerId” becomes mandatory when value
“CROSSBORDER” (imported into the Russian Federation from EEU countries) was selected in
the field “releaseMethod” (method of goods release into circulation).
32
For an example of REST-request for light industry, goods group category “Footwear”, see
Figure 9.
POST /api/v2/light/orders?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Type: application/json;charset=UTF-8 Content-Length: 783 Host: localhost:8080 { "products" : [ { "gtin" : "01334567894339", "quantity" : 20, "serialNumberType": "SELF_MADE", "serialNumbers": [ "QIQ8BQCXmSJJe", "GLTP9kqZn5QRt", "2Xg3Cz3KFIjDI","ETpOsXYzKgFJf","TrjipM76LBfkO","ZyLajXcsKCKEt", "zXo2z7aAib4f3","kDEGDIQemE9IE","sFHNXi4Ss6D4D","iOpbrH3AAObaw", "LL8GyS1szEs8b","DZSzdNOoBZgsW","mpF7K5pY5jBIo","9xiZObR1Lf8tb", "zFH93Lrww6dn5","9siRZSs7Jrobq","tp6CYNzDSnk9a","961RmCQ3GFFNQ", "xmWOa5g7zbgFm","M3fAgZdGrStA8"], "templateId": 1, "exporterTaxpayerId ": "123456789" } ], "contactPerson":"Иванов П.А.", "releaseMethodType": "CROSSBORDER", "createMethodType": "SELF_MADE", "productionOrderId": "08528091-808a-41ba-a55d-d6230c64b332", "contractNumber":"4689725647", "contractDate":"2019-09-12" }
Example of REST Request for Light Industry, Goods Group Сategory “Footwear”
Figure 9
33
4.5.1.1.4 Extensions for Tire Manufacturers—Goods Group Category “New Pneumatic
Rubber Tires and Tire Casings”
For the description of extension for object “Order” for tire manufacturers, goods group
category “New Pneumatic Rubber Tires and Tire Casings”, see Table 13.
Table 13 – Description of Extension for Object “Order” for Tire Manufacturers, Goods Group Category “New Pneumatic Rubber Tires and Tire Casings”
Field Description Type Mandatory
contactPerson Contact person String Yes
releaseMethodType Method of goods release into circulation
Guide No. 1* Yes
createMethodType IM creation method Guide No. 4 Yes
productionOrderId Production order identifier String No
contractNumber Number of contract with operator (this field is not used)
String No
contractDate Date of contract with operator (this field is not used)
String (yyyy-mm-dd)
No
Note*: the values “CROSSBORDER” in catalog “Method of Goods Release into
Circulation” is invalid for goods category “New Pneumatic Rubber Tires and Tire Casings”
Starting from 1/1/2020, fields “contractNumber” and “contractDate” will be excluded (these fields
are marked as not used).
34
For an example of REST-request for tire manufacturers, goods group category “New
Pneumatic Rubber Tires and Tire Casings”, see Figure 10.
POST /api/v2/tires/orders?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Type: application/json;charset=UTF-8 Content-Length: 783 Host: localhost:8080 { "products" : [ { "gtin" : "01334567894339", "quantity" : 20, "serialNumberType": "SELF_MADE", "serialNumbers": [ "QIQ8BQCXmSJJe", "GLTP9kqZn5QRt", "2Xg3Cz3KFIjDI","ETpOsXYzKgFJf","TrjipM76LBfkO","ZyLajXcsKCKEt", "zXo2z7aAib4f3","kDEGDIQemE9IE","sFHNXi4Ss6D4D","iOpbrH3AAObaw", "LL8GyS1szEs8b","DZSzdNOoBZgsW","mpF7K5pY5jBIo","9xiZObR1Lf8tb", "zFH93Lrww6dn5","9siRZSs7Jrobq","tp6CYNzDSnk9a","961RmCQ3GFFNQ", "xmWOa5g7zbgFm","M3fAgZdGrStA8"], "templateId": 7 } ], "contactPerson":"Иванов П.А.", "releaseMethodType": "PRODUCTION", "createMethodType": "SELF_MADE", "productionOrderId": "08528091-808a-41ba-a55d-d6230c64b332", "contractNumber":"4689725647", "contractDate":"2019-09-12" }
Example of REST Request for Light Industry, Goods Group Category “New Pneumatic Rubber Tires and Tire Casings”
Figure 10
35
4.5.1.1.5 Extensions for Perfumery Products Manufacturers—Goods Group Category
“Perfume and Eau de Toilette”
For the description of extension for object “Order” for the perfumery products
manufacturers, goods group category “Perfume and Eau de Toilette”, see Table 14.
Table 14 – Description of Extension for Object “Order” for Perfumery Products Manufacturers, Goods Group Category “Perfume and Eau de Toilette”
Field Description Type Mandatory
contactPerson Contact person String Yes
releaseMethodType Method of goods release into circulation
Guide No. 1* Yes
createMethodType IM creation method Guide No. 4 Yes
productionOrderId Production order identifier String No
contractNumber Number of contract with operator (this field is not used)
String No
contractDate Date of contract with operator (this field is not used)
String (yyyy-mm-dd)
No
Note*: the values “REMAINS” and “CROSSBORDER” in catalog “Method of Goods
Release into Circulation” are invalid for goods category “Perfume and Eau de Toilette” Starting
from 1/1/2020, fields “contractNumber” and “contractDate” will be excluded (these fields are
marked as not used).
For the description of “OrderProduct” object extension for the perfumery manufacturers of
goods group category “Perfume and eau de toilette”, see the table below (Ошибка! Источник
ссылки не найден.).
Table 15 – Description of “OrderProduct” Object Extension for the Perfumery Manufacturers of Goods Group Category “Perfume and Eau De Toilette”
Field Description Type Mandatory
cisType Marking code type Guide No. 13 Yes
36
For an example of request for the perfumery products manufacturers, goods group
category “Perfume and Eau de Toilette”, see Figure 11.
POST /api/v2/tires/orders?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Type: application/json;charset=UTF-8 Content-Length: 783 Host: localhost:8080 { "products" : [ { "gtin" : "01334567894339", "quantity" : 20, "serialNumberType": "SELF_MADE", "serialNumbers": [ "QIQ8BQCXmSJJe", "GLTP9kqZn5QRt", "2Xg3Cz3KFIjDI","ETpOsXYzKgFJf","TrjipM76LBfkO","ZyLajXcsKCKEt", "zXo2z7aAib4f3","kDEGDIQemE9IE","sFHNXi4Ss6D4D","iOpbrH3AAObaw", "LL8GyS1szEs8b","DZSzdNOoBZgsW","mpF7K5pY5jBIo","9xiZObR1Lf8tb", "zFH93Lrww6dn5","9siRZSs7Jrobq","tp6CYNzDSnk9a","961RmCQ3GFFNQ", "xmWOa5g7zbgFm","M3fAgZdGrStA8"], "templateId": 9, "cisType": "UNIT" } ], "contactPerson":"Иванов П.А.", "releaseMethodType": "PRODUCTION", "createMethodType": "SELF_MADE", "productionOrderId": "08528091-808a-41ba-a55d-d6230c64b332", "contractNumber":"4689725647", "contractDate":"2019-09-12" }
Example of REST Request for Perfumery Products Manufacturers, Goods Group Category “Perfume and Eau de Toilette”
Figure 11
37
4.5.1.1.6 Extensions for Photo Products Manufacturers—Goods Group Category “Photo
Cameras (Except Cine Cameras), Flash Lights and Flash Bulbs”
For the description of extension for object “Order” for the photo products manufacturers,
goods group category “Photo Cameras (Except Cine Cameras), Flash Lights and Flash Bulbs”,
see Table 16.
Table 16 – Description of Extension for Object “Order” for Photo Products Manufacturers, Goods Group Category “Photo Cameras (Except Cine Cameras), Flash Lights and Flash Bulbs”
Field Description Type Mandatory
contactPerson Contact person String Yes
releaseMethodType Method of goods release into circulation
Guide No. 1 Yes
createMethodType IM creation method Guide No. 4 Yes
productionOrderId Production order identifier String No
contractNumber Number of contract with operator (this field is not used)
String No
contractDate Date of contract with operator (this field is not used)
String (yyyy-mm-dd)
No
Note*: the value “CROSSBORDER” in catalog “Method of Goods Release into
Circulation” is invalid for goods category “Photo Cameras (Except Cine Cameras), Flash Lights
and Flash Bulbs” Starting from 1/1/2020, fields “contractNumber” and “contractDate” will be
excluded (these fields are marked as not used).
For the description of “OrderProduct” object extension for the manufacturers of photo
products of goods group category “Photo cameras (except for cine cameras), flash lights and
flash bulbs”, see the table below (Table 17 – Description of “OrderProduct” Object Extension for
the Manufacturers of Photo Products of Goods Group Category “Photo Cameras (Except for
Cine Cameras), Flash Lights and Flash Bulbs”).
Table 17 – Description of “OrderProduct” Object Extension for the Manufacturers of Photo Products of Goods Group Category “Photo Cameras (Except for Cine Cameras), Flash Lights and Flash Bulbs”
Field Description Type Mandatory
cisType Marking code type Guide No. 13 Yes
38
For an example of REST-request for the photo products manufacturers, goods group
category “Photo Cameras (Except Cine Cameras), Flash Lights and Flash Bulbs”, see Figure
12.
POST /api/v2/photo/orders?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Type: application/json;charset=UTF-8 Content-Length: 783 Host: localhost:8080 { "products" : [ { "gtin" : "01334567894339", "quantity" : 20, "serialNumberType": "SELF_MADE", "serialNumbers": [ "QIQ8BQCXmSJJe", "GLTP9kqZn5QRt", "2Xg3Cz3KFIjDI","ETpOsXYzKgFJf","TrjipM76LBfkO","ZyLajXcsKCKEt", "zXo2z7aAib4f3","kDEGDIQemE9IE","sFHNXi4Ss6D4D","iOpbrH3AAObaw", "LL8GyS1szEs8b","DZSzdNOoBZgsW","mpF7K5pY5jBIo","9xiZObR1Lf8tb", "zFH93Lrww6dn5","9siRZSs7Jrobq","tp6CYNzDSnk9a","961RmCQ3GFFNQ", "xmWOa5g7zbgFm","M3fAgZdGrStA8"], "templateId": 8, "cisType": "UNIT" } ], "contactPerson":"Иванов П.А.", "releaseMethodType": "PRODUCTION", "createMethodType": "SELF_MADE", "productionOrderId": "08528091-808a-41ba-a55d-d6230c64b333", "contractNumber":"4689725648", "contractDate":"2019-09-12" }
Example of REST Request for Photo Products Manufacturers, Goods Group Category “Photo Cameras (Except Cine Cameras), Flash Lights and Flash Bulbs”
Figure 12
39
4.5.1.1.7 Extensions for Pharmaceutical Industry
For the description of extension for object “Order” for pharmaceutical industry, see
Table 18.
Table 18 – Description of Extension for Object “Order” for Pharmaceutical Industry
Field Description Type Mandatory
subjectId Pharmaceutical entity. Number assigned upon registration in MDLP FGIS.
String (36) GUID
Yes
freeCode
MC emission payment attribute.
− true means non-payable MC;
− false means payable MC (default value)
boolean No
paymentType
Payment type Valid values:
− 1 for payment upon emission;
− 2 for payment upon application (default value).
Int32 No
For an example of REST-request (for pharmaceutical industry), see Figure 13.
POST /api/v2/pharma/orders?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Length: 559 Content-Type: application/json;charset=UTF-8 Host: localhost:8080 { "freeCode": false, "paymentType": 2, "products" : [ { "gtin" : "01334567894339", "quantity" : 20, "serialNumberType" : "SELF_MADE", "serialNumbers" : [ "77X4DdOGGDc9d", "6KfL3i7igypkd", "oBtEYaq1HCxHN", "kRGmTQoeOckPx", "KHnFN1fj7NmL6", "LSsbD7BrWRyFX", "rEw3MOgC86H4w", "7WQ4FZapQpacq", "Qaty1C5Imop1O", "mSWjzXd5axLRj", "2sneq3ZzQPxRD", "m6edPWjxsTc6R", "pIfdgy1XyYIkx", "CTQzSe9ZTormg", "dock4TYN5HSkW", "ZA6AITKGQNfO1", "AJfr6XoYxRIHE", "GpxniqfHc6iBA", "57gx4I7fj8J58", "iQ4PtkYIYfxKL" ], "templateId":5 } ], "subjectId ":"65468245-fb47-4c8a-af3d-d3486ead8c4a" }
Example of REST Request (for Pharmaceutical Industry)
Figure 13
40
4.5.1.1.8 Extensions for Dairy Manufacturers
For the description of extension for object “OrderProduct” for dairy manufacturers, see
Table 19.
Table 19 – Description of Extension for Object “Order” for the Dairy Manufacturers
Field Description Type Mandatory
expDate Product expiration date (shelf life exceeding 72 hours)
String (6) (YYMMDD)
No Conditionally mandatory
expDate72 Product expiration date (shelf life under 72 hours)
String (10) (YYMMDDHHMM)
No Conditionally mandatory
Notes:
1) depending on dairy product shelf life, the field to be filled is either “expDate” or
“expDate72” (data on product expiration date may be left out, but in this case product
expiration date will not be included in the marking code):
− for products with shelf life exceeding 72 hours, the attribute to be filled is “expDate”
comprised of 6 digits in YYMMDD-format containing the product expiration date;
− for products with shelf life under 72 hours, the field to be filled is “expDate72” comprised
of 10 digits in YYMMDDHHMM-format containing the product expiration date and time;
− when both fields are filled, an error occurs “Only one field to be filled: “expDate” or
“expDate72”.
2) values “expDate” and ”expDate72” shall not be before the start of current date
(00:00:00) and not later than 36 months since the current date.
For the description of extension for object “Order” for dairy manufacturers, goods group
category “Dairy Products”, see Table 20.
Table 20 – Description of Extension for Object “Order” for the Dairy Manufacturers
Field Description Type Mandatory
contactPerson Contact person String Yes
releaseMethodType Method of goods release into circulation
Guide No. 1 Yes
createMethodType IM creation method Guide No. 4 Yes
productionOrderId Production order identifier String No
Note*: the values “REMAINS”, “CROSSBORDER” and “IMPORT” in catalog “Method of
goods release into circulation” are invalid for goods category “Dairy Products”.
41
For an example of REST-request (for dairy manufacturers), see Figure 14.
POST /api/v2/milk/orders?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Content-Length: 718 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Type: application/json;charset=UTF-8 Host: localhost:8080 { "products":[ { "gtin":"04603721568000", "quantity" : 5, "serialNumberType" : "SELF_MADE", "serialNumbers" : [ "MZX78RZ9bmNYR", "MZX78R8i8PjF3", "MZX78RJTyZqzO", "MZX78RZnAMQTE", "MZX78RkJMXFAB" ], "templateId" : 6, "expDate":"200706" } ], "contactPerson":"Иванов П.А.", "releaseMethodType": "PRODUCTION", "createMethodType": "SELF_MADE", "productionOrderId": "08528091-808a-41ba-a55d-d6230c64b333" }
Example of REST Request (for Dairy Manufacturers)
Figure 14
42
4.5.1.1.9 Extensions for Bicycle and Bycicle Frame Manufacturers
For the description of extension for object “Order” for the bicycle and bicycle frame
manufacturers, goods group category “Bicycles and Bicycle Frames”, see Table 21.
Table 21 – Description of Extension for Object “Order” for the Manufacturers of Bicycles and Bicycle Frames
Field Description Type Mandatory
contactPerson Contact person String Yes
releaseMethodType Method of goods release into circulation
Guide No. 1 Yes
createMethodType IM creation method Guide No. 4 Yes
productionOrderId Production order identifier String No
Note*: the values “REMAINS” and “CROSSBORDER” in catalog “Method of Goods
Release into Circulation” are invalid for goods category “Bicycles and Bicycle Frames”.
For an example of REST-request (for bicycle and bicycle frame manufacturers), see
Figure 15.
POST /api/v2/bicycle/orders?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Content-Length: 718 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Type: application/json;charset=UTF-8 Host: localhost:8080 { "products":[ { "gtin":"04603721568000", "quantity" : 5, "serialNumberType" : "SELF_MADE", "serialNumbers" : [ "MZX78RZ9bmNYR", "MZX78R8i8PjF3", "MZX78RJTyZqzO", "MZX78RZnAMQTE", "MZX78RkJMXFAB" ], "templateId" : 11 } ], "contactPerson":"Иванов П.А.", "releaseMethodType": "PRODUCTION", "createMethodType": "SELF_MADE", "productionOrderId": "08528091-808a-41ba-a55d-d6230c64b333" }
Example of REST Request (for Bicycle and Bicycle Frame Manufacturers)
Figure 15
43
4.5.1.1.10 Extensions for Wheelchair Manufacturers
For the description of extension for object “Order” for wheelchair manufacturers, goods
group category “Wheelchairs”, see Table 21.
Table 22 – Description of Extension for Object “Order” for the Wheelchair Manufacturers
Field Description Type Mandatory
contactPerson Contact person String Yes
releaseMethodType Method of goods release into circulation
Guide No. 1 Yes
createMethodType IM creation method Guide No. 4 Yes
productionOrderId Production order identifier String No
Note*: the values “REMAINS” and “CROSSBORDER” in catalog “Method of Goods
Release into Circulation” are invalid for goods category “Wheelchairs”.
For an example of REST-request (for wheelchair manufacturers), see Figure 16.
POST /api/v2/wheelchairs/orders?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Content-Length: 718 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Type: application/json;charset=UTF-8 Host: localhost:8080 { "products":[ { "gtin":"04603721568000", "quantity" : 5, "serialNumberType" : "SELF_MADE", "serialNumbers" : [ "MZX78RZ9bmNYR", "MZX78R8i8PjF3", "MZX78RJTyZqzO", "MZX78RZnAMQTE", "MZX78RkJMXFAB" ], "templateId" : 12 } ], "contactPerson":"Иванов П.А.", "releaseMethodType": "PRODUCTION", "createMethodType": “SELF_MADE", "productionOrderId": "08528091-808a-41ba-a55d-d6230c64b333" }
Example of REST Request (for Wheelchair Manufacturers)
Figure 16
44
4.5.1.2. Response to Request
The method returns a unique order identifier and order expected completion time in
milliseconds (divide the result time by 1,000 for seconds, and by 60 for minutes). Value “orderId”
is used to obtain MC from the order upon its completion (see clause 4.5.6). For error codes, see
subsection 6.2..
Table 23 – Format of Response to Request
Field Description Type Mandatory
omsId Unique OMS identifier
String (UUID) Yes
orderId Unique identifier of MC Emission Order
String (UUID) Yes
expectedCompleteTimestamp Order expected completion tome, in milliseconds
Integer ($int64)
Yes
For an example of JSON-response, see Figure 17.
HTTP/1.1 200 OK Pragma: no-cache X-XSS-Protection: 1; mode=block Expires: 0 X-Frame-Options: DENY X-Content--Options: nosniff Content-Type: application/json;charset=UTF-8 Content-Length: 111 Cache-Control: no-cache, no-store, max-age=0, must-revalidate { "omsId" : "CDF12109-10D3-11E6-8B6F-0050569977A1", "orderId" : "b024ae09-ef7c-449e-b461-05d8eb116c79", "expectedCompleteTimestamp" : 5100 }
JSON-Response Example
Figure 17
45
4.5.2. Method “Send Report on MC Disposal / Rejection”
This method is used to send report on MC disposal / rejection to OMS. OMS generates
a security marker (token) during OMS-client registration. Security marker (token) is sent to
server within HTTP-header with name “clientToken”. In case security marker (token) was
obtained during the call for method “Obtain security marker by username and password” (see
cl. 4.5.13), username shall be sent within the HTTP-header named “userName”.
Note: currently, this method is available for the following goods groups:
- "Tobacco Products”
- “Dairy Products”. The structure of the request that is sent for Dairy Products must contain
Dropout Report base object without any extensions for the goods group.
4.5.2.1. Request
Structure of JSON-request used to send report on MC disposal / rejection to OMS.
REST Request Parameters
URL: http://<server-name>[:server-
port]/api/v2/{extension}/dropout?omsId={omsId}
Method:POST
Content-type:application/json
clientToken:{clientToken}
userName:{userName}
For request string parameters, see Table 24.
Table 24 – Request String Parameters
Field Description Type Mandatory
omsId Unique OMS identifier String (UUID) Yes
For the description of the structure of object “DropoutReport” for sending report on MC
disposal / rejection to OMS, see Table 25.
Table 25 – Object “DropoutReport” Structure
Field Description Type Mandatory
dropoutReason Disposal reason. String (Guide
No. 12) Yes
sntins An array of disposed MC full marking codes (including verification code)
JSON Array of String
Yes
46
Note. The quantity of MC per report on disposal shall not exceed 30,000 codes.
For an example of REST-request containing a DropoutReport base object and no
extensions, see Figure 18. This request structure is used for Dairy Products goods group.
POST /api/v2/milk/dropout?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Type: application/json;charset=UTF-8 Host: localhost:8080 Content-Length: 168 { "dropoutReason":"DEFECT", "sntins":["010400863843501621aBcD/GmaGIs3x\u001D1720032093aABb", "010400863843501621AbcdHywb*B!n+\u001D1720032093tTBb"] }
Example of REST request for Dairy Products
Figure 18
47
4.5.2.1.1 Extensions for Tobacco Industry
For the description of extension for object “DropoutReport” for tobacco industry, see Table
26.
Table 26 – Description of Extension for Object “DropoutReport” for Tobacco Industry
Field Description Type Mandatory
sourceDocDate Document date String (yyyy-mm-
dd) No
sourceDocNum Identifier of document on which the writing-off is based
String No
address Address of writing-off String Yes
withChild Attribute for writing-off of all contained elements.
Boolean (Default value=false)
Yes
participantId Tax identification number String Yes
productionOrderId Production order identifier String No
productionLineId Production line identifier String No
Note*: In case fields “sourceDocDate” and “sourceDocNum” are absent, OMS will fill
them automatically with the following values:
1) sourceDocDate with current date in unixTime UTC:0, in milliseconds;
2) sourceDocNum with current date in unixTime UTC:0, in milliseconds;
For an example of REST-request (for tobacco industry), see Figure .
POST /api/v2/tobacco/dropout?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Type: application/json;charset=UTF-8 Host: localhost:8080 Content-Length: 168 { "dropoutReason":"DEFECT", "sntins":[ "SNTIN1", "SNTIN2" ], "sourceDocNum":"12345", "sourceDocDate":"2018-05-01", "address":"198206 г Санкт-Петербург ш Петергофское, 71 ", "withChild": false, "participantId": "3543033591", "productionOrderId":"123", "productionLineId":"7098" }
Example of REST Request (for Tobacco Industry)
Figure 19
48
4.5.2.2. Response to Request
Upon successful completion of request, the server returns HTTP code -200 and a unique
identifier of report on MC disposal / rejection assigned by OMS. The obtained identifier of report
on MC disposal / rejection is used to obtain report processing status (see cl. 4.5.10). For
the structure of response to request to send information on aggregation, see Table 27. For error
codes, see subsection 6.2.
Table 27 – Format of Response to Request to Send Notification on MC Disposal / Rejection
Field Description Type Mandatory
omsId Unique OMS identifier String (UUID) Yes
reportId Unique identifier of report on MC disposal / rejection (OMS)
String (UUID) Yes
For an example of JSON-response, see Figure .
HTTP/1.1 200 OK Content-Length: 74 Pragma: no-cache X-XSS-Protection: 1; mode=block Expires: 0 X-Frame-Options: DENY X-Content--Options: nosniff Content-Type: application/json;charset=UTF-8 Cache-Control: no-cache, no-store, max-age=0, must-revalidate { "omsId" : "CDF12109-10D3-11E6-8B6F-0050569977A1", "reportId" : "46795d19-5024-404e-9275-959ac89ccb57" }
JSON-Response Example
Figure 20
49
4.5.3. Method “Send Report on MC-Aggregation”
This method is used to send report on MC aggregation to OMS. Within the report, MC are
sent without verification code. OMS generates a security marker (token) during OMS-client
registration. Security marker (token) is sent to server within HTTP-header with name
“clientToken”. In case security marker (token) was obtained during the call for method “Obtain
security marker by username and password” (see cl. 4.5.13), username shall be sent within
the HTTP-header named “userName”.
Note: currently, this method is available for the goods groups “Tobacco Products” and
“Dairy Products” only.
4.5.3.1. Request
Structure of JSON-request used to send report on MC aggregation to OMS.
REST Request Parameters
URL: http://<server-name>[:server-
port]/api/v2/{extension}/aggregation?omsId={omsId}
Method:POST
Content-type:application/json
clientToken:{clientToken}
userName:{userName}
For request string parameters, see Table 28.
Table 28 – Request String Parameters
Parameter Description Type Mandatory
omsId Unique OMS identifier String (UUID) Yes
For the description of the structure of object “AggregationReport” of request to send
information on aggregation, see Ошибка! Источник ссылки не найден.).
Table 29 – Object “AggregationReport” Structure
Field Description Type Mandatory
aggregationUnits Array of aggregation units Array of
AggregationUnit (Table 30)
Yes
participantId Tax identification number String Yes
For the description of the structure of object “AggregationUnit", see Table 30).
50
Table 30 – Object “AggregationUnit” Structure
Field Description Type Mandatory
aggregatedItemsCount Actual quantity (in pcs) per aggregation unit
Integer ($int32) Yes
aggregationType Aggregation type String (Guide
No. 7) Yes
aggregationUnitCapacity Packing unit capacity Integer ($int32) Yes
sntins
Array of aggregated MC Format in cases when MC
− - uses standard GS1:
− 01+goods nomenclature (GTIN)+21+serial number
− - does not use standard GS1:
− goods nomenclature (GTIN)+serial number
JSON Array of String
Yes
unitSerialNumber* Identification code of aggregation unit
String Yes
Note*: for goods group “Dairy Products”, field “unitSerialNumber” (aggregate code) shall
contain shipping container code (SSCC; length of 18 digital symbols).
51
4.5.3.1.1 Extensions for Tobacco Industry
For the description of extension for object “AggregationReport” for tobacco industry, see
Table 31.
Table 31 – Description of Extension for Object “AggregationReport” for Tobacco Industry
Field Description Type Mandatory
productionLineId Production line identifier String Yes
productionOrderId Production order identifier String No
For an example of REST-request for tobacco industry, see Figure .
POST /api/v2/tobacco/aggregation?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Type: application/json;charset=UTF-8 Content-Length: 785 Host: localhost:8080 { "participantId": "3543033591", "productionLineId": 235431, "productionOrderId": 123, "aggregationUnits": [ { "aggregatedItemsCount" : 2, "aggregationType" : "AGGREGATION", "aggregationUnitCapacity" : 10, “sntins" : [ "00000000666999QbUMR5M", "00000000666999r2Aw4Ge"], "unitSerialNumber" : "0100000000777999213l1SMYX" }, { "aggregatedItemsCount": 2, "aggregationType": "AGGREGATION", "aggregationUnitCapacity": 10, "sntins": [ “00000000666988QbUMR5M", "00000000666988r2Aw4Ge"], "unitSerialNumber": "0100000000777999213l1SMYT" } ] }
Example of REST Request for Tobacco Industry
Figure 21
52
4.5.3.1.2 Specifications for Dairy Manufacturers
The structure of report on MC aggregation for dairy manufacturers contains basic object
“AggregationReport” without extensions for goods group, yet has specific features. If the
aggregate is filled partially in fields “aggregationUnitCapacity” and “aggregatedItemsCount”,
value to be sent is 1. See below for examples of REST-requests for dairy manufacturers (cases
of full and partial filling of aggregate).
For an example of REST-request for dairy manufacturers (fully filled aggregate), see
Figure .
POST /api/v2/milk/aggregation?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Type: application/json;charset=UTF-8 Content-Length: 785 Host: localhost:8080 { "participantId": "3543033591", "aggregationUnits": [ { "aggregatedItemsCount" : 4, "aggregationType" : "AGGREGATION", "aggregationUnitCapacity" : 4, "sntins" : [ "010469022800405621MZX78RZ9bmNYR", "010469022800405621MZX78R8i8PjF3", "010469022800405621MZX78RJTyZqzO", "010469022800405621MZX78RZnAMQTE"], "unitSerialNumber" : "010000000077799921" } ] }
Example of REST Request for Dairy Manufacturers (Fully Filled Aggregate).
Figure 22
For an example of REST-request for dairy manufacturers (partially filled aggregate), see
Figure .
53
POST /api/v2/milk/aggregation?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Type: application/json;charset=UTF-8 Content-Length: 785 Host: localhost:8080 { "participantId": "3543033591", "aggregationUnits": [ { "aggregatedItemsCount" : 1, "aggregationType" : "AGGREGATION", "aggregationUnitCapacity" : 1, "sntins" : [ "010460166200003021MZE78RZ9bmNYR", "010460166200003021MZE78R8i8PjF3", "010460166200003021MZE78RJTyZqzO", "010460166200003021MZE78RZnAMQTE"], "unitSerialNumber" : "010000000077799922" } ] }
Example of REST Request for Dairy Manufacturers (Partially Filled Aggregate)
Figure 23
54
4.5.3.2. Response to Request
Upon successful completion of request, the server returns HTTP code -200 and a unique
identifier of report assigned by OMS. The obtained identifier of report on MC aggregation is
used to obtain report processing status (see cl. 4.5.10). For the structure of response to request
to send information on aggregation, see Table 32. For error codes, see subsection 6.2.
Table 32 – Format of Response to Request to Send Information on Aggregation
Field Description Type Mandatory
omsId Unique OMS identifier String (UUID) Yes
reportId Unique OMS identifier of report String (UUID) Yes
For an example of JSON-response, see Figure .
HTTP/1.1 200 OK Content-Length: 74 Pragma: no-cache X-XSS-Protection: 1; mode=block Expires: 0 X-Frame-Options: DENY X-Content--Options: nosniff Content-Type: application/json;charset=UTF-8 Cache-Control: no-cache, no-store, max-age=0, must-revalidate { "omsId" : "CDF12109-10D3-11E6-8B6F-0050569977A1", "reportId" : "fab1c0e4-9590-4ed7-8d58-18862d6a9aab" }
JSON-Response Example
Figure 24
55
4.5.4. Method “Send Report on MC-Utilization (Application)”
This method is used to send report on MC utilization to OMS. OMS generates a security
marker (token) during OMS-client registration. Security marker (token) is sent to server within
HTTP-header with name “clientToken”. In case security marker (token) was obtained during
the call for method “Obtain security marker by username and password” (see cl. 4.5.13),
username shall be sent within the HTTP-header named “userName”.
Note: currently, this method is available for the goods groups “Tobacco Products”, “Dairy”
and “Medicines for Human Use” only. Report will be generated automatically for the following
goods groups:
1) Bicycles and bicycle frames
2) Wheelchairs
2) Items of clothing, bed, table, bath and kitchen linens
4) Footwear
5) Perfume and eau de toilette
6) Tires and new pneumatic rubber tire casings
7) Photo cameras (except for cine cameras), flash lights and flash bulbs
Later, when the information system is ready (anticipated in Q3 of 2020), automatic sending of
application reports will be disabled. You will have to generate and send reports on MC utilization
(application) on your own, using the method described.
4.5.4.1. Request
Structure of JSON-request used to send report on MC utilization to OMS.
REST Request Parameters
URL: http://<server-name>[:server-
port]/api/v2/{extension}/utilisation?omsId={omsId}
Method:POST
Content-type:application/json
clientToken:{clientToken}
userName:{userName}
For request string parameters, see Table 33.
Table 33 – Request String Parameters
Parameter Description Type Mandatory
omsId Unique OMS identifier String (UUID) Yes
For the description of the structure of object “UtilisationReport” used to send report on
MC utilization to OMS, see Table 34.
Note. In parameters “sntins”, the sent marking codes shall include the full marking code
with verification code because this report is sent to emission registrar where marking code is
verified. The quantity of MC per report on utilization shall not exceed 30,000 codes.
56
Table 34 – Object “UtilisationReport” Structure
Field Description Type Mandatory
sntins Array of strings (full marking code, including verification code)
JSON Array of String Yes
usageType Type of use String (Guide No. 10) Yes
57
4.5.4.1.1 Extensions for Tobacco Industry
For the description of extension for object “UtilisationReport” for tobacco industry, see
Table 35.
Table 35 – Description of Extension for Object “UtilisationReport” for Tobacco Industry
Field Description Type Mandatory
productionLineId Production line identifier String Yes
productionOrderId Production order identifier. String No
brandcode Product brandname String (256) No
sourceReportId Identifier of report on application to APCS
String (36) No
For an example of REST-request for tobacco industry, see Figure .
POST /api/v2/tobacco/utilisation?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Type: application/json;charset=UTF-8 Content-Length: 145 Host: localhost:8080 { "sntins" : [ "SNTIN1", "SNTIN2" ], "usageType" : "USED_FOR_PRODUCTION", "productionLineId" : "1", "productionOrderId":"123", "brandcode" : "2212Brandcode", "sourceReportId":"8ed74f90-0119-48f2-b289-379707934e2f" }
Example of REST Request for Tobacco Industry
Figure 25
58
4.5.4.1.2 Extensions for Pharmaceutical Industry
For the description of extension for object “UtilisationReport” for pharmaceutical industry,
see Table 36.
Table 36 – Description of Extension for Object “UtilisationReport” for Pharamceutical Industry
Field Description Type Mandatory
expirationDate Date of shelf life expiration String
(dd.mm.yyyy) Yes
orderType Order type Integer (1 or 2) No
ownerId Owner identifier String (36)
(GUID) No
seriesNumber Production series number String (1-20) Yes
subjectId Pharmaceutical entity (business place identifier)
String (14 or 36) [0-9]{14} or
GUID Yes
packingId
Identifier of manufacturer who performed packing / prepacking into secondary package (if none—into primary package)
String (36) (GUID)
No
controlId Identifier of manufacturer who performs release quality control
String (36) (GUID)
No
productionDate Date of production. Shall not be earlier than MC-emission order creation date
String (dd.mm.yyyy
hh:mm:ss±hh) No
customsReceiverId Identifier of goods location in the customs control area
String (36) (GUID)
No
Note*: Value subjectId (value of subjectId):
1) for medicines produced in the territory of the Russian Federation: 14-character
business place identifier of party to circulation assigned upon the latter’s registration of
business place in MDLP FGIS;
2) for medicines produced outside the territory of the Russian Federation: 36-character
number assigned to the marketing authorization holder (or representative office thereof)
upon its registration in MDLP FGIS.
59
Attention!
1) For medicines produced in the territory of the Russian Federation:
− Field “orderType” is mandatory. This field shall contain a numerical value for
manufacturing order type: (1) for in-house and (2) for contract manufacturing;
− When orderType=2 is indicated, the value of field “ownerId” shall indicate 36-
character number assigned to the pharmaceutical entity which is the customer of
contract manufacturing upon its registration in MDLP FGIS;
− Fields “packingId”, “controlId” and “customsReceiverId” are left empty.
2) For medicines produced outside the territory of the Russian Federation:
− Field “packingId” is mandatory. It shall contain 36-character identifier assigned to
foreign counterparties upon their registration in MDLP FGIS by the medicine marketing
authorization holder (or by representative office thereof).
− Field “customsReceiverId” is non-mandatory. The field shall be filled in case
the medicines are marked in the customs control area. It shall contain an MDLP FGIS
36-character identifier of goods location from the Registry of Places in the Customs-
Controlled Area.
− Field “controlId” is non-mandatory.
Attribute “controlId” becomes mandatory upon filling in of “customReceiverId” field, i.e.
the field shall be filled in if the medicines are marked in the customs control area.
The field “controlId” may be filled in for any medicines manufactured outside the
Russian Federation even if the marking is performed beyond the customs control area
(in this case the field shall be optional).
It shall contain a 36-character identifier assigned to foreign counterparties upon their
registration in MDLP FGIS by the medicine marketing authorization holder (or by its
representative office).
− Fields “orderType” and “ownerId” are left empty.
for an example of REST-request (for pharmaceutical industry with production in the
territory of the Russian Federation), see Figure .
60
POST /api/v2/pharma/utilisation?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Length: 271 Content-Type: application/json;charset=UTF-8 Host: localhost:8080 { "sntins":[ "SNTIN1", "SNTIN2" ], "usageType":"VERIFIED", "expirationDate":"12.06.2020", "orderType":"2", "ownerId":"0c290e4a-aabb-40ae-8ef2-ce462561ce7f", "seriesNumber":"123", "subjectId":"00000000000397", "productionDate":"31.10.2019 23:59:59+03" }
Example of REST Request (for Pharmaceutical Industry with Production in the Territory of the Russian Federation)
Figure 26
For examples of REST-request (for pharmaceutical industry with production outside the
territory of the Russian Federation), see Figure .
61
/*In cases when medicines are marked in the customs control area*/ POST /api/v2/pharma/utilisation?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Length: 271 Content-Type: application/json;charset=UTF-8 Host: localhost:8080 { "sntins":[ "SNTIN1", "SNTIN2" ], "usageType":"VERIFIED", "expirationDate":"12.06.2020", "seriesNumber":"123", "subjectId":"1c858e4m-uucb-77re-1te2-ce345231ce9m", "packingId":"0c456e4a-aacb-42ae-8ef2-ce462662ce8a", "customsReceiverId": "b2jy241f-a959-1a65-9d64-5dd1378bec83", "controlId": "a6fb141f-d958-4a95-8f57-7ff2319ceb95",
"productionDate":"31.10.2019 23:59:59+03" } /*Excluding cases when medicines are marked in the customs control area**/ POST /api/v2/pharma/utilisation?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Length: 271 Content-Type: application/json;charset=UTF-8 Host: localhost:8080 { "sntins":[ "SNTIN1", "SNTIN2" ], "usageType":"VERIFIED", "expirationDate":"12.06.2020", "seriesNumber":"123", "subjectId":"1c858e4m-uucb-77re-1te2-ce345231ce9m", "packingId":"0c456e4a-aacb-42ae-8ef2-ce462662ce8a", "productionDate":"31.10.2019 23:59:59+03" }
Examples of REST Request (for Pharmaceutical Industry with Production Outside the Territory of the Russian Federation)
Figure 27
62
4.5.4.1.3 Extensions for Dairy Manufacturers
For the description of extension for object “UtilisationReport” for dairy manufacturers, see
Table 37.
Table 37 – Description of Extension for Object “UtilisationReport” for the Dairy Manufacturers
Field Description Type Mandatory
accompanyingDocument Production veterinary accompanying document
String Yes
expDate Product expiration date (shelf life exceeding 72 hours)
String (6) (YYMMDD)
No* Conditionally mandatory
expDate72 Product expiration date (shelf life under 72 hours)
String (10) (YYMMDDHHMM)
No* Conditionally mandatory
capacity Capacity, volume Double (3 decimal
places) No
usedInProduction
Indicator of MC use in production: 0 is default value; 1 means MC were used in production.
Integer ($int32) No
Note*: The report shall mandatorily include product expiration date within attribute
“expDate” or “expDate72”. If marking codes contain product expiration date varying from the
value given in attributes “expDate” or “expDate72”, report will not be accepted.
For an example of REST-request (for dairy manufacturers), see Figure .
POST /api/v2/milk/utilisation?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Type: application/json;charset=UTF-8 Content-Length: 78 Host: localhost:8080 { "sntins" : [ "SNTIN1", "SNTIN2" ], "usageType" : "USED_FOR_PRODUCTION", "accompanyingDocument": " AE68-730A-F64C-45E0-B24C-964A-DB04-33CE", "expDate":"190516", "capacity":"1.001", "usedInProduction":0 }
Example of REST Request (for Dairy Manufacturers)
Figure 28
63
4.5.4.2. Response to Request
Upon successful completion of request, the server returns HTTP code -200 and a unique
identifier of MC-utilization report assigned by OMS. The obtained identifier of report on MC
utilization is used to obtain report processing status (see cl. 4.5.10). For the structure of
response to request to send report on utilization, see Table 38. For error codes, see subsection
6.2.
Table 38 – Format of Response to Request to Send Report on MC Application
Field Description Type Mandatory
omsId Unique OMS identifier String (UUID)
Yes
reportId Unique identifier of MC application report (OMS) String (UUID)
Yes
For an example of JSON-response, see Figure .
HTTP/1.1 200 OK Content-Length: 74 Pragma: no-cache X-XSS-Protection: 1; mode=block Expires: 0 X-Frame-Options: DENY X-Content--Options: nosniff Content-Type: application/json;charset=UTF-8 Cache-Control: no-cache, no-store, max-age=0, must-revalidate { "omsId" : "CDF12109-10D3-11E6-8B6F-0050569977A1", "reportId" : "3179f5d2-2bf5-47d1-8df0-9452b257d851" }
JSON-Response Example
Figure 29
64
4.5.5. Method “Close the Suborder by the GTIN Specified”
This method is used to close MC-array (suborder) by using the following parameters:
security marker (token), OMS identifier, order identifier, and GTIN. OMS generates a security
marker (token) during OMS-client registration. Security marker (token) is sent to server within
HTTP-header with name “clientToken”.
Note: A suborder is an MC-array within one GTIN in a business order. As the last suborder
is closed, the order os sclosed automatically.
4.5.5.1. Request
REST Request Parameters
URL:http://<server-name>[:server-port]/api/v2/{extension}/buffer/close
?orderId={orderId}>in={gtin}&omsId={omsId}&
lastBlockId={lastBlockId}
Method:POST
clientToken:{clientToken}
For request string parameters, see Table 39.
Table 39 – Request String Parameters
Parameter Description Type Mandatory
omsId Unique OMS identifier String (UUID) Yes
orderId OMS-identifier of MC-emission order String (UUID) Yes
gtin GTIN by which MC-issue must be stopped
String (14) [0-9]{14}
Yes
lastBlockId Identifier of last code block obtained (default value: 0)
String No
Note: see below for suborder closure rules:
In a request in order to close a suborder, parameter “lastBlockId” shall be sent
specifying the latest code block identifier obtained in response message to the call of
method “Obtain MC from Order” (see section 4.5.6). In case the circulation participant
did not request for marking codes, it is not necessary to fill field “lastBlockId” (default
value of “0” will be set);
For an example of REST-response, see Figure .
POST /api/v2/tobacco/buffer/close HTTP/1.1 Accept: application/json Content-Type: application/x-www-form-urlencoded;charset=UTF-8 clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Host: localhost:8080 orderId=b024ae09-ef7c-449e-b461-05d8eb116c79>in=01334567894339&lastBlockId=0&omsId=CDF12109-10D3-11E6-8B6F-0050569977A1
Example of REST Response
Figure 30
65
4.5.5.2. Response to Request
Upon successful completion of request, the server returns HTTP code -200 and a unique
OMS identifier. For the structure of response to request to close the suborder by GTIN
specified, see Table 40. For error codes, see subsection 6.2.
Table 40 – Format of Response to Request to Close Suborder by GTIN Specified
Field Description Type
omsId Unique OMS identifier. (UUID) String
For an example of JSON-response, see Figure .
HTTP/1.1 200 OK Pragma: no-cache X-XSS-Protection: 1; mode=block Expires: 0 X-Frame-Options: DENY X-Content--Options: nosniff Content-Type: application/json;charset=UTF-8 Content-Length: 19 Cache-Control: no-cache, no-store, max-age=0, must-revalidate { "omsId" : "CDF12109-10D3-11E6-8B6F-0050569977A1" }
JSON-Response Example
Figure 31
66
4.5.6. Method “Obtain MC from Order”
This method is used to obtain MC-array of a specific order by using the following
parameters: security marker (token), OMS identifier, order identifier, GTIN, and quantity of
requested codes. OMS generates a security marker (token) during OMS-client registration.
Security marker (token) is sent to server within HTTP-header with name “clientToken”.
4.5.6.1. Request
REST Request Parameters
URL:http://<server-name>[:server-port]/api/v2/{extension}/codes?
omsId={omsId}&orderId={orderId}>in={gtin}&quantity={quantity}&
lastBlockId={lastBlockId}
Method:GET
clientToken:{clientToken}
For request string parameters, see Table 41.
Table 41 – Request String Parameters
Parameter Description Type Mandatory
omsId Unique OMS identifier String (UUID)
Yes
orderId Identifier of MC-emission order String (UUID)
Yes
gtin Goods GTIN for which the codes are requested
String (14) [0-9]{14}
Yes
quantity Quantity of requested codes Integer ($int32)
Yes
lastBlockId
Code block identifier issued in the previous request. May be equal to 0 in the first MC request from pool. Further, previous packet identifier shall be sent. Default value: 0
String No
Note: A circulation participant obtains emitted marking codes (guaranteed obtainment of
emitted marking codes) by sending confirmation of marking code obtainment within request, and
when closing the order. Instruction on obtaining marking codes:
1) in the first request for marking codes, the value of attribute “lastBlockId” shall be “0”
(zero), the response message will contain code block identifier (attribute “blockId” value)
which must be specified within the next request for marking codes, and each
subsequent request shall specify attribute “lastBlockId” value as the code block identifier
obtained within the previous request (code block identifier transmission confirms that
emitted marking codes were received);
67
2) the final step is order closure performed automatically when the last MC is being
printed. Circulation participant may close the order at will while MC have not been
printed completely (see section 4.5.5). The request to close (attribute “lastBlockId”) shall
contain the last obtained code block identifier if some of MC have already been printed.
If no MC from the order has been printed, it is not necessary to fill in the attribute
“lastBlockId” (value of “0” will be set).
For an example of REST-response, see Figure .
GET /api/v2/tobacco/codes?orderId=b024ae09-ef7c-449e-b461-05d8eb116c79>in=01334567894339&quantity=15&lastBlockId=0&omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json Content-Type: application/x-www-form-urlencoded;charset=UTF-8 clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Host: localhost:8080
Example of REST Response
Figure 32
68
4.5.6.2. Response to Request
Upon successful completion of request, the server returns HTTP code -200 and an MC-
array. For the format of response to request for MC for the goods specified, see Table 42. For
error codes, see subsection 6.2.
Table 42 – Format of Response to Request for MC for the Goods Specified
Field Description Type Mandatory
omsId Unique OMS identifier String (UUID)
Yes
codes MC-array JSON Array
of Strings Yes
blockId MC packet identifier String (UUID)
Yes
For an example of JSON-response, see Figure .
HTTP/1.1 200 OK Pragma: no-cache X-XSS-Protection: 1; mode=block Expires: 0 X-Frame-Options: DENY X-Content--Options: nosniff Content-Length: 820 Content-Type: application/json;charset=UTF-8 Cache-Control: no-cache, no-store, max-age=0, must-revalidate { "omsId" : "CDF12109-10D3-11E6-8B6F-0050569977A1", "codes" : [ "010460165303004621\u003drxDV3M\u001d93VXQI",...], "blockId" : "012cc7b0-c9e4-4511-8058-2de1f97a87b0" }
JSON-Response Example
Figure 33
69
4.5.7. Method “Obtain MC-Array Status from Order”
This method is used to obtain the current status of MC-array from the order and requires
the following parameters: security marker (token), OMS identifier, order identifier “orderId”, and
GTIN. OMS generates a security marker (token) during OMS-client registration. Security marker
(token) is sent to server within HTTP-header with name “clientToken”.
4.5.7.1. Request
The structure of request to obtain MC-array status from order.
REST Request Parameters
URL:http://<server-name>[:server-
port]/api/v2/{extension}/buffer/status?
omsId={omsId}&orderId={orderId}>in={gtin}
Method:GET
clientToken:{clientToken}
For request string parameters, see Table 43.
Table 43 – Request String Parameters
Field Description Type Mandatory
omsId Unique OMS identifier String (UUID)
Yes
orderId Identifier of MC-emission order String (UUID)
Yes
gtin Goods GTIN the status of which is required String
(14) [0-9]{14}
Yes
For an example of REST-response, see Figure .
GET /api/v2/tobacco/buffer/status?orderId=b024ae09-ef7c-449e-b461-05d8eb116c79>in=01334567894339&omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json Content-Type: application/x-www-form-urlencoded;charset=UTF-8 clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Host: localhost:8080
Example of REST Response
Figure 34
70
4.5.7.2. Response to Request
For the JSON-format of response to request to obtain MC-array status, see Table 44. For
error codes, see subsection 6.2.
Table 44 – Format of Response to Request, object “BufferInfo”
Field Description Type Mandatory
availableCodes The total quantity of available MC for goods in buffer and pools of registrar
Integer ($int32) Yes
bufferStatus Buffer status String (Guide
No. 8) Yes
gtin GTIN on which the request was made
String (14) [0-9]{14}
Yes
leftInBuffer Quantity of MC unused. (local buffer) Integer ($int32) Yes
omsId Unique OMS identifier String Yes
orderId Unique identifier of MC-emission order Order on which the request was made
String (UUID) Yes
poolInfos Array of pools created for the buffer JSON Array of PoolInfo Object
(Table 45) Yes
poolsExhausted MC-pools in registrars are exhausted Boolean Yes
rejectionReason
Reason for buffer rejection by OMS Note: in case the order is declined, this field has value “Order declined:” with the reason for order decline
String No
totalCodes Ordered quantity of MC in order Integer ($int32) Yes
totalPassed Total qty of MC obtained from buffer Integer ($int32) Yes
unavailableCodes Quantity of unavailable codes Integer ($int32) Yes
Table 45 – Object “PoolInfo” Format
Field Description Type Mandatory
isRegistrarReady ER readiness Boolean Yes
lastRegistrarErrorTimestamp Time stamp for the latest ER-errors observed
Long ($int64) Yes
leftInRgistrar Quantity of MC left in pool Integer ($int32) Yes
quantity Ordered quantity of MC in pool
Integer ($int32) Yes
registrarErrorCount Quantity of ER-errors Integer ($int32) Yes
registrarId ER-identifier (number) String Yes
rejectionReason Rejection reason String No
71
Field Description Type Mandatory
status MC pool status String (Guide
No. 6) Yes
For an example of JSON-response (with existing buffer), see Figure .
HTTP/1.1 200 OK Pragma: no-cache X-XSS-Protection: 1; mode=block Expires: 0 X-Frame-Options: DENY X-Content--Options: nosniff Content-Length: 659 Content-Type: application/json;charset=UTF-8 Cache-Control: no-cache, no-store, max-age=0, must-revalidate { "poolInfos" : [ { "status" : "READY", "quantity" : 9, "leftInRegistrar" : 0, "registrarId" : "Virtual Registrar", "isRegistrarReady" : true, "registrarErrorCount" : 0, "lastRegistrarErrorTimestamp" : 0 }, { "status" : "READY", "quantity" : 11, "leftInRegistrar" : 0, "registrarId" : "Virtual Registrar", "isRegistrarReady" : true, "registrarErrorCount" : 0, "lastRegistrarErrorTimestamp" : 0 } ], "leftInBuffer" : 0, "totalCodes" : 20, "poolsExhausted": false, "unavailableCodes" : 0, "availableCodes" : 20, "orderId" : "b024ae09-ef7c-449e-b461-05d8eb116c79", "gtin" : "01334567894339", "bufferStatus" : "ACTIVE", "totalPassed": 0, "omsId" : "CDF12109-10D3-11E6-8B6F-0050569977A1" }
Example of JSON-Response (with Existing Buffer)
Figure 35
72
Example of the JSON response (for the declined order) is shown in Figure .
HTTP/1.1 200 OK Pragma: no-cache X-XSS-Protection: 1; mode=block Expires: 0 X-Frame-Options: DENY X-Content--Options: nosniff Content-Length: 659 Content-Type: application/json;charset=UTF-8 Cache-Control: no-cache, no-store, max-age=0, must-revalidate { "leftInBuffer" : -1, "poolsExhausted": false, "totalCodes" : -1, "unavailableCodes" : -1, "availableCodes" : -1, "orderId" : "6be66e5e-ab2b-4b8b-b2b7-19a71ddefb9d", "gtin" : "04606038003172", "bufferStatus" : "REJECTED", "rejectionReason": "Order declined: Control and logic check of the order is not passed. 0106: Value 04606038003172 in field 'GTIN' in document 'MC order'{1} is not found in GTIN registry.", "totalPassed": -1, "omsId": "0206854c-f182-4356-8207-0c2517c3853b" }
Example of the JSON Response (for the declined order)
Figure 36
73
4.5.8. Method “Obtain the status of orders”
This method is applied to obtain the status of business orders using the following
parameters: security marker (token), OMS identifier. The security marker (token) is generated
by OMS during OMS client registration. Security marker (token) is sent to server within HTTP-
header with name “clientToken”.
Notes:
3) the method is designed to restore the APCS after total data loss, the use of
opportunities offered thereby in the regular OMS operation processes is prohibited.
4) Applying this method from a single source, as well as the order creation method,
cannot be realized more often than 100 times per second.
4.5.8.1. Request
REST Request Parameters
URL: http://<server-name>[:server-
port]/api/v2/{extension}/orders?omsId={omsId}
Method:GET
clientToken:{clientToken}
For the request string parameter, see Table 46.
Table 46 – Request String Parameters
Parameter Description Type Mandatory
omsId Unique OMS identifier String (UUID) Yes
REST Request Example is shown in Figure .
GET /api/v2/tobacco/orders?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json Content-Type: application/x-www-form-urlencoded;charset=UTF-8 clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Host: localhost:8080
REST Request Example
Figure 37
74
4.5.8.2. Response to Request
Upon successful completion of request, the server returns HTTP code -200, and data on
the business orders status, and the unique OMS identifier. The format of response to request for
the aggregate structure is shown in Table 47. For error codes see subsection 6.2.
Table 47 – Format of Response to Request for Order Status
Parameter Description Type Mandatory
omsId Unique OMS identifier String (UUID) Yes
orderInfos Array of orders with their statuses JSON Array of
OrderSummaryInfo (Table 48)
Yes
Table 48 – Object “OrderSummaryInfo” Format
Field Description Type Mandatory
orderId Identifier for MC emission order String (UUID) Yes
orderStatus Order status String (Guide
No.11) Yes
buffers Buffer status information array JSON Array of BufferInfo (Table 44)
Yes
createdTimestamp Order creation time Integer ($int64)
Yes
declineReason Reason for order decline String No
75
JSON Response example is shown in Figure .
HTTP/1.1 200 OK Pragma: no-cache X-XSS-Protection: 1; mode=block Expires: 0 X-Frame-Options: DENY X-Content--Options: nosniff Content-Length: 953 Content-Type: application/json;charset=UTF-8 Cache-Control: no-cache, no-store, max-age=0, must-revalidate { "omsId" : "CDF12109-10D3-11E6-8B6F-0050569977A1", "orderInfos" : [ { "orderId" : "b024ae09-ef7c-449e-b461-05d8eb116c79", "orderStatus" : "READY", "createdTimestamp" : 1550650989568, "buffers" : [ { "poolInfos" : [ { "status" : "READY", "quantity" : 9, "leftInRegistrar" : 0, "registrarId" : "Virtual Registrar", "isRegistrarReady" : true, "registrarErrorCount" : 0, "lastRegistrarErrorTimestamp" : 0 }, { "status" : "READY", "quantity" : 11, "leftInRegistrar" : 0, "registrarId" : "Virtual Registrar", "isRegistrarReady" : true, "registrarErrorCount" : 0, "lastRegistrarErrorTimestamp" : 0 } ], "leftInBuffer" : 20, "totalCodes" : 20, "unavailableCodes" : 0, "orderId" : "b024ae09-ef7c-449e-b461-05d8eb116c79", "gtin" : "01334567894339", "bufferStatus" : "ACTIVE", "omsId" : "CDF12109-10D3-11E6-8B6F-0050569977A1" } ] } ] }
JSON Response Example
Figure 38
76
4.5.9. Method “Obtain the Aggregation Information”
This method is applied to obtain the aggregation structure using the following parameters:
token, OMS identifier, aggregate identifier. The token is generated by OMS during OMS client
registration. The token is sent to server within HTTP-header with name “clientToken”.
4.5.9.1. Request
REST Request Parameters
URL: http://<server-name>[:server-
port]/api/v2/{extension}/aggregation/info?omsId={omsId}&
unitSerialNumber={unitSerialNumber}
Method:GET
Accept: application/json
clientToken:{clientToken}
For the request string parameter, see Table 49.
Table 49 – Request String Parameters
Parameter Description Type Mandatory
omsId Unique OMS identifier String (UUID) Yes
unitSerialNumber
Aggregate identifier. The code may contain special symbols, therefore, the value shall be encoded to the valid format ASCII (URL Encoding)
String Yes
REST Request Example is shown in Figure .
GET /api/v2/tobacco/aggregation/info?unitSerialNumber= 0100000000777999213l1SMYX8005100000&omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Type: application/json;charset=UTF-8 Host: localhost:8080
REST Request Example
Figure 39
77
4.5.9.2. Response to Request
Upon successful completion of request, the server returns HTTP code -200 and the
commodity nomenclature guidebook data. The format of response to request for the aggregate
structure is shown in Table 50. For error codes see subsection 6.2.
Table 50 – Format of Response to Request for Information on Aggregation, object “AggregationInfo”
Field Description Type Mandatory
aggregationUnits Array of aggregation units Array of
AggregationUnit (Table 30)
Yes
omsId Unique OMS identifier String (UUID) Yes
participantId Tax identification number String Yes
productsInfo Product information Array of
ProductInfo (Table 51)
No
For the description of object “ProductInfo» structure, see Table 51.
Table 51 – Object “OrderSummaryInfo” Format
Field Description Type Mandatory
gtin Product GTIN String (14) [0-
9]{14} Yes
name Product name String Yes
78
JSON Response example is shown in Figure .
HTTP/1.1 200 OK Pragma: no-cache X-XSS-Protection: 1; mode=block Expires: 0 X-Frame-Options: DENY Content-Length: 119 X-Content--Options: nosniff Content-Type: application/json;charset=UTF-8 { "aggregationUnit": { "aggregatedItemsCount": 48, "aggregationType": "AGGREGATION", "aggregationUnitCapacity": 50, "sntins": [ "0100000848839984215LJ", "0100000848839984215Py" ], "unitSerialNumber": "0100000000777999213l1SMYX8005100000" }, "omsId": "CDF12109-10D3-11E6-8B6F-0050569977A1", "participantId": "string", "productsInfo": [ { "gtin": "string", "name": "string" } ] }
JSON Response Example
Figure 40
79
4.5.9.2.1 Extension of Tobacco Industry
Description of the “AggregationInfo” object extension for the tobacco industry
manufacturers is shown in Table 52.
Table 52 – Description of the “AggregationInfo” Object Extension for Tobacco Industry Manufacturers
Field Description Type Mandatory
productionLineId Production line identifier String Yes
productionOrderId Production order identifier String No
JSON Response example is shown in Figure .
HTTP/1.1 200 OK Pragma: no-cache X-XSS-Protection: 1; mode=block Expires: 0 X-Frame-Options: DENY Content-Length: 119 X-Content--Options: nosniff Content-Type: application/json;charset=UTF-8 { "aggregationUnit": { "aggregatedItemsCount": 48, "aggregationType": "AGGREGATION", "aggregationUnitCapacity": 50, "sntins": [ "0100000848839984215LJ", "0100000848839984215Py" ], "unitSerialNumber": "0100000000777999213l1SMYX8005100000" }, "omsId": "CDF12109-10D3-11E6-8B6F-0050569977A1", "participantId": "string", "productionLineId": 235431, "productionOrderId": 123, "productsInfo": [ { "gtin": "string", "name": "string" } ] }
JSON Response Example
Figure 41
80
4.5.10. Method “Obtain the Report Processing Status”
This method is applied to obtain the report processing status using the following
parameters: security marker (token) and OMS identifier; report identifier. The security marker
(token) is generated by OMS during OMS client registration. Security marker (token) is sent to
server within HTTP-header with name “clientToken”.
4.5.10.1. Request
REST Request Parameters
URL: http://<server-name>[:server-
port]/api/v2/{extension}/report/info?omsId={omsId}&
reportId={reportId}
Method:GET
clientToken:{clientToken}
For the request string parameter, see Table 53.
Table 53 – Request String Parameters
Parameter Description Type Mandatory
omsId Unique OMS identifier String (UUID) Yes
reportId Unique OMS report identifier String (UUID) Yes
REST Request Example is shown in Figure .
GET /api/v2/tobacco/report/info?reportId=fab1c0e4-9590-4ed7-8d58-18862d6a9aab&omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-Type: application/json;charset=UTF-8 Host: localhost:8080
REST Request Example
Figure 42
81
4.5.10.2. Response to Request
Upon successful completion of request, the server returns HTTP code -200 and a unique
OMS report identifier and the report processing status. The format of response to request for the
report processing status is shown in Table 54. For error codes see subsection 6.2.
Table 54 – Format of Response to Request for the Report Processing Status
Parameter Description Type Mandatory
omsId Unique OMS identifier String (UUID) Yes
reportId Unique OMS report identifier String (UUID) Yes
reportStatus Report processing status String(Guide
No.9) Yes
JSON Response example is shown in Figure .
HTTP/1.1 200 OK Pragma: no-cache X-XSS-Protection: 1; mode=block Expires: 0 X-Frame-Options: DENY Content-Length: 108 X-Content--Options: nosniff Content-Type: application/json;charset=UTF-8 Cache-Control: no-cache, no-store, max-age=0, must-revalidate { "omsId":"CDF12109-10D3-11E6-8B6F-0050569977A1", "reportId":"fab1c0e4-9590-4ed7-8d58-18862d6a9aab", "reportStatus":"SENT" }
JSON Response Example
Figure 43
82
4.5.11. Method “Send APCS Log Files”
This method is used for sending APCS log files in zip format with the following parameters:
security marker (token), OMS identifier and file in zip format. The security marker (token) is
generated by OMS during OMS client registration. Security marker (token) is sent to server
within HTTP-header with name “clientToken”.
4.5.11.1. Request
REST Request Parameters
URL: http://<server-name>[:server-port]/api/v2/{extension}/
logs?omsId={omsId}
Method:POST
Content-: multipart/form-data
clientToken:{clientToken}
For the request string parameter, see Table 55).
Table 55 – Request String Parameters
Parameter Description Type Mandatory
omsId Unique OMS identifier String (UUID) Yes
For the request parameter, see Table 56.
Table 56 – Request Body Parameters
Parameter Description Type Mandatory
log File in zip format - Yes
Request Example is shown in Figure .
POST /api/v2/tobacco/logs/upload?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Content-: multipart/form-data;charset=UTF-8; boundary=6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm Host: localhost:8080 --6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm Content-Disposition: form-data; name=omsId 123456 --6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm Content-Disposition: form-data; name=log; filename=logs.zip Content-Type: text/plain Test data --6o2knFse3p53ty9dmcQvWAIx1zInP11uCfbm—
Request Example
Figure 44
83
4.5.11.2. Response to Request
Upon successful completion of request, the server returns HTTP code -200 and a unique
OMS identifier. The format of response to request for OMS availability is shown in Table 57. For
error codes see subsection 6.2.
Table 57 – Format of Response to Request for OMS Availability
Field Description Type Mandatory
omsId Unique OMS identifier String (UUID) Yes
JSON Response example is shown in Figure .
HTTP/1.1 200 OK Pragma: no-cache X-XSS-Protection: 1; mode=block Expires: 0 X-Frame-Options: DENY X-Content--Options: nosniff Content-Type: application/json;charset=UTF-8 Content-Length: 19 Cache-Control: no-cache, no-store, max-age=0, must-revalidate { "omsId" : "CDF12109-10D3-11E6-8B6F-0050569977A1" }
JSON Response Example
Figure 45
84
4.5.12. Method “Check OMS Availability”
This method is used to check the OMS availability with the following parameters: security
marker (token) and OMS identifier. The security marker (token) is generated by OMS during
OMS client registration. Security marker (token) is sent to server within HTTP-header with name
“clientToken”.
4.5.12.1. Request
REST Request Parameters
URL: http://<server-name>[:server-
port]/api/v2/{extension}/ping?omsId={omsId}
Method:GET
clientToken:{clientToken}
For the request string parameter, see Table 58.
Table 58 – Request String Parameters
Parameter Description Type Mandatory
omsId Unique OMS identifier String(UUID) Yes
REST Request Example is shown in Figure .
GET /api/v2/tobacco/ping?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 HTTP/1.1 Accept: application/json Content-Type: application/x-www-form-urlencoded;charset=UTF-8 clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Host: localhost:8080
REST Request Example
Figure 46
85
4.5.12.2. Response to Request
Upon successful completion of request, the server returns HTTP code -200 and a unique
OMS identifier. The format of response to request for OMS availability is shown in Table 59. For
error codes see subsection 6.2.
Table 59 – Format of Response to Request for OMS Availability
Field Description Type Mandatory
omsId Unique OMS identifier String (UUID) Yes
JSON Response example is shown in Figure .
HTTP/1.1 200 OK Pragma: no-cache X-XSS-Protection: 1; mode=block Expires: 0 X-Frame-Options: DENY X-Content--Options: nosniff Content-Type: application/json;charset=UTF-8 Content-Length: 19 Cache-Control: no-cache, no-store, max-age=0, must-revalidate { "omsId":"CDF12109-10D3-11E6-8B6F-0050569977A1" }
JSON Response Example
Figure 47
86
4.5.13. Method “Obtain Security Marker by Username and Password”
This method allows getting security marker (token) by username and password. The
method uses the following parameters: OMS identifier, username and password. The obtained
security marker (token) is used in HTTP-header with name “clientToken” when calling other
OMS API methods (addressing to other recourses).
Note*: this method is not supported by the Production-based OMS.
4.5.13.1. Request
REST Request Parameters
URL: http://<server-name>[:server-
port]/api/v2/{extension}/token?omsId={omsId}&
username={username}&password={password}
Method:GET
tokenName: tokenName
Accept: application/json
The HTTP header parameters are shown in Table 60.
Table 60 – HTTP Header Parameters
Parameter Description Type Mandatory
tokenName User name (client device name) String Yes
For the request string parameters, see Table 61.
Table 61 – Request String Parameters
Parameter Description Type Mandatory
omsId Unique OMS identifier String (UUID) Yes
username User's first name String Yes
password User password String Yes
REST Request Example is shown in Figure .
GET /api/v2/tobacco/token?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 &username=admin&password=password HTTP/1.1 Accept: application/json Host: localhost:8080
REST Request Example
Figure 48
87
4.5.13.2. Response to Request
Upon successful completion of request, the server returns HTTP code -200, a unique OMS
identifier and security marker (token). The format of response to request for OMS availability is
shown in Table 62. For error codes see subsection 6.2.
Table 62 – Format of Response to Request for Security Marker
Field Description Type Mandatory
omsId Unique OMS identifier String (UUID) Yes
token Security marker String Yes
JSON Response example is shown in Figure .
HTTP/1.1 200 OK Pragma: no-cache X-XSS-Protection: 1; mode=block Expires: 0 X-Frame-Options: DENY X-Content--Options: nosniff Content-Type: application/json;charset=UTF-8 Content-Length: 19 Cache-Control: no-cache, no-store, max-age=0, must-revalidate { "omsId":"CDF12109-10D3-11E6-8B6F-0050569977A1", "token":"1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f", }
JSON Response Example
Figure 49
88
4.5.14. Method “Obtain OMS and API Version”
This method helps obtaining the versions of OMS and API. The method does not require
any parameters. The security marker (token) generated by OMS during OMS client registration
is sent to server within HTTP-header with name “clientToken”.
4.5.14.1. Request
REST Request Parameters
URL: http://<server-name>[:server-port]/api/v2/{extension}/ version
Method:GET
clientToken:{clientToken}
Accept: application/json
4.5.14.2. Response to Request
Upon successful completion of request, the server returns HTTP code -200, OMS version
number and OMS API number. The format of response to request for OMS availability is shown
in Table 63. For error codes see subsection 6.2.
Table 63 – Format of Response to Request for OMS and API Version
Field Description Type Mandatory
apiVersion OMS API version String Yes
omsVersion OMS version String Yes
JSON Response example is shown in Figure .
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Content-Length: 19 { "apiVersion": "2.0.0.54", "omsVersion": "3.1.8.0" }
JSON Response Example
Figure 50
89
4.5.15. Method “Obtain the List of Marking Code Package Identifiers”
This method is used to obtain the list of marking code package identifiers issued
previously from marking code order for repeated request for marking codes by calling method
“Re-obtain marking codes from the marking code order” (see clause 4.5.16).
The method uses the following parameters: OMS identifier, order identifier, GTIN. The
security marker (token) generated by OMS during OMS client registration is sent to server within
HTTP-header with name “clientToken”.
4.5.15.1. Restrictions
The list of previously issued marking code package identifiers may be obtained only if the
marking code order has not been closed and the first request for printing has been executed via
API.
4.5.15.2. Request
REST request parameters:
URL: http://<server-name>[:server-
port]/api/v2/{extension}/codes/blocks?omsId={omsId}&
orderId={orderId}>in={gtin}
Method:GET
clientToken:{clientToken}
Accept: application/json
Table 64 – Request String Parameters
Parameter Description Type Mandatory
omsId Unique OMS identifier String(UUID) Yes
orderId
Marking code order identifier. String value. Identifier value in accordance with ISO/IEC 9834-8. Template: [0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}
String (36) (UUID)
Yes
gtin Goods code (GTIN) for which marking code package identifiers are requested. Template: [0-9]{14}
String (14) [0-9]{14}
Yes
Request Example is shown in Figure .
GET /api/v2/{extension}/codes/blocks?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1&orderId=b024ae09-ef7c-449e-b461-05d8eb116c79>in=01334567894339 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Host: localhost:8080
Request Example
Figure 51
90
4.5.15.3. Response to Request
Upon successful completion of request, the server returns HTTP code 200, a list of
marking code package identifiers. For the format of response to request for the list of marking
code package identifiers for the marking and goods code order specified, see Table 65. For
error codes, see subsection 6.2.
Table 65 – Format of Response to Request for the List of MC Packet Identifiers for the Marking and Goods Code Order Specified
Field Description Type Mandatory
orderId
Marking code order identifier. String value. Identifier value in accordance with ISO/IEC 9834-8. Template: [0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}
String (36) (UUID)
Yes
gtin Goods code (GTIN) for which marking code package identifiers are requested. Template: [0-9]{14}
String (14) [0-9]{14}
Yes
omsId Unique OMS identifier String (UUID) Yes
blocks List of marking code packages
Array of objects Block
(JSON Array of Block)
Yes
Table 66 – Format of MC Package List, Object “Block”
Field Description Type Mandatory
blockId
Marking code package identifier sent within the request. String value. Identifier value in accordance with ISO/IEC 9834-8. Template: [0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}
String (36)(UUID)
Yes
blockDateTime Date, time of marking code package creation. Format: UnixTime
Integer ($int64) Yes
quantity Quantity of marking codes in marking code package
Integer ($int32) Yes
91
Response example is shown in Figure .
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 X-RequestId: 1a59cc06-4371-4981-9e9e-019b435bfa72 Content-Length: 310 { "orderId": "b024ae09-ef7c-449e-b461-05d8eb116c79", "omsId": "CDF12109-10D3-11E6-8B6F-0050569977A1", "gtin": "01334567894339", "blocks": [ { "blockId": "a024ae09-ef7c-449e-b461-05d8eb116c90", "blockDateTime": 1573986891, "quantity": 100 }, { "blockId": "a024ae09-ef7c-449e-b461-05d8eb116c93", "blockDateTime": 1573986910, "quantity": 100 } ] }
Response Example
Figure 52
92
4.5.16. Method “Re-obtain Marking Codes from the Marking Code Order”
This method is used to re-obtain emitted MC array from marking code suborder in case
when marking codes were not obtained due to communications errors or errors on the side of
System interacting with OMS.
The method uses the following parameters: order identifier, GTIN, marking code package
identifier. The security marker (token) generated by OMS during OMS client registration is sent
to server within HTTP-header with name “clientToken”.
The list of previously issued marking code package identifiers is obtained by calling
method “Obtain the list of marking code package identifiers” (see cl. 4.5.1515).
4.5.16.1. Restrictions
The marking codes may be repeatedly requested if
5) they were previously requested via API;
6) the suborder of marking codes has not been closed.
4.5.16.2. Request
See request parameters below:
URL: http://<server>[:port]/api/v2/{extension}/codes/retry?
orderId={orderId}>in={gtin}&blockId={blockId}
Method:GET
clientToken:{clientToken}
Accept: application/json
Table 67 – Request String Parameters
Parameter Description Type Mandatory
orderId
Marking code order identifier. String value. Identifier value in accordance with ISO/IEC 9834-8. Template: [0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}
String (36) (UUID)
Yes
gtin Goods code (GTIN) for which marking codes are requested again. Template: [0-9]{14}
String (14) [0-9]{14}
Yes
blockId
Code block identifier. String value. Identifier value in accordance with ISO/IEC 9834-8. Template: [0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}
String (36) (UUID)
Yes
Request Example is shown in Figure .
93
GET /api/v2/{extension}/codes/retry?orderId=b024ae09-ef7c-449e-b461-05d8eb116c79>in=01334567894339&blockId=a024ae09-ef7c-449e-b461-05d8eb116c90 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Host: localhost:8080
Request Example
Figure 53
94
4.5.16.3. Response to Request
Upon successful completion of request, the server returns HTTP code 200, a marking
code package. Format of response to request for re-obtaining of MC for the goods specified is
shown in Table 68. For error codes, see subsection 6.2.
Table 68 – Format of Response to Request for Re-obtainment of MC for the Goods Specified
Field Description Type Mandatory
omsId Unique OMS identifier String (UUID)
Yes
codes Marking code package
Array of strings (JSON Array of Strings)
Yes
blockId
Marking code package identifier sent within the request. String value. Identifier value in accordance with ISO/IEC 9834-8. Template: [0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}
String (36) (UUID)
Yes
Response example is shown in Figure .
HTTP/1.1 200 OK Content-Type: application/json;charset=UTF-8 Content-Length: 310 { "omsId": "bb179f1f-d6d5-4e09-8012-2a28648474e9", "codes": ["010460165303004621\u003drxDV3M\u001d93VXQI","..."], "blockId": "a024ae09-ef7c-449e-b461-05d8eb116c90" }
Response Example
Figure 54
95
4.5.17. Method “Send Report on the Utilization and Automatic
Introduction into Circulation”
This method is applied to send report on using MC and request for introduction into
circulation to OMS. The method uses OMS identifier as a parameter. The security marker
(token) generated by OMS during OMS client registration is sent to server within HTTP-header
with name “clientToken”. If the security marker (token) was obtained during the call for method
“Obtain security marker by username and password” (see section 4.5.1313), username shall be
sent within the HTTP-header named “userName”.
4.5.17.1. Restrictions
Currently this method is available for the milk producers.
4.5.17.2. Request
REST request parameters are provided below:
URL: http://<server-name>[:server-port]/api/v2/{extension}/
rollout?omsId={omsId}
Method:POST
Content-type:application/json
clientToken:{clientToken}
userName:{userName}
Table 69 – Request String Parameters
Parameter Description Type Mandatory
omsId Unique OMS identifier String (UUID) Yes
For the request body parameters, see Table 70.
Table 70 – Object “RollOutReport” Structure
Field Description Type Mandatory
usageType Type of use String (enum) (Guide No.10)
Yes
documentFormat Document format. Valid value: «MANUAL»
String Yes
type
Valid values:
− LP_INTRODUCE_GOODS_AUTO - made in the Russian Federation
− LP_GOODS_IMPORT_AUTO – imported Note: the value "LP_GOODS_IMPORT_AUTO" is currently invalid for goods category "Dairy products”.
String Yes
participantInn Participant's INN (10 or 12 digits) String Yes
productionDate Date of production. Date (yyyy- Yes
96
Field Description Type Mandatory
The attribute value shall be within the following range: current date minus 5 calendar years <= productionDate <= current date.
mm-dd)
products Information on products (see Table 73) Array of Product
Yes
produced
Information on manufacturer, Russian Federation. To be filled if =LP_INTRODUCE_GOODS_AUTO (see Table 71)
Object Produced
No (Conditionally mandatory)
import
Information on import manufacturer. To be filled if =LP_GOODS_IMPORT_AUTO (see Table 72)
Object Import No
(Conditionally mandatory)
Table 71 – Description of the Object “Produced” for Goods Made in the Russian Federation
Field Description Type Mandatory
producerInn Manufacturer’s INN (10 or 12 digits)
String Yes
ownerInn Owner’s TIN/INN (10 or 12 digits). String Yes
productionType Production order type. Valid value: OWN_PRODUCTION
String Yes
Table 72 – Description of the Object “Import” for Imported Goods
Field Description Type Mandatory
declarationDate
Date of goods customs declaration registration. The attribute value shall be within the following range: current date minus 5 calendar years <= declarationDate <= current date.
Date (YYYY-MM-
DD) Yes
declarationNumber Goods declaration number String Yes
customsCode Customs authority code String Yes
decisionCode
Customs authority decision code. Integer ($int64)
Yes
Table 73 – Description of Object “Product”
Field Description Type Mandatory
code Full MC (including verification code). String Yes
97
Field Description Type Mandatory
certificateDocument
Type of document confirming compliance. Valid values:
− “1” - Certificate of conformity;
− “2” - Declaration of conformity
String No
certificateDocumentDate
Date of document confirming compliance. The attribute value shall be within the following range: current date minus 5 calendar years <= certificateDocumentDate <= current date.
Date (YYYY-
MM-DD)
No
certificateDocumentNumber Number of document confirming compliance
String No
tnvedCode Goods code as per EEU FEACN. String (10)
Yes
98
4.5.17.2.1 Extensions for milk producers
Description of the “RollOutReport” object extension for the milk producers is shown in
Table 74.
Table 74 – Description of Object “RollOutReport” Extension for Milk Producers
Field Description Type Mandatory
accompanyingDocument Production veterinary accompanying document
String Yes
expDate Product expiration date (shelf life exceeding 72 hours)
String (6) (YYMMDD)
No* Conditionally mandatory
expDate72 Product expiration date (shelf life under 72 hours)
String (10) (YYMMDDHHMM)
No* Conditionally mandatory
capacity Capacity, volume Double (3 decimal
places) No
Note*: The report shall obligatorily include product expiration date within attribute
“expDate” or “expDate72”. If marking codes contain product expiration date varying from the
value given in attributes “expDate” or “expDate72”, report will not be accepted.
99
Request example for goods made in the Russian Federation is shown in Figure .
POST /api/v2/{extension}/rollout?omsId=123456789 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Host: localhost:8080 { "usageType": "SENT_TO_PRINTER", "documentFormat": "MANUAL", "type": "LP_INTRODUCE_GOODS_AUTO", "participantInn": "1334567890", "productionDate": "10/10/2019", "accompanyingDocument": "AE68-730A-F64C-45E0-B24C-964A-DB04-33CE", "expDate": "190516", "capacity": "120.014", "products": [ { "code": "01046071128147902154BkTTHqlQl9E\u001d17190516\u001d93ZmFrZQ==", "certificateDocument": "1", "certificateDocumentDate": "10/13/2018", "certificateDocumentNumber": "1234", "tnvedCode": "1111111111" } ], "produced": { "producerInn": "1134567890", "ownerInn": "1234567890", "productionType": "OWN_PRODUCTION" } }
Request Example for Goods Made in the Russian Federation
Figure 55
100
Request example for the imported goods is shown in Figure .
POST /api/v2/{extension}/rollout?omsId=123456789 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Host: localhost:8080 { "usageType": "SENT_TO_PRINTER", "documentFormat": "MANUAL", "type": "LP_GOODS_IMPORT_AUTO", "participantInn": "1334567890", "productionDate": "10/10/2019", "accompanyingDocument": "AE68-730A-F64C-45E0-B24C-964A-DB04-33CE", "expDate72": "1905162112", "capacity": "120.014", "products": [ { "code": "01046071128147902154BkTTHqlQl9E\u001d70031905162112\u001d93ZmFrZQ==", "certificateDocument": "1", "certificateDocumentDate": "10/13/2018", "certificateDocumentNumber" : "1234", "tnvedCode": "1111111111" } ], "Import": { "declarationDate": "12/12/2015", "declarationNumber": "1234", "customsCode": "1234", "decisionCode": 321 } }
Request example for the imported goods
Figure 56
101
4.5.17.3. Response to Request
Upon successful completion of request, the server returns HTTP code 200 and a unique
identifier of report on utilization/introduction into circulation. The format of response to request is
shown in Table 75. For error codes, see subsection 6.2.
Table 75 - Format of Response to Request
Field Description Type Mandatory
omsId Unique OMS identifier String (UUID) Yes
reportId Unique identifier of report on utilization/introduction into circulation
String (UUID) Yes
Response example is shown in Figure .
HTTP/1.1 200 OK Content-Length: 74 Pragma: no-cache X-XSS-Protection: 1; mode=block Expires: 0 X-Frame-Options: DENY X-Content--Options: nosniff Content-Type: application/json;charset=UTF-8 Cache-Control: no-cache, no-store, max-age=0, must-revalidate { "omsId" : "CDF12109-10D3-11E6-8B6F-0050569977A1", "reportId" : "46795d19-5024-404e-9275-959ac89ccb57" }
Response Example
Figure 57
102
4.5.18. Method “Request for the Document Number of Report on Introduction into
Circulation”
This method is used to obtain the identifier of TT GIS document on the introduction into
circulation report.
The security marker (token) generated by OMS during OMS client registration is sent to
server within HTTP-header with name “clientToken”. If the security marker (token) was obtained
during the call for method “Obtain security marker by username and password”, username shall
be sent within the HTTP-header named “userName”.
4.5.18.1. Restrictions
Currently this method is available for the milk producers.
4.5.18.2. Request
REST request parameters are provided below:
URL: http://<server-name>[:server-port]/api/v2/{extension}/
rollout?omsId={omsId}?reportId={reportId}
Method:GET
Content-type:application/json
clientToken:{clientToken}
userName:{userName}
Table 76 – Request String Parameters
Parameter Description Type Mandatory
omsId Unique OMS identifier String Yes
reportId Unique identifier of report on utilization/introduction into circulation
String Yes
Request Example is shown in Figure .
GET /api/v2/{extension}/rollout?omsId=123456789?reportId=46795d19-5024-404e-9275-959ac89ccb57 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Host: localhost:8080
Request Example
Figure 58
103
4.5.18.3. Response
Upon successful completion of request, the server returns HTTP code 200, a unique
identifier of document generated in TT GIS, its status, and rejection reason (if any). The format
of response to request is shown in Table 77. For error codes, see subsection 6.2.
Table 77 - Format of Response to Request
Field Description Type Mandatory
omsId Unique OMS identifier String (UUID)
Yes
documentId
Unique identifier of TT GIS document on introduction into circulation. TT GIS document identifier comes when the document has been successfully sent to TT GIS (status SENT)
String (UUID)
No
reportId Unique identifier of report on utilization/introduction into circulation
String (UUID)
Yes
status
Status:
− PENDING means the document is being processed;
− SENT means the document has been successfully sent to TT GIS;
− REJECTED means the document has been rejected.
String Yes
reason Document rejection reason String No
Response example is shown in Figure .
HTTP/1.1 200 OK Content-Length: 74 Pragma: no-cache X-XSS-Protection: 1; mode=block Expires: 0 X-Frame-Options: DENY X-Content--Options: nosniff Content-Type: application/json;charset=UTF-8 Cache-Control: no-cache, no-store, max-age=0, must-revalidate { "omsId": "CDF12109-10D3-11E6-8B6F-0050569977A1", "documentId": "46795d19-5024-404e-9275-959ac89ccb57", "reportId": "46795d19-5024-404e-9275-959ac89ccb52", "status": "SENT" }
Response Example
Figure 59
104
5. INPUT AND OUTPUT DATA
5.1. Nature, Arrangement and Initial Preparation of Input and Output Data
5.1.1. Information Sources
The main information sources for the system are:
7) Related information systems involved in both infocommunication and functional
exchange.
8) Data entered by system users.
Operations on:
9) analog-to-digital and digital-to-analog signal conversion;
10) optical character recognition;
11) other actions to bring information to a form suitable for computer processing
are not provided for as part of the OMS-Production 3.1 AS functions.
5.1.2. Methods of Data Collection, Transmission, Control and Correction
Arrangement
The information arrays are collected during the system operation through:
12) Receiving of structured XML-documents generated on the basis of specified XSD-
schemes via collaborative services.
13) User input of information in screen forms and its subsequent storage in the
database.
Data integrity control is implemented by the system application software and tools built
in the used DBMS (restrictions, indices, primary and secondary keys). Data entry and correction
shall be carried out only through the system software components. Direct user access to the
database is not expected.
The main requirements to the processes of data collection, transmission, control and
correction arrangement are to ensure the reliability, verifiability, confidentiality, accessibility,
efficiency of the data collected and transmitted.
The reliability requirement implies arrangement of the information collection and
transmission process, within the scope of which the transmitted and collected information will
not be subject to misrepresentation.
The verifiability requirement implies arrangement of the information collection and
transmission process which allows control over the reliability of the transmitted information.
The confidentiality requirement means provision of access to information in strict
adherence to the established access isolation priorities and rules.
105
The accessibility requirement means the fundamental possibility of obtaining the
collected information and its transfer.
The efficiency requirement implies such arrangement of the information collection and
transmission process, during which the available information will be transmitted in a time frame
acceptable for its analysis.
106
5.2. Format, Description and Encoding Method of the Input and Output
Data when Using API
Format, description and encoding method of the input and output data when using
API are provided in description of the relevant methods.
107
5.3. Guides Accessible via API
5.3.1. Guides to Control the Marking Codes
5.3.1.1. Guide “Method of Goods Introduction into Circulation”
List of possible values of guide “Method of goods introduction into circulation" is shown in
Table 78.
Table 78 – Possible Values of Guide “Method of Goods Introduction into Circulation”
Constant Value Type
PRODUCTION Manufacturing in the Russian Federation String
IMPORT Imported to the RF (Import) String
REMAINS
Marking of remains (available only for GG "Footwear", "Tires and new pneumatic rubber tires", "Photo cameras (except cine camera), flash lights and flash bulbs", "Items of clothing, bed, table, bath and kitchen linen")
String
CROSSBORDER Imported to the RF from the EEU countries (available only for GG “Footwear”)
String
Note: the choice of REMAINS introduction into circulation method for GG "Footwear" is
available only for goods produced/purchased before 7/1/2020 and is limited in time: for imported
goods (imported into the Russian Federation from 7/1/2020) until 8/1/2020; in other cases - until
9/1/2020.
5.3.1.2. Guide “Method of Individual Serial Number Generation”
The list of possible values of guide “Method of individual serial number generation" is
shown in Table 79.
Table 79 – Possible Values of Guide “Method of Individual Serial Number Generation”
Constant Value Type
SELF_MADE No assistance String
OPERATOR By TT IS operator String
5.3.1.3. Guide “Marking Type”
The list of possible values of guide “Marking type” is provided in Table 80.
Table 80 – Possible Values of Guide “Marking type”
Constant Value Type
PRODUCT_PACKAGE For consumer package String
PRODUCT For product String
PRODUCT_LABEL For product label String
108
5.3.1.4. Guide “Manufacturing Method”
List of possible values of guide “Manufacturing Method” is shown in Table 81.
Table 81 – Possible Values of Guide “Manufacturing Method”
Constant Value Type
SELF_MADE No assistance String
CEM LMC String
5.3.1.5. Guide “MC Templates”
List of possible values of guide “MC templates” is shown in Table 82.
Table 82 – Possible Values of Guide “Manufacturing Method”
Constant Value Type
1 01 + GTIN + 21 + serial (13 chars) String
2 01 + GTIN + 21 + serial (13 chars) String
3 01 + GTIN + 21 + serial (7 chars) String
4 GTIN + serial (7 chars) String
5 01 + GTIN + 21 + serial (13 chars) String
6
01 + GTIN + 21 + SERIAL (13 chars) + 17 + expDate (6 char) or 01 + GTIN + 21 + SERIAL (13 chars) + 7003 + expDate72 (10 char) or 01 + GTIN + 21 + SERIAL (13 chars)
String
7 01 + GTIN + 21 + serial (13 chars) String
8 01 + GTIN + 21 + serial (20 chars) String
9 01 + GTIN + 21 + serial (13 chars) String
10 01 + GTIN + 21 + serial (13 chars) String
11 01 + GTIN + 21 + SERIAL (13 chars) String
12 01 + GTIN + 21 + SERIAL (13 chars) String
Table 83 – Description of MC Templates
Name Description
Template 1 Light industry, footwear (applicable to footwear only)
Template 2 Medicines
Template 3 Cigarettes, cartons
Template 4 Cigarettes, packs
Template 5 Medicines (short verification code)
Template 6 Milk producers (short verification code)
109
Name Description
Template 7 Tire manufacturers (short verification code)
Template 8 Photo products manufacturers (short verification code)
Template 9 Perfumery products manufacturers (short verification code)
Template 10 Light industry (short verification code), excluding the footwear
Template 11 Bicycles and bicycle frames
Template 12 Wheelchairs
Note: Pack-template lacks AI in template and MC.
5.3.1.6. Guide “MC Array Status”
List of possible values of guide “MC Array Status” is shown in Table 84.
Table 84 – Possible Values of Guide “MC Array Status”
Constant Value Type
REQUEST_ERROR Incorrect request format String
REQUESTED MC array (pool) was requested in ER String
IN_PROCESS Processing in progress String
READY MC array (pool) ready for use String
CLOSED All MCs in array were fully utilized String
DELETED MC array exhausted and closed String
REJECTED Order not completed (incorrect order parameters—e.g., the order contains non-unique serial numbers)
String
110
State diagram is shown in Figure .
IN_PROCESS
В обработке
READY
Готов
REQUESTED
Запрошен
REJECTED
Отклонен
REQUEST_ERROR
Ошибка
CLOSED
Закрыт
DELETED
Удален
MC Array Status
Figure 60
5.3.1.7. Guide “Aggregation Type”
List of possible values of guide “Aggregation Type” is shown in Table 85.
Table 85 – Possible Values of Guide “Aggregation Type”
Constant Value Type
AGGREGATION New aggregation String
UPDATE
Update of existing aggregation
Note: selecting this value means repacking (only those
marking codes, which were sent within the current
request, will belong to the specified aggregate code).
String
5.3.1.8. Guide “MC Buffer Status”
List of possible values of guide “MC buffer status” is shown in Table 86.
Table 86 – Possible Values of Guide “MC Buffer Status”
Constant Value Type
PENDING MC buffer pending String
ACTIVE Buffer is created String
111
Constant Value Type
EXHAUSTED No more codes left in the buffer and pools of ER String
REJECTED Buffer is non-operational String
CLOSED Buffer is closed String
State diagram is shown in Figure .
ACTIVE
Активный
CLOSED
Закрыт
PENDING
В ожидании
REJECTED
Недоступен
EXHAUSTED
Исчерпан
MC Buffer Status
Figure 61
5.3.1.9. Guide “Report Processing Status”
List of possible values of guide “Report processing status” is shown in Table 87.
Table 87 – Possible Values of Guide “Report Processing Status”
Constant Value Type
DRAFT Report received by the OMS (Outdated, not applied) String
PENDING Report pending String
READY_TO_SEND Report ready to be sent to ER String
REJECTED Report rejected String
SENT Report sent String
112
State diagram is shown in Figure .
READY_TO_SEND
Готов к отправке
SENT
Отправлен
PENDING
В ожидании
REJECTED
Отклонен
Report processing status
Figure 62
5.3.1.10. Guide “Type of Utilization”
List of possible values of guide “Type of utilization” is shown in Table 88.
Table 88 – Possible Values of Guide “Type of Utilization”
Constant Value Type
USED_FOR_PRODUCTION MC sent to production line String
SENT_TO_PRINTER Production line sent MC to printer String
PRINTED MC printed String
PRINTER_LOST MC lost by printer—confirmed String
VERIFIED MC application—confirmed String
5.3.1.11. Guide “Order Status”
List of possible values of guide “Order status” is shown in Table 89.
Table 89 – Possible Values of Guide “Order Status”
Constant Value Type
CREATED Order created String
PENDING Order awaiting confirmation by TT IS String
DECLINED Order is not confirmed in TT IS String
APPROVED Order is confirmed in TT IS String
READY Order ready String
CLOSED Order closed String
113
State diagram is shown in Figure .
APPROVED
Подтверждён
READY
Готов
PENDING
В ожидании
DECLINED
Отклонен
CREATED
Создан
CLOSED
Закрыт
Order status
Figure 63
5.3.1.12. Guide “Dropout Reason”
List of possible values of guide “Dropout Reason” is shown in Table 90.
Table 90 – Possible Values of Guide “Dropout Reason”
Code Constant Description Type
0 DEFECT Defect String
1 EXPIRY Shelf life is expired String
2 QA_SAMPLES Laboratory test samples String
3 PRODUCT_RECALL Recalled from market String
4 COMPLAINTS Complaints String
5 PRODUCT_TESTING Product testing String
6 DEMO_SAMPLES Demo samples String
7 OTHER Other reasons String
114
5.3.1.13. Guide “Marking Code Type”
Table 91 shows a list of possible values for guide “Marking code type”.
Table 91 – Possible Values of Guide “Marking Code Type”
Constant Description Type
UNIT Goods item String
BUNDLE Bundle String
115
6. MESSAGES
6.1. Messages to the Operator transmitted via GUI
6.1.1. Information windows
If any error occurs during the program execution, a red pop-up window opens in the
Web-browser with two types of messages:
14) Program entry error message (Figure ).
Program entry error message
Figure 64
15) System error message (Figure ).
System error message
Figure 65
116
6.2. Error Format and Codes
6.2.1. Error format
The format of response with error is shown in Table 92.
Table 92 – Format of Response with Error
Field Description Type
fieldErrors Error JSON Array Of
ProtobeansError Object
globalErrors Description of global errors JSON Array Of string
success Request execution result Boolean
For the description of object “ProtobeansError” format, see Table 93.
Table 93 – Object “ProtobeansError” Format
Field Description Type
fieldError Error description String
fieldName Field name String
Example of JSON response with error is shown in Figure .
{ "fieldErrors": [ { "fieldError": "string", "fieldName": "string" } ], "globalErrors": [ "string" ], "success": false }
Example of JSON response with error
Figure 66
6.2.2. Description of Errors
Error codes in response to request are shown in Table 94.
117
Table 94 – Data Send Error Codes
Error code Description
400 Operation not completed. Wrong input parameters
500 Operation not completed. Internal server error.
118
7. MATRIX OF PROVISION OF OMS API 2.0 SERVICES BY OMS
SOFTWARE PACKAGE COMPONENTS
Matrix of provision of OMS API 2.0 services by OMS software package components is
shown in this section (Table 95).
Table 95 – OMS API 2.0 Services Provision Matrix
OMS API 2.0 Method OMS-Client OMS-
Production OMS-Cloud
1. Create order for emission of marking codes.
● ● ●
2. Send report on MC dropout/rejection.
● ● ●
3. Send report on MC aggregation
● ● ●
4. Send report on MC utilization.
● ● ●
5. Close the suborder by the GTIN specified.
● ● ●
6. Obtain MC from the order.
● ● ●
7. Obtain MC array status from the order
● ● ●
8. Obtain the status of orders
● ● ●
9. Obtain the aggregation information
● ● ●
10. Obtain the report processing status
● ● ●
11. Send APCS log files ● ● ●
12. Check OMS availability
● ● ●
13. Obtain security marker by username and password
● ● ○
14. Obtain OMS and API version;
● ● ●
15. Obtain the list of marking code package identifiers;
● ● ●
119
OMS API 2.0 Method OMS-Client OMS-
Production OMS-Cloud
16. Re-obtain marking codes from marking code order
● ● ●
17. Send report on the utilization and automatic introduction into circulation
● ● ●
18. Request for the document number of report on introduction into circulation
● ● ●
120
8. OMS API 2.0 USE EXAMPLES
This section contains OMS API 2.0 use examples.
8.1. Signing Requests with the Electronic Digital Signature
This subsection describes the method of signing an HTTP request using the example of
CryptoPro JCP library from CRYPTO-PRO Limited Liability Company. When using a library of
other crypto provider, follow the guidelines for the selected library.
Before using other libraries, make sure that the library supports the required standards
which can be found in subsection 2.3.
8.1.1. Library “CryptoPro JCP”
To get the CryptoPro JCP library, go through the registration procedure on the official
website of CRYPTO-PRO Limited Liability Company (https://www.cryptopro.ru/). After
registration, go to the "Download Center" section and select the required library from the list, in
our case it is "CryptoPro JCP" (Figure ).
121
List of CryptoPro Software Products
Figure 67
After clicking on the "CryptoPro JCP" link, the user gets the list of library versions
available for downloading (Figure ).
122
List of “CryptoPro JCP” Versions
Figure 68
After downloading the selected version, get access on your computer to archive "jcp-
2.0.40035.zip" with the library and examples of use (see Figure ).
123
Content of “CryptoPro JCP” Library
Figure 69
The “sample-sources” directory contains a subdirectory “CMS_samples”, which
provides an example of classes and functions to generate a detached signature of CMS
format [IETF RFC 5652] (Figure ).
Examples of “CryptoPro JCP” Use
Figure 70
124
The next section provides an example of calling a function to sign a request using
detached signature in CMS format [IETF RFC 5652]; the requirements for request signing are
given in section 2.3.1.
8.1.2. Example with the Use of Library to Sign the Request
Below is an example of using “CryptoPro JCP” library using classes from the
examples distributed with the library.
Note: The program code in the examples distributed with the library is intended for
training purposes. This code cannot be directly used to protect information. Crypto-Pro
company does not bear any responsibility for the operation of this code. (C) Crypto-Pro, LLC
2004-2007.
To sign the request, the data must be converted into a byte array and sent to
CMS.CMSSignEx signature method of the library, see the method parameters below (Table
96). To generate a detached signature, parameter “detached” shall contain value “true”.
Table 96 - Parameters of CMS Format Signature Generation Function.
Description
/** * sign CMS * * @param data - Signed data array * @param key - Private key * @param cert cert - Certificate * @param detached - Detached signature use attribute * @param digestOid - OID of hashing algorithm * @param signOid - OID of signature algorithm * @param signAlg – Signature algorithm name * @param providerName – Provider name; * @throws Exception e */ public static byte[] CMSSignEx(byte[] data, PrivateKey key, Certificate cert, boolean detached, String digestOid, String signOid, String signAlg, String providerName) throws Exception { // sign final Signature signature = Signature.getInstance(signAlg, providerName); signature.initSign(key); signature.update(data); final byte[] sign = signature.sign(); // create cms format return createCMSEx(data, sign, cert, detached, digestOid, signOid); }
125
The function execution result is the signature of CMS format [IETF RFC 5652], the
generated signature of the message request in CMS format fit in the HTTP header in “X-
Signature” parameter in Base64 encoding.
Verification of the generated request signature fit in HTTP in “X-Signature” parameter can
be performed with the support program use of cURL command-line designed to transfer data
using cURL syntax.
An example of command used to verify the request signature is shown below (Table 97).
Table 97 - Example of Command to Verify the Request Signature
Description
curl -X POST "https://intuot.crpt.ru:12011/api/v2/light/orders?omsId=" -H "@headers.txt" -H "@XSignature.txt" --data "@order.json" PAUSE >nul
Where:
16) URL: address of the resource where the request is sent;
17) "@headers.txt" – file containing the HTTP header of the request (excluding “X-
Signature” parameter);
18) "@XSignature.txt" – file containing parameter “X-Signature” from the request HTTP
header;
19) "@order.json" – file containing the request data.
126
APPENDIX
LIST OF APPLICATION PROGRAMMING INTERFACE CHANGES
List of registered changes
Version Date OMS
version List of Modifications
2.81 11/05/2020 3.1.13
The following modifications were introduced:
- Note added that the method to send a report on Dropout/Rejection of MC is available for “Dairy Products” goods group 9 (see Section 4.5.2);
- The stints field description amended in the structure DropoutReport object used in the request of sending the report on dropout/rejection of MC: the field must now contain full marking codes, including the verification code (see Section 4.5.2.1);
- Added an example of REST request for sending a report on dropout/rejection of MC containing the DropoutReport object and no extensions (used for Dairy Products) (see Section 4.5.2.1).
2.80 5/7/2020 3.1.12
The following modifications were introduced:
- Typo corrected in templateId in the example of order creation for goods group “Items of Clothing, Bed, Table, Bath and Kitchen Linen”: value 1 changed to 10 (see Section 4.5.1.1.2)
- Typo corrected in the display of the list of goods group codes: bicycle and wheelchairs code added (see Section 4.5)
- Example of order creation for the “Medicines for Human Use” goods group was changed: templateId changed to 5, emission payment attribute freeCode changed to false, paymentType changed to 2 (see Section 4.5.1.1.7)
- Note to field serialNumberType for order creation request was changed: the initially set field value can not be changed for one GTIN for the “Tobacco Products” goods group only (see Section 4.5.1.1)
- Unused guides were deleted from the list of guides: “IM Type” (printable, adhesive, hanging), “Method of Receipt” (hard copy, soft copy).
2.79 4/24/2020 3.1.12
The following modifications were introduced:
- Guide for marking code types was added (see Section 5.3.1.13)
- “cisType” (marking code type) field was added to the “OrderProduct” object extension used in the order creation request for three goods groups: “Items of clothing, bed, table, bath and kitchen linen”, “Perfume and eau de toilette”, “Photo cameras (except for cine cameras), flash lights and flash bulbs” (see Sections 4.5.1.1.2, 4.5.1.1.5, 4.5.1.1.6).
2.78 4/22/2020 3.1.12
The following modifications were introduced:
− Note on automatic sending of utilization reports was added (see Section 4.5.4);
127
List of registered changes
Version Date OMS
version List of Modifications
− Note on the meaning of UPDATE aggregation type was added (see Section 5.3.1.7).
2.77 4/17/2020 3.1.12
The following modifications were introduced:
- A note is added that the value “IMPORT” of the Method of goods release into circulation is currently invalid for goods category “Dairy products” (see section 4.5.1.1.8);
- A note is added that the value of “type” field of “LP_GOODS_IMPORT_AUTO” is currently invalid when sending a report on automatic release into circulation for goods category “Dairy products” (see section 4.5.17.2);
- The note about permitted values of the aggregate code is changed for goods category “Dairy products”: it shall contain the shipping package code SSCC (see section 4.5.3.1);
- Duplicating words are removed in the note for “exporterTaxpayerId” field (see section 4.5.1.1.3).
2.76 4/13/2020 3.1.12
The following modifications were introduced:
- “customsReceiverId” field description and conditions of its use in the structure of request for sending report on utilization were added - for medicines (see section 4.5.4.1.2);
- description of modified conditions of “controlId” field usage in the structure of request for sending report on utilization was added - for medicines (see section 4.5.4.1.2)
2.75 3/20/2020 3.1.10.7.
3
The following modifications were introduced:
- Description of the permitted range for expDate, expDate72 dates was added;
- Misprint in freeCode field name was corrected: The Russian letter “C” was changed to the English one;
- Broken link to section 2.2.15 in section 2.2.16 was corrected.
2.74 3/18/2020 3.1.10.7.
3
The following modifications were introduced:
- The wording regarding the signature for a number of product groups was changed: if signing of order via API is not used, then signing via UI is required;
- Misprint with “expectedCompleteTimestamp” field name in the description of the response to the order creation request was corrected.
2.73 3/10/2020 3.1.10.7.
3
The following modifications were introduced:
- According to WMS (No. 216 of 2/29/2020), restrictions on marking of the footwear remains were changed: dates 3/1/2020, 4/1/2020 and 5/1/2020 were changed to 7/1/2020, 8/1/2020 and 9/1/2020 respectively.
2.72 3/1/2020 3.1.10.7.The following modifications were introduced:
− The Note was added to the introduction into circulation method
128
List of registered changes
Version Date OMS
version List of Modifications
1 «REMAINS».
− Misprints with indication of GG, for which introduction into circulation method «REMAINS» is available, were corrected.
− “Order” object extension was added in the request for creation of order for GG “goods”
2.71 2/25/2020 3.1.10
The following modifications were introduced:
− Notes to sub-clauses “Method “Create order for emission of marking codes” and Method “Obtain the status of orders” were updated
2.70 2/19/2020 3.1.10
The following modifications were introduced:
− The text of Notes in subsection “General information” was changed.
− Links to API methods in subsection “General information” were added.
− In the first example of response to request for MC array status (suborder) from the order, a misprint with missing mandatory fields was corrected
2.69 2/17/2020 3.1.10
The following modifications were introduced:
− Note was added to the format of of response to request for marking code array status (suborder) from the order, as well as additional example – in case of the order decline
2.68 2/14/2020 3.1.10
The following modifications were introduced:
− Valid values were provided for “certificateDocument” field in the request for sending the report on utilization and automatic introduction into circulation.
− The Note was added reading that calling the order creation method from one source cannot be realized more often than one time per second.
− The misprint in the name of “exporterTaxpayerId” field in the note under relevant table was corrected
− In response to the request for the number of document on introduction into circulation, the name of “rejectedReason” field was changed to correct “reason”.
− The name of the method in the example of the response to the request for the number of document on introduction into circulation was changed from “exploitation” to “rollout”.
− The format of “subjectId” field in the example of a request for sending report an application for the pharmaceutical industry in case of production outside the Russian Federation was corrected. − In the examples of the utilization and automatic introduction into circulation report sending method, the format of fields “accompanyingDocument” and “code” was corrected
129
List of registered changes
Version Date OMS
version List of Modifications
2.67 1/22/2020
3.1.10
The following modifications were introduced:
− Non-mandatory fields were added to examples for several API.
− For dropout, aggregation and utilization report sending methods, the Notes contain the goods groups for which these methods are not accessible.
− In the example of order creation for the goods group “Perfumes and Eau de Toilette”, the template number was changed from 7 to 9.
− In the second example of sending the utilization report for the goods group “Medicines” (if they are produced outside the Russian Federation), mandatory field “controlId” was added.
− Parameter “usedInProduction” was added to the description of the utilization report sending method for the goods group “Milk”.
− In the example of obtaining package identifiers, field “gtin” mistakenly used for the second time was replaced with the correct “omsId”.
− In the description of the the utilization and automatic introduction into circulation report sending method, the type of the “tnvedCode” field was changed to string one.
− The section describing examples of sending an aggregation report for milk producers was added; − In sub-clause “Request” of “Send MC aggregation report” method, the description of “sntins” field in the relevant table was extended and a Note was added to “unitSerialNumber” field.
2.66 12/30/2019 3.1.10
The following modifications were introduced:
− In Guide No. 1. the description of constant IMPORT in Russian was changed from “Imported” to “Imported to the RF (import)”.
− In Guide No. 14, the description of constant EXPIRY in Russian was changed from “Expiration” to “Expired”
2.65 12/19/2019 3.1.10
The following modifications were introduced:
− The utilization and automatic introduction into circulation report sending method and request for the number of document on introduction into circulation were added
2.64 12/3/2019 3.1.10
The following modifications were introduced:
− The option of repetitive MC obtaining was added.
− Parameters “productionLineId”, “productionOrderId” were transferred to a separate extension for the tobacco industry from the response of the method for obtaining information on aggregation.
− An extension of “OrderProduct” object for GG “goods” was added.
− The type of “accompanyingDocument” field (Production veterinary accompanying document) was changed from String (UUID) to String
2.63 11/28/2019 3.1.9.4
The following modifications were introduced:
− The method for obtaining the commodity nomenclature guide (product/info) was removed.
− GG “Dairy products” support was restored
2.62 11/20/2019 3.1.9 The following modifications were introduced:
− The order closure description was changed
130
List of registered changes
Version Date OMS
version List of Modifications
2.61 11/15/2019 3.1.9 The following modifications were introduced:
− GG “Dairy products” support was removed
2.60 11/7/2019 3.1.9
The following modifications were introduced:
− The new value “CROSSBORDER” (Imported to the RF from the EEU countries) was added to Guide “Method of Goods Introduction into Circulation”. Available for GG “Footwear” only
2.59 10/29/2019 3.1.9
The following modifications were introduced:
− MC templates were changed for GG “Dairy products”
− The “Order” object extension in the order structure was added for GG “Dairy Products”.
− “UtilizationationReport” object extension in the utilization report was added for GG “Dairy Products”.
− For the pharmaceutical industry, the bindingness parameters were changed in the “Order” object.
− For the pharmaceutical industry, the field “Production Date” was added to the request for the usage (application) report generation.
− Extensions of the base object “Order” were added for GG "Bicycles and Bicycle Frames" and "Wheelchairs".
− The Note was added, if the fields "sourceDocDate" and "sourceDocNum" in the request for dropout (rejection) report creation for GG “Tobacco” are not filled, they shall be filled in automatically by OMS.
− Guide “Dropout Reason” was updated
2.58 10/11/2019 3.1.8
The following modifications were introduced:
− The section with the list of methods was restructured, sections “Formation of GS1 DataMatrix” and “JSON Processing” were added.
− The method to obtain the OMS and API version was added.
− For categories of goods groups (Items of clothing, bed linen, table linen, bath and kitchen linen, Footwear, Perfume and Eau de Toilette, Tyres and new pneumatic rubber tire casings and Photo cameras (except cine camera) flash lights and flash bulbs) in the order extension object, the attributes “Number of contract with Operator” (contractNumber) and “Date of contract with operator” (contractDate) are non-mandatory and are not currently used (will be excluded in the future)
2.57 10/10/2019 The following modifications were introduced:
− In the response to request for MC from the order, the “blockld” parameter was updated with UUID format indication
2.56 10/3/2019 The following modifications were introduced:
− Description of requirements for transmission of detached digital signature was updated
2.55 10/2/2019 The following modifications were introduced:
− Section with description of requirements for transmission of detached digital signature was added
2.54 9/30/2019 The following modifications were introduced:
131
List of registered changes
Version Date OMS
version List of Modifications
− Description of extensions was updated.
− Extension of the order for Light Industry for the goods group category “ goods” and category “Items of clothing, bed linen, table linen, bath and kitchen linen” were transformed into separate extensions.
− Extension for the order for tire manufacturers for the goods group category “Tires and new pneumatic rubber tire casings” was updated.
− Extension for the order for perfumery products manufacturers for the goods group category “Perfume and Eau de Toilette” was updated.
− Extension for the order for photo products manufacturers for goods group category “Photo cameras (except cine cameras), flash lights and flash bulbs” was updated.
− For the pharmaceutical industry, description of extension for the order was updated
2.53 9/25/2019
The following modifications were introduced:
− The information attribute “offset” is excluded in MC obtaining response
2.52 9/24/2019 The following modifications were introduced:
− The compulsoriness of attribute “contactPerson” was corrected, the attribute is mandatory
2.51 9/23/2019 The following modifications were introduced:
− Valid marking codes according to GS1 specification were updated
2.50 9/20/2019 The following modifications were introduced:
− For the Tobacco industry, the “sourceReportId” attribute is updated in the extension of MC utilization report
2.49 9/20/2019
The following modifications were introduced:
− For the tobacco industry, the example of the MC utilization report sending request was updated.
− The information attribute “offset” was added in the response when obtaining MC.
− Attributes “freeCode” and “payment” were added to the extension of object “Order” for the pharmaceutical industry.
− Value “REMAINS” was added to the guide “Method of goods introduction into circulation”.
− Attributes “contractNumber” and “contractDate” were added to the extension of object “Order” for the light industry.
− The product registration API was excluded from the document
2.48 8/29/2019
The following modifications were introduced:
− The description of the product registration API (Product Registration API ) was added.
− Non-mandatory parameter “brandcode” was added to the extension for the tobacco industry
2.47 8/23/2019 The following modifications were introduced:
132
List of registered changes
Version Date OMS
version List of Modifications
− Restriction on the number of marking codes was added to the dropout report
2.46 8/20/2019 The following modifications were introduced:
− The restriction and parameter “tokenName” were added to the method of obtaining security marker by username and password
2.45 8/15/2019
The following modifications were introduced:
− In the Light Industry extension of the order object, the following attributes shall be excluded:
o CEM name (cemName). o CEM contract number (cemContractNum). o CEM contract date (cemContractNum). o CEM INN (cemInn). o Delivery address (deliveryAddress). o IM type (identification). o Marking (marking). o Receiving method (receiveМethod).
− In extension for Light Industry, the related object “DeliveryAddress” was removed
2.44 8/5/2019
The following modifications were introduced:
− Explanation regarding the serial numbers generation method was added.
− Explanation to template 1 and 10 was added
2.43 8/1/2019 The following modifications were introduced:
− The maximum amount of MC in the utilization report (30,000 MC) was changed
2.42 7/31/2019 The following modifications were introduced:
− Template for the Light Industry was added
2.41 7/26/2019 The following modifications were introduced:
− The marking code order closure rule (Note) was added.
− The marking code order obtaining rule (Note) was added
2.40 7/22/2019
The following modifications were introduced:
− The marking code templates for photo and perfumery products manufacturers were added.
− In addition to description of MC array statuses, the state diagram was provided.
− In addition to description of MC buffer statuses, the state diagram was provided.
− In addition to description of the report processing statuses, the state diagram was provided.
− In addition to description of the order statuses, the state diagram was provided.
− The Note, containing restrictions on the number of marking codes in the order and the number of goods items in one order, was added to the description of method “Create order for emission of marking codes”; for the tobacco industry, information on MRP was added.
133
List of registered changes
Version Date OMS
version List of Modifications
− In method “Send report on MC dropout/rejection”, changes regarding the marking code included in the report (GTIN + serial #) were made
2.39 7/17/2019
The following modifications were introduced:
− Two fields were added to "BufferInfo" object: rejectionReason, totalPassed.
− The field “declineReason” was added to object “OrderSummaryInfo”.
− The “draft” report send status was indicated as outdated, not used
2.38 7/8/2019 “omsId” format (UUID) was updated in the document. The request and response examples were corrected.
2.37 7/5/2019
1. The following modifications were introduced for milk producers:
− The marking code template (template 6) was changed.
− Extension for the object “OrderProduct”, including fields “expDate” and “expDate72”, was added.
2. The following changes (not affecting the integration implementation) were made for the tobacco industry:
− Extension for the object “OrderProduct” (Table 7), including field “mrp”, was added
2.36 7/5/2019 Subsections of the object model extensions for goods groups were added
2.35 7/4/2019 The OMS API 2.0 services provision matrix was added.
2.34 7/4/2019 Changes were made to the format of the marking code template for
light industry, the FEACN code is excluded from the marking code template
134
LIST OF TERMS
The following terms are used in this document:
1) Hardware — PC (personal computer) or another computer equipment (mainframe,
minicomputer, microcomputer, PDA (pocket digital assistant), computer terminal).
2) Individual user’s hardware is a computer equipment providing the following:
− automation of computer component for the daily work of the Customer’s personnel;
− access to information services automating processes of the Customer’s enterprise.
3) Shared hardware is a computer equipment intended for
− arrangement of a computational platform automating processes of the Customer;
− adjustment and control of hardware included into the automated system;
− accumulation and processing of data used at automation of processes of the Customer.
4) General software is a complex of program components providing minimal hardware
functionality:
− environment for start and operation of other program tools (operating system);
− tools for operation with structured data sets (DBMS);
− tools for accessing Internet resources (Web-browser);
− tools for hardware resources publication on the Internet (Webserver).
5) Special software is a set of software components specially developed for particular
hardware (not a “box version” software).
6) End hardware is equipment and devices directly managed by automated system (via
information communication channels) or indirectly (via functional interface with related
systems) and intended for performance of process functions (printer, scanner, registrar,
controller etc.).
7) Aggregation is a process of bundling products (in consumer package) into a first-level
shipping package, as well as of first-level shipping packages into higher-level shipping
package with application of shipping package identification code to the shipping
package specifying information on the correlation among the identification codes of
each included product, consumer package, shipping package.
8) Introduction of goods into circulation when manufacturing goods:
− in the territory of the Russian Federation, entering of goods on the balance sheet of the
manufacturer of such goods or initial compensatory or non-compensatory transfer of
goods from the manufacturer to the new owner or another person for the purpose of
alienation or for further sale making these goods available for distribution and/or use;
135
− in the territory of the Russian Federation, in case of contract manufacturing, entering of
goods produced within and under the contract and transferred from the goods
manufacturer, to the balance sheet of the goods owner;
− outside the territory of the Russian Federation (excluding goods imported from the
Eurasian Economic Union member states), customs release for domestic consumption
of goods imported into the territory of the Russian Federation;
− outside the territory of the Russian Federation for the goods imported from the Eurasian
Economic Union member states within the cross-border trade in the customs territory of
the Eurasian Economic Union, import of goods by a legal entity or an individual
registered as individual entrepreneur into the Russian Federation.
A proposal for sale (sale), made by a commission agent, of goods received from
individuals who are not individual entrepreneurs (with the exception of goods previously
purchased and returned by individuals who are not individual entrepreneurs) is also
recognized as introduction into circulation within the commission agreement, including a
offering goods for further trade (sale) prior to their display at the point of sale and upon
display at the place of sale, demonstration of their samples or the provision of
information about them at the place of sale.
9) Track and Trace Government Information System for the goods subject to the mandatory
marking with the identification means (Track and Trace Information System, TT GIS) is
a government information system created to automatize the processes of acquisition
and processing of data on circulation of goods subject to mandatory marking with the
identification means, store such information, provide access to it, deliver and distribute
it, enhance the exchange efficiency for such information, and enable traceability of the
goods mentioned, as well as for other purposes as stipulated in the federal laws.
10) Importer of goods (importer) is a legal entity or individual registered as an individual
entrepreneur, who imports goods to the Russian Federation from the territories of the
states which are not members of the Eurasian Economic Union, or goods purchased in
the framework of cross-border trade in the customs territory of the Eurasian Economic
Union.
11) Individual Serial Number (ISN) is a sequence of symbols that distinctly identifies a
goods item (consumer package of goods) on the basis of the goods code.
12) Electronic Interface is aggregated resources and rules that enable interaction between
the goods circulation participants’ firmware and Track and Trace Information System.
136
13) Identification Code (IC) is a sequence of symbols comprising a unique number of goods
item formed by the Track and Trace Information System operator in order to identify
goods, including those in consumer package.
The identification code consists of the first and second groups of the marking code data
groups:
− the first group consists of 14 digits and contains the goods code, which is preceded by
the application identifier (01), is generated by the operator on the basis of information
provided by the goods circulation participant when registering goods in the Track and
Trace Information System;
− the second group consists of 13 characters (digits, lowercase and uppercase letters of
the Latin alphabet, as well as special characters) and contains the individual serial
number of the goods item, which is preceded by the application identifier (21) and which
is generated by the operator or goods circulation participant. The ending character for
this data group shall be the delimiter having code 29 in the ASCII character table.
14) Shipping Package Identification Number (SPIN) is a sequence of symbols comprising a
unique item of the goods shipping package in the form of a one-dimensional bar code
which complies with GS1-128 international standard. The content of the transport
packing identification code shall be determined by the goods circulation participant who
carries out aggregation of goods into transport packing.
15) Marking Code (MC) is a unique sequence of symbols consisting of identification and
verification codes, generated by the operator in order to identify goods, including those
in consumer package.
The marking code includes 4 groups of data, where the first and second groups form
identification code, while the third and fourth groups form verification code:
− the first group consists of 14 digits and contains the goods code, which is preceded by
the application identifier (01), is generated by the operator on the basis of information
provided by the goods circulation participant when registering goods in the Track and
Trace Information System;
− the second group consists of 13 characters (digits, lowercase and uppercase letters of
the Latin alphabet, as well as special characters) and contains the individual serial
number of the goods item, which is preceded by the application identifier (21) and which
is generated by the operator or goods circulation participant. The ending character for
this data group shall be the delimiter having code 29 in the ASCII character table;
137
− the third group consists of 4 characters and contains verification code, which is preceded
by the application identifier (91) generated by the operator. The ending character for this
data group shall be the special character-delimiter having code 29 in the ASCII
character table;
− the fourth group consists of 88 characters (digits, lowercase and uppercase letters of the
Latin alphabet, and special characters) and contains verification code, which is
preceded by the application identifier (92) generated by the operator. The ending
character for this data group shall be the special character-delimiter having code 29 in
the ASCII character table.
16) Verification Code (VC) is a sequence of symbols generated by the operator as a result
of cryptographic conversion of identification code which allows fake identification code
detection while checking it with the use of a fiscal memory device and (or) technical
means intended to check the verification code. It includes the third and the fourth
marking code data groups.
− the third group consists of 4 characters and contains verification code, which is preceded
by the application identifier (91) generated by the operator. The ending character for this
data group shall be the special character-delimiter having code 29 in the ASCII
character table;
− the fourth group consists of 88 characters (digits, lowercase and uppercase letters of the
Latin alphabet, and special characters) and contains verification code, which is
preceded by the application identifier (92) generated by the operator. The ending
character for this data group shall be the special character-delimiter having code 29 in
the ASCII character table.
17) Goods Code (GC, GTIN) is a unique code assigned to a group of goods while
describing them at an information resource that enables accounting and storage of
reliable data on the goods by corresponding codes of the unified Foreign Economic
Activity Goods Nomenclature of the Eurasian Economic Union (the goods
nomenclature).
18) Contract manufacturing means manufacturing to order of goods under the customer’s
trademark at capacities of a third party that ensures full observance of technological
cycle and quality control regarding finished goods in accordance with the customer’s
requirements.
138
19) User Account (UA) is an information service located in the Internet at the operator
website, duly provided by the operator to a goods circulation participant or a federal
executive body, and used by the operator, goods circulation participant and federal
executive body.
20) Marked Goods are goods with identification means applied, the reliable information of
which (including information about the applied identification means and/or material
media having the identification means) is contained in the Track and Trace Information
System.
21) Marking of goods with the identification means is application of goods identification
means on the consumer package, or product label, or goods.
22) Goods Circulation means import into the Russian Federation, storage, transportation,
reception and transfer of goods including procurement and implementation (sale)
thereof in the territory of the Russian Federation.
23) Operator of the Track and Trace Information System (operator) is a legal entity
registered in the territory of the Russian Federation, creating, developing, updating, and
operating the Track and Trace Information System, ensuring its full availability, as well
as receiving, storing and processing the information.
24) Remarking of goods is the repeated application of identification means on consumer
package, or goods, or product label due to the loss or damage of previously applied
identification means.
25) Consumer Package is a package intended for primary packaging of goods, as well as
materials and components used for storage and presentation of goods sold to the end
consumer along with the goods.
26) Goods Producer (producer) is a legal entity or an individual registered as an individual
entrepreneur, being tax resident of the Russian Federation, which exercises production
and sale of goods.
27) Identification Means of goods (identification means, IM) is a marking code in machine-
readable form represented as a bar-code to be applied to the consumer package, or
product label, or goods.
28) Product Label is a data media designed for marking information on the goods including
goods identification means, attached directly to the consumer package or included into
the consumer package.
139
29) Shipping Package of goods is a package consolidating goods used for storage and
transportation of goods to protect them from transportation damages, and constituting a
separate transportation unit. A shipping package may contain smaller shipping
packages (by size or volume). Therewith, a package consolidating only goods with or
without consumer package shall be considered as a first-level shipping package, while
further shipping packages of various enclosure levels, starting from those containing
first-level shipping packages only, shall be considered shipping packages of subsequent
(second, third, etc.) level.
30) Emission registrar (ER) is a software and hardware encryption (cryptographic) technical
means including a validator of verification code or compliant with the requirements to a
validator of verification code, used by goods circulation participants to exchange
information with the Track and Trace Information System in terms of obtainment of
marking codes by the goods circulation participants and transfer of information to the
Track and Trace Information System regarding the goods marking with identification
means; for which the Federal Security Service of the Russian Federation issued a
document on its compliance with the established requirements to encryption
(cryptographic) means of information protection applicable to encryption (cryptographic)
means for verification of marking codes.
31) Goods Circulation Participants are legal entities and individuals registered as individual
entrepreneurs, being tax residents of the Russian Federation, exercising introduction of
goods into circulation, circulation and/or withdrawal of goods from circulation, excluding
legal entities and individuals registered as individual entrepreneurs procuring goods to
be used in purposes not related to their further trade (sale).
32) Eurasian Economic Union (EEU) is an international organization of regional economic
integration having the international legal personality and established by the Treaty on
the Eurasian Economic Union. Member States of the Eurasian Economic Union are the
Republic of Armenia, the Republic of Belarus, the Republic of Kazakhstan, the Kyrgyz
Republic and the Russian Federation.
33) The Eurasian Economic Commission (EEC) is a permanent regulatory body of the
Eurasian Economic Union, providing conditions for the EEU functioning and
development, development of proposals for the further integration development.
34) Technical Support Service (TSS) is a technical support service for the Track and Trace
Information System users.
140
35) Goods nomenclature for foreign economic activities of the Eurasian Economic Union
(goods nomenclature) is the goods classifier used by customs authorities and
participants of foreign economic activities (FEA) to perform customs operations.
36) EQES is an enhanced qualified electronic signature.
141
LIST OF ABBREVIATIONS
AWS Automated working station AS Automated system APCS Automated process control system EEU Eurasian Economic Union is an international organization of regional economic
integration having the international legal personality and established by the Treaty on the Eurasian Economic Union. Member States of the Eurasian Economic Union are the Republic of Armenia, the Republic of Belarus, the Republic of Kazakhstan, the Kyrgyz Republic and the Russian Federation
IS Information security TT IS Track and Trace Information System MC Marking code GC Goods code, GTIN HC Hardware complex LAN Local area network UA Unauthorized access LAN Local area network NC National Catalog EHW End hardware OS Operating system GSW General software SW Software SHP Software and hardware package PC Personal computer OR Operation registrar ER Emission registrar VPM Virus protection means HW Hardware IM Identification means SCS Structures cable system IPT Information protection tool SSW Specialized software NT Networking tools OMS Order Management Station ES Emission server TOR Terms of reference GCP Goods Circulation Participant
142
LIST OF FIGURES
Figure 1 ...................................................................................................................................... 13
Figure 2 ...................................................................................................................................... 14
Figure 3 ...................................................................................................................................... 17
Figure 4 ...................................................................................................................................... 19
Figure 5 ...................................................................................................................................... 20
Figure 6 ...................................................................................................................................... 22
Figure 7 ...................................................................................................................................... 27
Figure 8 ...................................................................................................................................... 29
Figure 9 ...................................................................................................................................... 32
Figure 10 .................................................................................................................................... 34
Figure 11 .................................................................................................................................... 36
Figure 12 .................................................................................................................................... 38
Figure 13 .................................................................................................................................... 39
Figure 14 .................................................................................................................................... 41
Figure 15 .................................................................................................................................... 42
Figure 16 .................................................................................................................................... 43
Figure 17 .................................................................................................................................... 44
Figure 18 .................................................................................................................................... 46
Figure 19 .................................................................................................................................... 47
Figure 20 .................................................................................................................................... 48
Figure 21 .................................................................................................................................... 51
Figure 22 .................................................................................................................................... 52
Figure 23 .................................................................................................................................... 53
Figure 24 .................................................................................................................................... 54
Figure 25 .................................................................................................................................... 57
Figure 26 .................................................................................................................................... 60
Figure 27 .................................................................................................................................... 61
Figure 28 .................................................................................................................................... 62
Figure 29 .................................................................................................................................... 63
Figure 30 .................................................................................................................................... 64
Figure 31 .................................................................................................................................... 65
Figure 32 .................................................................................................................................... 67
Figure 33 .................................................................................................................................... 68
Figure 34 .................................................................................................................................... 69
Figure 35 .................................................................................................................................... 71
Figure 36 .................................................................................................................................... 72
Figure 37 .................................................................................................................................... 73
143
Figure 38 .................................................................................................................................... 75
Figure 39 .................................................................................................................................... 76
Figure 40 .................................................................................................................................... 78
Figure 41 .................................................................................................................................... 79
Figure 42 .................................................................................................................................... 80
Figure 43 .................................................................................................................................... 81
Figure 44 .................................................................................................................................... 82
Figure 45 .................................................................................................................................... 83
Figure 46 .................................................................................................................................... 84
Figure 47 .................................................................................................................................... 85
Figure 48 .................................................................................................................................... 86
Figure 49 .................................................................................................................................... 87
Figure 50 .................................................................................................................................... 88
Figure 51 .................................................................................................................................... 89
Figure 52 .................................................................................................................................... 91
Figure 53 .................................................................................................................................... 93
Figure 54 .................................................................................................................................... 94
Figure 55 .................................................................................................................................... 99
Figure 56 .................................................................................................................................. 100
Figure 57 .................................................................................................................................. 101
Figure 58 .................................................................................................................................. 102
Figure 59 .................................................................................................................................. 103
Figure 60 .................................................................................................................................. 110
Figure 61 .................................................................................................................................. 111
Figure 62 .................................................................................................................................. 112
Figure 63 .................................................................................................................................. 113
Figure 64 .................................................................................................................................. 115
Figure 65 .................................................................................................................................. 115
Figure 66 .................................................................................................................................. 116
Figure 67 .................................................................................................................................. 121
Figure 68 .................................................................................................................................. 122
Figure 69 .................................................................................................................................. 123
Figure 70 .................................................................................................................................. 123
144
LIST OF TABLES
Table 1 – Example of Request with Handover of a Detached Signature ..................................... 8
Table 2 – List of Applicability Indicators which the System shall be Compliant with .................. 10
Table 3 – Valid MC-Symbols ..................................................................................................... 12
Table 4 – Request String Parameters ........................................................................................ 24
Table 5 – Description of JSON Format of Request for Creation and Sending of MC Emission
Order, object “Order” .......................................................................................................... 24
Table 6 – Format of Object “OrderProduct” ............................................................................... 25
Table 7 – Description of Extension for Object “OrderProduct” for Tobacco Industry ................. 26
Table 8 – Description of Extension for Object “Order” for Tobacco Industry .............................. 26
Table 9 – Description of Extension for Object “Order” for Goods Group Category “Items of
Clothing, Bed, Table, Bath and Kitchen Linen” ................................................................... 28
Table 10 – Description of “OrderProduct” Object Extension for Light Industry of Goods Group
Category “Items of Clothing, Bed, Table, Bath and Kitchen Linen” ..................................... 28
Table 11 – Description of Extension for Object “Order” for Light Industry, Goods Group Category
“Footwear” .......................................................................................................................... 30
Table 12 – Description of Extension for Object “OrderProduct” for GG “Footwear” ................... 31
Table 13 – Description of Extension for Object “Order” for Tire Manufacturers, Goods Group
Category “New Pneumatic Rubber Tires and Tire Casings” ............................................... 33
Table 14 – Description of Extension for Object “Order” for Perfumery Products Manufacturers,
Goods Group Category “Perfume and Eau de Toilette” ...................................................... 35
Table 15 – Description of “OrderProduct” Object Extension for the Perfumery Manufacturers of
Goods Group Category “Perfume and Eau De Toilette” ..................................................... 35
Table 16 – Description of Extension for Object “Order” for Photo Products Manufacturers,
Goods Group Category “Photo Cameras (Except Cine Cameras), Flash Lights and Flash
Bulbs” ................................................................................................................................. 37
Table 17 – Description of “OrderProduct” Object Extension for the Manufacturers of Photo
Products of Goods Group Category “Photo Cameras (Except for Cine Cameras), Flash
Lights and Flash Bulbs” ...................................................................................................... 37
Table 18 – Description of Extension for Object “Order” for Pharmaceutical Industry ................. 39
Table 19 – Description of Extension for Object “Order” for the Dairy Manufacturers ................. 40
Table 20 – Description of Extension for Object “Order” for the Dairy Manufacturers ................. 40
Table 21 – Description of Extension for Object “Order” for the Manufacturers of Bicycles and
Bicycle Frames ................................................................................................................... 42
Table 22 – Description of Extension for Object “Order” for the Wheelchair Manufacturers ....... 43
Table 23 – Format of Response to Request .............................................................................. 44
Table 24 – Request String Parameters ...................................................................................... 45
Table 25 – Object “DropoutReport” Structure ............................................................................ 45
Table 26 – Description of Extension for Object “DropoutReport” for Tobacco Industry ............. 47
145
Table 27 – Format of Response to Request to Send Notification on MC Disposal / Rejection .. 48
Table 28 – Request String Parameters ...................................................................................... 49
Table 29 – Object “AggregationReport” Structure ...................................................................... 49
Table 30 – Object “AggregationUnit” Structure .......................................................................... 50
Table 31 – Description of Extension for Object “AggregationReport” for Tobacco Industry ....... 51
Table 32 – Format of Response to Request to Send Information on Aggregation ..................... 54
Table 33 – Request String Parameters ...................................................................................... 55
Table 34 – Object “UtilisationReport” Structure ......................................................................... 56
Table 35 – Description of Extension for Object “UtilisationReport” for Tobacco Industry ........... 57
Table 36 – Description of Extension for Object “UtilisationReport” for Pharamceutical Industry 58
Table 37 – Description of Extension for Object “UtilisationReport” for the Dairy Manufacturers 62
Table 38 – Format of Response to Request to Send Report on MC Application ....................... 63
Table 39 – Request String Parameters ...................................................................................... 64
Table 40 – Format of Response to Request to Close Suborder by GTIN Specified .................. 65
Table 41 – Request String Parameters ...................................................................................... 66
Table 42 – Format of Response to Request for MC for the Goods Specified ............................ 68
Table 43 – Request String Parameters ...................................................................................... 69
Table 44 – Format of Response to Request, object “BufferInfo” ................................................ 70
Table 45 – Object “PoolInfo” Format .......................................................................................... 70
Table 46 – Request String Parameters ...................................................................................... 73
Table 47 – Format of Response to Request for Order Status .................................................... 74
Table 48 – Object “OrderSummaryInfo” Format ........................................................................ 74
Table 49 – Request String Parameters ...................................................................................... 76
Table 50 – Format of Response to Request for Information on Aggregation, object
“AggregationInfo” ................................................................................................................ 77
Table 51 – Object “OrderSummaryInfo” Format ........................................................................ 77
Table 52 – Description of the “AggregationInfo” Object Extension for Tobacco Industry
Manufacturers ..................................................................................................................... 79
Table 53 – Request String Parameters ...................................................................................... 80
Table 54 – Format of Response to Request for the Report Processing Status .......................... 81
Table 55 – Request String Parameters ...................................................................................... 82
Table 56 – Request Body Parameters ....................................................................................... 82
Table 57 – Format of Response to Request for OMS Availability .............................................. 83
Table 58 – Request String Parameters ...................................................................................... 84
Table 59 – Format of Response to Request for OMS Availability .............................................. 85
Table 60 – HTTP Header Parameters ....................................................................................... 86
Table 61 – Request String Parameters ...................................................................................... 86
Table 62 – Format of Response to Request for Security Marker ............................................... 87
Table 63 – Format of Response to Request for OMS and API Version ..................................... 88
Table 64 – Request String Parameters ...................................................................................... 89
146
Table 65 – Format of Response to Request for the List of MC Packet Identifiers for the Marking
and Goods Code Order Specified ....................................................................................... 90
Table 66 – Format of MC Package List, Object “Block” ............................................................. 90
Table 67 – Request String Parameters ...................................................................................... 92
Table 68 – Format of Response to Request for Re-obtainment of MC for the Goods Specified 94
Table 69 – Request String Parameters ...................................................................................... 95
Table 70 – Object “RollOutReport” Structure ............................................................................. 95
Table 71 – Description of the Object “Produced” for Goods Made in the Russian Federation ... 96
Table 72 – Description of the Object “Import” for Imported Goods ............................................ 96
Table 73 – Description of Object “Product” ................................................................................ 96
Table 74 – Description of Object “RollOutReport” Extension for Milk Producers ....................... 98
Table 75 - Format of Response to Request ............................................................................. 101
Table 76 – Request String Parameters .................................................................................... 102
Table 77 - Format of Response to Request ............................................................................. 103
Table 78 – Possible Values of Guide “Method of Goods Introduction into Circulation” ............ 107
Table 79 – Possible Values of Guide “Method of Individual Serial Number Generation” ......... 107
Table 80 – Possible Values of Guide “Marking type” ............................................................... 107
Table 81 – Possible Values of Guide “Manufacturing Method” ................................................ 108
Table 82 – Possible Values of Guide “Manufacturing Method” ................................................ 108
Table 83 – Description of MC Templates ................................................................................. 108
Table 84 – Possible Values of Guide “MC Array Status” ......................................................... 109
Table 85 – Possible Values of Guide “Aggregation Type” ....................................................... 110
Table 86 – Possible Values of Guide “MC Buffer Status” ........................................................ 110
Table 87 – Possible Values of Guide “Report Processing Status” ........................................... 111
Table 88 – Possible Values of Guide “Type of Utilization” ....................................................... 112
Table 89 – Possible Values of Guide “Order Status” ............................................................... 112
Table 90 – Possible Values of Guide “Dropout Reason”.......................................................... 113
Table 91 – Possible Values of Guide “Marking Code Type” .................................................... 114
Table 92 – Format of Response with Error .............................................................................. 116
Table 93 – Object “ProtobeansError” Format ........................................................................... 116
Table 94 – Data Send Error Codes .......................................................................................... 117
Table 95 – OMS API 2.0 Services Provision Matrix ................................................................. 118
Table 96 - Parameters of CMS Format Signature Generation Function. ................................. 124
Table 97 - Example of Command to Verify the Request Signature .......................................... 125
147
Revision Sheet
Numbers of sheets (pages)
Total sheets (pages) in document
Document No.
Reference No. of supporting document and
date
Sign. Date Rev
changed replaced new cancelled