AGREED BY APPROVED BY General Director CRPT, LLC 2020 2020 · 2 RU 15861920.620111-04 33 01 ANNOTATION This document «OMS-Cloud 3.1. Special Software. Programmer’s Guide» RU 15861920.620111-04

2020

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.

AGREED BY APPROVED BY General Director

CRPT, LLC _______________/ / _______________/ /

______________ 2020 ______________ 2020

OMS-CLOUD 3.1

Special software

Programmer’s guide

Key Functions

Version API 2.87

Revision 28

RU 15861920.620111-04 33 01

Approval list

2020

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

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.

APPROVED

RU 15861920.620111-04 33 01-AL

OMS-CLOUD 3.1

Special software

Programmer’s guide

Key Functions

Version API 2.87

Revision 28

RU 15861920.620111-04 33 01

Sheets 160

2

ANNOTATION

This document “OMS-Cloud 3.1. Special software. Programmer’s guide” RU

15861920.620111-04 33 01 is intended to introduce the functions of application programming

interface of special software (SSW) of automated system “OMS-Cloud 3.1” (OMS-Cloud 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 ............................................................................................................ 6 1.1. Program Purpose ............................................................................................................ 6 1.2. Program Functions ......................................................................................................... 6 2. PROGRAM APPLICATION ENVIRONMENT ......................................................................... 7 2.1. Applied Hardware ............................................................................................................ 7 2.1.1. Required characteristics of PC for the operation of software component from OMS-

Cloud 3.1 AS SSW executed at OMS-Cloud 3.1 AS SSW HWC ................................... 7 2.1.2. Required characteristics of PC to use “Web-Interface Module” software component

from OMS-Cloud 3.1 AS SSW......................................................................................... 7 2.2. Software required for program functioning .................................................................. 8 2.2.1. Software required for the functioning of software component from OMS-Cloud 3.1

AS SSW executed at OMS-Cloud 3.1 AS SSW HWC .................................................... 8 2.2.2. Software required for the functioning of “Web-Interface Module” software

component from OMS-Cloud 3.1 AS SSW .................................................................... 8 2.3. Software required for program operation ..................................................................... 8 2.3.1. General requirements to request signing ..................................................................... 8 2.3.2. Generating GS1 DataMatrix .......................................................................................... 10 2.3.3. Requirements JSON-format processing ..................................................................... 10 3. PROGRAM CHARACTERISTICS ......................................................................................... 11 3.1. Applicability Indicators ................................................................................................. 11 3.2. Operation Mode ............................................................................................................. 12 3.3. Means of Correct Operation Control and Self-Restorability of Program ................. 12 3.3.1. Means of Correct Operation Control ........................................................................... 12 3.3.2. Self-Restorability Means .............................................................................................. 12 4. PROGRAM CALL.................................................................................................................. 13 4.1. Introduction ................................................................................................................... 13 4.2. OMS-Method Call Sequences....................................................................................... 13 4.3. Description of MC-Emission Process ......................................................................... 15 4.3.1. Process “01.01.00.00 Create MC-Emission Order” .................................................... 15 4.3.2. Process “01.02.00.00 Obtain MC-Array Status from Order” ...................................... 18 4.3.3. Process “01.03.00.00 Obtain MC from Order” ............................................................ 20 4.3.4. Process “01.04.00.00 Send Report on MC-Utilization” .............................................. 22 4.4. MC Storage Buffer in OMS ........................................................................................... 24 4.5. OMS API Extensions ..................................................................................................... 25 4.5.1. Method “Create Marking Code Emission Order” ....................................................... 26 4.5.1.1. Request ............................................................................................................... 26 4.5.1.2. Response to Request ......................................................................................... 49 4.5.2. Method “Send Report on MC Disposal / Rejection” ................................................... 50 4.5.2.1. Request ............................................................................................................... 50 4.5.2.2. Response to Request ......................................................................................... 53 4.5.3. Method “Send Report on MC-Aggregation” ............................................................... 54 4.5.3.1. Request ............................................................................................................... 54 4.5.3.2. Response to Request ......................................................................................... 61 4.5.4. Method “Send Report on MC-Utilization (Application)” ............................................ 62 4.5.4.1. Request ............................................................................................................... 63 4.5.4.2 Response to Request ......................................................................................... 72 4.5.5 Method “Close the Suborder by the GTIN Specified” ................................................ 73 4.5.5.1 Request ............................................................................................................... 73 4.5.5.2 Response to Request ......................................................................................... 74 4.5.6 Method “Obtain MC from Order” ................................................................................. 75

4

4.5.6.1 Request ............................................................................................................... 75 4.5.6.2 Response to Request ......................................................................................... 77 4.5.7 Method “Obtain MC-Array Status from Order” ........................................................... 78 4.5.7.1 Request ............................................................................................................... 78 4.5.7.2 Response to Request ......................................................................................... 79 4.5.8 Method “Obtain the status of orders” ......................................................................... 82 4.5.8.1 Request ............................................................................................................... 82 4.5.8.2 Response to Request ......................................................................................... 83 4.5.9 Method “Obtain the Aggregation Information” .......................................................... 85 4.5.9.1 Request ............................................................................................................... 85 4.5.9.2 Response to Request ......................................................................................... 86 4.5.10 Method “Obtain the Report Processing Status” ........................................................ 89 4.5.10.1 Request ............................................................................................................... 89 4.5.10.2 Response to Request ......................................................................................... 90 4.5.11 Method “Send APCS Log Files” .................................................................................. 91 4.5.11.1 Request ............................................................................................................... 91 4.5.11.2 Response to Request ......................................................................................... 92 4.5.12 Method “Check OMS Availability” ............................................................................... 93 4.5.12.1 Request ............................................................................................................... 93 4.5.12.2 Response to Request ......................................................................................... 94 4.5.13 Method “Obtain Security Marker by Username and Password” ............................... 95 4.5.13.1 Request ............................................................................................................... 95 4.5.13.2 Response to Request ......................................................................................... 96 4.5.14 Method “Obtain OMS and API Version” ...................................................................... 97 4.5.14.1 Request ............................................................................................................... 97 4.5.14.2 Response to Request ......................................................................................... 97 4.5.15 Method “Obtain the List of Marking Code Package Identifiers” ............................... 98 4.5.15.1 Restrictions ......................................................................................................... 98 4.5.15.2 Request ............................................................................................................... 98 4.5.15.3 Response to Request ......................................................................................... 99 4.5.16 Method “Re-obtain Marking Codes from the Marking Code Order” ....................... 101 4.5.16.1 Restrictions ....................................................................................................... 101 4.5.16.2 Request ............................................................................................................. 101 4.5.16.3 Response to Request ....................................................................................... 103 4.5.17 Method “Send Report on the Utilization and Automatic Introduction into

Circulation”.................................................................................................................. 104 4.5.17.1 Restrictions ....................................................................................................... 104 4.5.17.2 Request ............................................................................................................. 104 4.5.17.3 Response to Request ....................................................................................... 110 4.5.18 Method “Request for the Document Number of Report on Introduction into

Circulation”.................................................................................................................. 111 4.5.18.1 Restrictions ....................................................................................................... 111 4.5.18.2 Request ............................................................................................................. 111 4.5.18.3 Response .......................................................................................................... 112 5 INPUT AND OUTPUT DATA ........................................................................................ 113 5.1. Nature, Arrangement and Initial Preparation of Input and Output Data ................. 113 5.1.1. Information Sources ................................................................................................... 113 5.1.2. Methods of Data Collection, Transmission, Control and Correction

Arrangement ................................................................................................................ 113 5.2. Format, Description and Encoding Method of the Input and Output Data when

Using API ..................................................................................................................... 115 5.3. Guides Accessible via API ......................................................................................... 116

5

5.3.1. Guides to Control the Marking Codes ....................................................................... 116 5.3.1.1. Guide “Method of Goods Introduction into Circulation”............................... 116 5.3.1.2. Guide “Method of Individual Serial Number Generation” ............................. 116 5.3.1.3. Guide “Manufacturing Method” ....................................................................... 117 5.3.1.4. Guide “MC Templates” ..................................................................................... 117 5.3.1.5. Guide “MC Array Status” ................................................................................. 118 5.3.1.6. Guide “Aggregation Type”............................................................................... 119 5.3.1.7. Guide “MC Buffer Status” ................................................................................ 119 5.3.1.8. Guide “Report Processing Status” ................................................................. 120 5.3.1.9. Guide “Type of Utilization” .............................................................................. 121 5.3.1.11. Guide “Dropout Reason” ................................................................................. 122 5.3.1.12. Guide “Marking Code Type” ............................................................................ 123 6. Messages ..................................................................................................................... 124 6.1. Messages to the Operator transmitted via GUI ........................................................ 124 6.1.1. Information windows .................................................................................................. 124 6.2. Error Format and Codes ............................................................................................. 125 6.2.1. Error format ................................................................................................................. 125 6.2.2. Description of Errors .................................................................................................. 125 7. Matrix of Provision of OMS API 2.0 Services by OMS Software Package

Components ................................................................................................................ 126 8. OMS API 2.0 Use Examples ........................................................................................ 127 8.1. Signing Requests with the Electronic Digital Signature .......................................... 127 8.1.1. Library “CryptoPro JCP” ............................................................................................ 127 8.1.2. Example with the Use of Library to Sign the Request ............................................. 131 APPENDIX .............................................................................................................................. 133 LIST OF TERMS ..................................................................................................................... 144 LIST OF ABBREVIATIONS .................................................................................................... 150 LIST OF FIGURES .................................................................................................................. 151 LIST OF TABLES .................................................................................................................... 154

6

1. PROGRAM PURPOSE

1.1. Program Purpose

The specialized software is intended to enable the performance of target functions of

OMS-Cloud 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-Cloud 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.

7

2. PROGRAM APPLICATION ENVIRONMENT

2.1. Applied Hardware

2.1.1. Required characteristics of PC for the operation of software component from

OMS-Cloud 3.1 AS SSW executed at OMS-Cloud 3.1 AS SSW HWC

In order to operate a software component from OMS-Cloud 3.1 AS SSW executed at

OMS-Cloud 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-Cloud 3.1 AS SSW

To operate the information services provided by OMS-Cloud 3.1 AS SSW, the following

hardware (HW) shall be used:

1) Non-shared HW:

8

− 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-Cloud 3.1 AS.

2.2. Software required for program functioning

2.2.1. Software required for the functioning of software component from OMS-

Cloud 3.1 AS SSW executed at OMS-Cloud 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-Cloud 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-Cloud 3.1 AS SSW

To operate the information services provided by “Web-Interface Module” software

component from OMS-Cloud 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).

9

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 BiqFAwICAzB/MSMwIQYJKoZIhvcNAQkBFhRzdXBwb3J0QGNyeXB0b3Byby5ydTELMAkGA1

10

Description

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.

11

3. PROGRAM CHARACTERISTICS

3.1. Applicability Indicators

OMS-Cloud 3.1 AS SSW ensures implementation of OMS-Cloud 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


Quantity of marking codes per marking code disposal / rejection report.


12

3.2. Operation Mode

OMS-Cloud 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-Cloud 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-Cloud 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.

13

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).

14

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.

OMS-Method Call Sequence

Figure 1

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)


7. Send report of dropout IC to OMS (omsId, dropoutReport)


15

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.

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;

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?


Yes


request


Check for errors

Create IC array

No


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»


Save business order data

16

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.




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;


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;


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;

17

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.

18

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.

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;


− Moving to Step 7 of main scenario.

5) OMS obtains information on MC-array;

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


YesNo

Check for errors

Any mistakes?


Yes

Get information about the IC array

No



01.03.00.00 «Get ICs from the order»

Yes

Is the CM buffer s tatus «PENDING»?


Is the IC buffer status «ACTIVE»?

No

No

Yes

The response message includes information about the buffer and IC arrays.

19


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;


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.


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.

20

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.

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;



4) OMS generates an array of emitted MC;


6) APCS receives response message;

7) APCS performs check for errors:

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


YesNo

Check for errors

Any mistakes?


Yes

Generate an array of emitted IC

No


Yes

Is there more IC in the order?


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.

21

− In case of any errors within the request, APCS registers them in a log;


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”;


11) In case the remaining MC do not have to be downloaded, the process is terminated.

22

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.

Process “Send Report on MC-Utilization”

Figure 5

Description:

1) APCS generates a request containing MC-utilization report and sends it to OMS;

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.




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;

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


request

Yes

Report


Check request

Any mistakes?

No

Any mistakes?

No

IC utilisation report

Create request

IC utilisation report

Check request


Yes

Any mistakes?

Check for errors


Yes No

Check for errors

Any mistakes?


Yes


request


Check for errors

No



Assign a report id


Process report



If there are no errors, the response message

contains the report identifier.

23

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;


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;



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;


15) In case of no errors, APCS saves report identifier, the process is terminated.

24

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.

MC Order Distribution between ERs

Figure 6

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

25

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 extensionthat determines access to extensions of goods groups has

the following default values:

1) light – URL-parameter extension for light industry, previously used for two product cat-

egories: “Items of clothing, bed, table, bath and kitchen linens” and “Footwear”. A transi-

tion from this general extension to two separate ones, “lp” and “shoes”, has begun. In the

future, “light” will no longer be supported.

2) lp – URL-parameter extension for light industry, “Items of clothing, bed, table, bath and

kitchen linens” product category;

3) shoes – URL-parameter extension for light industry, “Footwear” product category;

4) pharma – URL-parameter extension for pharmaceutical industry.

5) tobacco – URL-parameter extension for tobacco industry.

6) tires – URL-parameter extension for tire manufacturers.

7) photo – URL-parameter extension for photo products manufacturers.

8) perfume – URL-parameter extension for perfumery products manufacturers.

9) milk – URL-parameter extension for dairy manufacturers;

10) bicycle – URL-parameter extension for bicycle and bicycle-frame manufacturers;

11) wheelchairs – URL-parameter extension for wheelchair manufacturers.

12) otp - URL-parameter extension for manufacturers of alternative tobacco products.

13) Water – URL-parameter extension for manufacturers of packed water products.

26

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

27


serviceProviderId Service provider identifier String(36)

UUID No

Note: Field “serviceProviderId” is used for the following product groups included in the

distribution process: “Footwear”, “Dairy products”, “Medicines for human use”.

For the description of format of object “OrderProduct", see Table 6.

Table 6 – Format of Object “OrderProduct”


Gtin Product GTIN String (14) [0-9]{14}

Yes

quantity MC quantity Integer ($int32) Yes

serialNumberType Serial number generation method.

String (5.3.1.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)

(5.3.1.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.

28

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


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


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

29

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

30

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”


contactPerson Contact person String Yes

releaseMethodType Method of goods release into circulation

5.3.1.1 Yes

createMethodType IM creation method 5.3.1.3 Yes

productionOrderId Production order identifier String No

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”


cisType Marking code type 5.3.1.12 Yes

exporterTaxpayerId The exporter’s INN/UNB or a similar ID number

String No*

Note*: The field “exporterTaxpayerId” becomes mandatory when the value

“CROSSBORDER” (imported into the Russian Federation from EEU countries) is selected in

the field “releaseMethod” (method of goods release into circulation).

31

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

32

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”




5.3.1.1 Yes



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

33


remainsImport

Attribute of foreign-made goods imported into the Russian Federation after 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 – 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

boolean No


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”


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


34

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

35

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



5.3.1.1 Yes



Table 14 – Description of “OrderProduct” Object Extension for Tire Manufactures in the goods group category of New Pneumatic Rubber Tires and Tire Casings.



String No*




36

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

37

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 15 – Description

of Extension for Object “Order” for Perfumery Products Manufacturers, Goods Group Category

“Perfume and Eau de Toilette”

Table 15 – Description of Extension for Object “Order” for Perfumery Products Manufacturers, Goods Group Category “Perfume and Eau de Toilette”




5.3.1.1* Yes



Note*: the values “REMAINS” in catalog “Method of Goods Release into Circulation” are

invalid for goods category “Perfume and Eau de Toilette”

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 ).

Table 16 – Description of “OrderProduct” Object Extension for the Perfumery Manufacturers of Goods Group Category “Perfume and Eau De Toilette”




String No*




38

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

39

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 .

Table 17 – Description of Extension for Object “Order” for Photo Products Manufacturers, Goods Group Category “Photo Cameras (Except Cine Cameras), FlashLights and Flash Bulbs”




5.3.1.1 Yes



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 18).

Table 18 – 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”




String No*




40

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

41

4.5.1.1.7 Extensions for Pharmaceutical Industry

For the description of extension for object “Order” for pharmaceutical industry, see Table .

Table 19 – Description of Extension for Object “Order” for Pharmaceutical Industry


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

42

4.5.1.1.8 Extensions for Dairy Manufacturers

For the description of extension for object “OrderProduct” for dairy manufacturers, see

Table .

Table 20 – Description of Extension for Object “Order” for the Dairy Manufacturers


expDate Product expiration date (shelf life exceeding 72 hours)

String (6) (YYMMDD)


expDate72 Product expiration date (shelf life under 72 hours)

String (10) (YYMMDDHHMM)


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 21.

Table 21 – Description of Extension for Object “Order” for the Dairy Manufacturers




5.3.1.1 Yes



Note*: the values “REMAINS” and “REMARK” in catalog “Method of goods release into

circulation” are invalid for goods category “Dairy products”.

43

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

44

4.5.1.1.9 Extensions for Bicycle and Bicycle 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 22 – Description of Extension for Object “Order” for the Manufacturers of Bicycles and Bicycle Frames




5.3.1.1 Yes



Note*: the values “REMAINS” and “REMARK” 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

45

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 23.

Table 23 – Description of Extension for Object “Order” for the Wheelchair Manufacturers




5.3.1.1 Yes



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

46

4.5.1.1.11 Extensions for Manufacturers of Alternative Tobacco Products

For the description of extension for object “OrderProduct” for alternative tobacco

products, see Table 24 – Description of Extension for Object “OrderProduct” for alternative

tobacco products.

Table 24 – Description of Extension for Object “OrderProduct” for alternative tobacco products


mrp Maximum retail price String (4) No


cisType

Marking code type. Valid values: - UNIT - Product unit; - GROUP- Group retail package

5.3.1.12 Yes

Note*:

1) The “cisType” value is set for the following contidions:

- If “cisType”= UNIT , then permissible values of the “templateId” attribute are 14 and 15;

- If “cisType”= GROUP, then permissible value of the “templateId” attribute is 14.

2) For ATP, the default value of the “mrp” attribute is = АААА, which contains a re-coded

maximum retail price of the retail package down to kopecks, and the stated price is zero rubles

and zero kopecks. Filled in automatically when mentioning Template 15.

For the description of extension for object “Order” for alternative tobacco products, see

Table .

Table 25 – Structure of extension for object “Order” for alternative tobacco products



releaseMethodType Method of goods introduction into circulation

5.3.1.1 Yes

createMethodType Manufacturing method 5.3.1.3 Yes

productionOrderId Production order identifier String

No

factoryId Factory identifier. (Global location number)

String Yes

factoryName Factory name String No

factoryAddress Factory address String No

factoryCountry Country of manufacture String Yes


47


productCode Product code (SKU) String Yes

productDescription Product description String Yes

poNumber Production order number String No

expectedStartDate Expected production start date for the order

String (yyyy-mm-dd)

No

Notes*:

1) values “REMAINS”, “CROSSBORDER”, “REMARK” from the “Method of Goods

Introduction into Circulation” Guide are not applicable for the “Alternative tobacco products”

product category;

2)value “CEM” from the “Manufacturing Method” Guide is not applicable for the “Alternative

tobacco products” product category.

For an example of REST-request (for alternative tobacco products), see Figure 17.

POST /api/v2/otp/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":"04600818007695", "quantity" : 2, "serialNumberType" : "SELF_MADE", "serialNumbers" : [ "Z9bmNYR", "8i8PjF3"], "templateId" : 14, "cisType": "UNIT", "mrp": 41000}], "contactPerson":"Иванов И.И.", "releaseMethodType": "PRODUCTION", "createMethodType": "SELF_MADE", "productionOrderId": "08528091-808a-41ba-a55d-d6230c64b332", "factoryId":"Identifier", "factoryName":"Alt Tobacco Factory", "factoryAddress":"Address", "factoryCountry":"Country", "productionLineId":"1", "productCode":"6789", "productDescription":"Simple", "poNumber":"123", "expectedStartDate":"2020-09-01" }

Example of REST-request (for alternative tobacco products)

Figure 17

48

4.5.1.1.12 Extensions for manufacturers of Packed Water

For the description of extension for object “Order” for packed water, see Table 26.

Table 26 – The description of the extension for the “Order” object for the manufacturers of packed water



releaseMethodType Goods release method type

Guide №1 Yes

createMethodType MC manufacturing method Guide №4 Yes

productionOrderId Manufacturing order identifier

String No

Note*: values “REMAINS”, “CROSSBORDER”, “REMARK” from the “Method of Goods

Introduction into Circulation” Guide are not applicable for the “Packed water” product category

For the example of REST-request (for “Packed water” products) see

For the example of REST-request (for “Packed water” products) see Figure 18.

POST /api/v2/water/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":"04606791012510", "quantity": 3, "serialNumberType": "SELF_MADE", "serialNumbers": [ "XT6c84e39gXjW", "2kY39OmdmHTwx", "X4ebssJPznnLg" ], "templateId": 16 } ], "contactPerson":"Иванов П.А.", "releaseMethodType": "PRODUCTION", "createMethodType": "SELF_MADE", "productionOrderId": "08528091-808a-41ba-a55d-d6230c64b333" }

Example of REST-request (for “Packed water”)

Figure 18

Способ_выпуска#_Справочник_

Способ_изготовления#_Справочник_

49

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 27 – Format of Response to Request


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 19.

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 19

50

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

containDropout Report base object without any extensions for the goods group.

- “Packed water”. 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.



port]/api/v2/{extension}/dropout?omsId={omsId}

Method:POST



userName:{userName}




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 29.

Table 29 – Object “DropoutReport” Structure


dropoutReason Disposal reason. String

(5.3.1.11) Yes

sntins An array of disposed MC full marking codes (including verification code)

JSON Array of String

Yes

51

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 20 (for “Dairy Products”) and Figure 21 (for “Packed water”).

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 20

POST /api/v2/water/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":["010460679101251021aBcD/GmaGIs3x\u001D93aABb", "010460679101251021AbcdHywb*B!n+\u001D93tTBb"] }

Example of REST request for Packed water products Figure 21


For the description of extension for object “DropoutReport” for tobacco industry, see Table

30.

Table 30 – Description of Extension for Object “DropoutReport” for Tobacco Industry


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

52



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 22.

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 22

53


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 31. For error

codes, see subsection 6.2.

Table 31 – Format of Response to Request to Send Notification on MC Disposal / Rejection



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" }


Figure 23

54

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 following goods groups:

- “Tobacco Products”

- “Dairy Products”

- “Footwear”, “Perfume and eau de toilette”, “Photo cameras (except cine cameras), flash

lights and flash bulbs”, “Items of clothing, bed, table, bath and kitchen linens”. This method is

available for the above goods group and only for EEU Operators. The structure of request sent

by aggregation by the EEU Operator shall contain the “AggregationReport” basic object without

extensions for a goods group. For the goods group “Items of clothing, bed, table, bath and kitchen

linens”, only new lp extension must be used in the URL request;

- “Alternative tobacco products”.

- “Packed water”. The request structure send under the packed water shall include the basic

object “AggregationReport” without extension for a goods group.

4.5.3.1. Request

Structure of JSON-request used to send report on MC aggregation to OMS.



port]/api/v2/{extension}/aggregation?omsId={omsId}

Method:POST



userName:{userName}





55

For the description of the “AggregationReport” object structure of request to send

information on aggregation, see Table 33 – Object “AggregationReport” Structure).

Table 33 – Object “AggregationReport” Structure


aggregationUnits Array of aggregation units Array of

AggregationUnit (Table 34)

Yes


For the description of the “AggregationUnit" object structure, see Table 34.

Table 34 – Object “AggregationUnit” Structure


aggregatedItemsCount Actual quantity (in pcs) per aggregation unit

Integer ($int32) Yes

aggregationType Aggregation type String (5.3.1.6) 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 groups “Dairy products” and “Packed water”, field “unitSerialNumber”

(aggregate code) shall contain shipping container code (SSCC; length of 18 digital symbols).

For an example of a REST request for the “AggregationReport” basic object without

extensions, see Figure 24. (for all goods group when sending by the EEU Operator) and Figure

25 (for “Packed water” goods group).

56

POST /api/v2/light/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" : 2, "aggregationType" : "AGGREGATION", "aggregationUnitCapacity" : 2, "sntins" : [ "010693452653800321ABC78RZ9bmNYR", "010693452653800321ABC78R8i8PjF3"], "unitSerialNumber" : "010000000111222333" } ] }

Example of REST Request for “Footwear” (when sending by the EEU Operator)

Figure 24

POST /api/v2/water/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": "1233033692", "aggregationUnits": [ { "aggregatedItemsCount" : 2, "aggregationType" : "AGGREGATION", "aggregationUnitCapacity" : 2, "sntins" : [ "010460679101251021XT6c84e39gXjW", "010460679101251021X4ebssJPznnLg"], "unitSerialNumber" : "099900000111222333" } ] }

Example of REST Request for “Packed water”

Figure 25


For the description of extension for object “AggregationReport” for tobacco industry, see

Table 35.

Table 35 – Description of Extension for Object “AggregationReport” for Tobacco Industry




57

For an example of REST-request for tobacco industry, see Figure 26.

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 26

58

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 27.

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 27

For an example of REST-request for dairy manufacturers (partially filled aggregate), see

Figure 28.

59

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 28

60

4.5.3.1.3 Extensions for Alternative Tobacco Products

For the description of extension for object “AggregationReport” for alternative tobacco

products, see Table .

Table 36 – Description of Extension for Object “AggregationReport” for alternative tobacco products




For an example of REST-request for alternative tobacco products, see Figure 29.

POST /api/v2/otp/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": "1", "productionOrderId": "1", "aggregationUnits": [ { "aggregatedItemsCount": 2, "aggregationType": "AGGREGATION", "aggregationUnitCapacity": 2, "sntins": [ "010000004620984921?nWNbqv", "010000004620984921?gBDbQs"], "unitSerialNumber": "010000004620984921DtRwbEs" } ] }

Example of REST-request for alternative tobacco products

Figure 29

61



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 37. For error codes, see subsection 6.2.

Table 37 – Format of Response to Request to Send Information on Aggregation



reportId Unique OMS identifier of report String (UUID) Yes


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" }


Figure 30

62

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 section 4.5.13),

username shall be sent within the HTTP-header titled “userName”.

Note:

1) for participants who are not EEU-Operators, this method is currently available for

“Tobacco Products”, “Dairy products”, “Medicines for human use”, and “Alternative tobacco

products”, “Packed water” product groups. The report is generated automatically for the following

product groups:

- “Bicycles and bicycle frames”

- “Wheelchairs”

- “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”

Later on, when the information system is ready (expected in Q3 2020), the function of

sending application reports automatically will be disabled. Reports on MC utilization (application)

will have to be generated and sent manually using the described method.

2) for an EEU Operator, the method is not available

63

4.5.4.1. Request

Structure of JSON-request used to send report on MC utilization to OMS.



port]/api/v2/{extension}/utilisation?omsId={omsId}

Method:POST



userName:{userName}





For the description of the structure of object “UtilisationReport” used to send report on

MC utilization to OMS, see Table 39.

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.

Table 39 – Object “UtilisationReport” Structure


Sntins Array of strings (full marking code, including verification code)

JSON Array of String Yes

usageType Type of use String (5.3.1.9) Yes

64


For the description of extension for object “UtilisationReport” for tobacco industry, see

Table 40.

Table 40 – Description of Extension for Object “UtilisationReport” for Tobacco Industry



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 31

65

4.5.4.1.2 Extensions for Pharmaceutical Industry

For the description of extension for object “UtilisationReport” for pharmaceutical industry,

see Table 41.

Table 41 – Description of Extension for Object “UtilisationReport” for Pharamceutical Industry


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.

66

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 .

67

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 32

For examples of REST-request (for pharmaceutical industry with production outside the

territory of the Russian Federation), see Figure .

68

/*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 33

69

4.5.4.1.3 Extensions for Dairy Manufacturers

For the description of extension for object “UtilisationReport” for dairy manufacturers, see

Table 42.

Table 42 – Description of Extension for Object “UtilisationReport” for the Dairy Manufacturers


accompanyingDocument Production veterinary accompanying document

String Yes


String (6) (YYMMDD)

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 34.

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 34

70

4.5.4.1.4 Extensions for Manufacturers of Alternative Tobacco Products

For the description of extension for object “UtilisationReport” for manufacturers of

alternative tobacco products, see Table .

Table 43 – Description of extension for object “UtilisationReport” for manufacturers of alternative tobacco products


productionLineId Production line identifier

String Yes

productionOrderId Production order identifier

String No

brandcode Brand name

String(256) No

sourceReportId Identifier of report on APCS application

String(36) No

For example of REST-request (for manufacturers of alternative tobacco products), see

Figure 35.

POST /api/v2/otp/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" : "VERIFIED", "productionLineId" : "1", "productionOrderId":"1", "brandcode" : "Brandcode123", "sourceReportId":"8ed74f90-0119-48f2-b289-379707934e2f" }

Example of REST-request (for manufacturers of alternative tobacco products)

Figure 35

71

4.5.4.1.5 Extensions for Manufacturers of “Packed water” products

For the description of extension for object “UtilisationReport” for manufacturers of alternative

tobacco products, see Table 44.

Table 44 – Description of extension for object “UtilisationReport” for manufacturers of “Packed water” products


usedInProduction

Indication of MC usage at the production: 0 – value by default;

1 – MC were used at the production

Integer ($int32)

No

For example of REST-request (for manufacturers of packed products products), see Figure

36.

POST /api/v2/water/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" : "VERIFIED", "usedInProduction":1 }

Example of REST-request (for manufacturers of “Packed water” products)

Figure 36

72

4.5.4.2 Response to Request


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 45. For error codes, see subsection 6.2.

Table 45 – Format of Response to Request to Send Report on MC Application



Yes

reportId Unique identifier of MC application report (OMS)

String (UUID)

Yes

For an example of JSON-response, see Figure 37.

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" }


Figure 37

73

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


URL:http://<server-name>[:server-port]/api/v2/{extension}/buffer/close

?orderId={orderId}&gtin={gtin}&omsId={omsId}&

lastBlockId={lastBlockId}

Method:POST






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&gtin=01334567894339&lastBlockId=0&omsId=CDF12109-10D3-11E6-8B6F-0050569977A1

Example of REST Response

Figure 38

74



OMS identifier. For the structure of response to request to close the suborder by GTIN specified,

see Table 47. For error codes, see subsection 6.2.

Table 47 – Format of Response to Request to Close Suborder by GTIN Specified


omsId Unique OMS identifier. (UUID) String


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" }


Figure 39

75

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


URL:http://<server-name>[:server-port]/api/v2/{extension}/codes?

omsId={omsId}&orderId={orderId}&gtin={gtin}&quantity={quantity}&

lastBlockId={lastBlockId}

Method:GET






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);

76

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).


GET /api/v2/tobacco/codes?orderId=b024ae09-ef7c-449e-b461-05d8eb116c79&gtin=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


Figure 40

77


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 49. For

error codes, see subsection 6.2.

Table 49 – Format of Response to Request for MC for the Goods Specified



Yes

codes MC-array JSON Array

of Strings Yes

blockId MC packet identifier String (UUID)

Yes


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" }


Figure 41

78

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.


URL:http://<server-name>[:server-

port]/api/v2/{extension}/buffer/status?

omsId={omsId}&orderId={orderId}&gtin={gtin}

Method:GET






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


GET /api/v2/tobacco/buffer/status?orderId=b024ae09-ef7c-449e-b461-05d8eb116c79&gtin=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


Figure 42

79


For the JSON-format of response to request to obtain MC-array status, see Table 51. For

error codes, see subsection 6.2.

Table 51 – Format of Response to Request, object “BufferInfo”


availableCodes The total quantity of available MC for goods in buffer and pools of registrar


bufferStatus Buffer status String (Guide “MC Buffer

Status”) Yes

gtin GTIN on which the request was made

String (14) [0-9]{14}

Yes

leftInBuffer Quantity of MC unused. (local buffer)


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 52) No

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 52 – Object “PoolInfo” Format


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


registrarErrorCount Quantity of ER-errors Integer ($int32) Yes

registrarId ER-identifier (number) String Yes

80


rejectionReason Rejection reason String No

status MC pool status String (Guide

“MC Array Status”)

Yes

For an example of JSON-response (with existing buffer), see Figure 43.

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 43

81

Example of the JSON response (for the declined order) is shown in Figure 44.

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 44

For an example of JSON response for the case where the pool has not been created yet

and the buffer is inactive, see Figure 45.

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" : "PENDING", "totalPassed": -1, "omsId": "0206854c-f182-4356-8207-0c2517c3853b" }

Example of JSON response (the pool has not been created yet and the buffer is inactive)

Figure 45

82

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:

1) 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.

2) 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



port]/api/v2/{extension}/orders?omsId={omsId}

Method:GET


For the request string parameter, see Table 53.




REST Request Example is shown in Figure 46.

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 46

83


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 54. For error codes see subsection 6.2.

Table 54 – Format of Response to Request for Order Status



orderInfos Array of orders with their statuses JSON Array of

OrderSummaryInfo (Table 55)

Yes

Table 55 – Object “OrderSummaryInfo” Format


orderId Identifier for MC emission order String (UUID) Yes

orderStatus Order status String (Guide

“Order Status”)

Yes

buffers Buffer status information array JSON Array of BufferInfo (Table 51)

Yes

createdTimestamp Order creation time Integer ($int64)

Yes

declineReason Reason for order decline String No

84

JSON Response example is shown in Figure 47.

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 47

85

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



port]/api/v2/{extension}/aggregation/info?omsId={omsId}&

unitSerialNumber={unitSerialNumber}

Method:GET

Accept: application/json






unitSerialNumber

Aggregate identifier. The code may contain special symbols, therefore, the value shall be encoded to the valid format ASCII (URL Encoding)

String Yes


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


Figure 48

86


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 57. For error codes see subsection 6.2.

Table 57 – Format of Response to Request for Information on Aggregation, object “AggregationInfo”


aggregationUnits Array of aggregation units Array of

AggregationUnit (Table 34)

Yes



productsInfo Product information Array of

ProductInfo (Table 58)

No

For the description of object “ProductInfo" structure, see Table 58.

Table 58 – Object “OrderSummaryInfo” Format


gtin Product GTIN String (14) [0-

9]{14} Yes

name Product name String Yes

87


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" } ] }


Figure 49

88

4.5.9.2.1 Extension of Tobacco Industry

Description of the “AggregationInfo” object extension for the tobacco industry manufacturers

is shown in Table 59.

Table 59 – Description of the “AggregationInfo” Object Extension for Tobacco Industry Manufacturers





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" } ] }


Figure 50

89

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


4.5.10.1 Request



port]/api/v2/{extension}/report/info?omsId={omsId}&

reportId={reportId}

Method:GET






reportId Unique OMS report identifier String (UUID) Yes


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


Figure 51

90



OMS report identifier and the report processing status. The format of response to request for the

report processing status is shown in Table 61. For error codes see subsection 6.2.

Table 61 – Format of Response to Request for the Report Processing Status



reportId Unique OMS report identifier String (UUID) Yes

reportStatus Report processing status String (5.3.1.8) Yes


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" }


Figure 52

91

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


4.5.11.1 Request


URL: http://<server-name>[:server-port]/api/v2/{extension}/

logs?omsId={omsId}

Method:POST

Content-: multipart/form-data


For the request string parameter, see Table 62).




For the request parameter, see Table 63.

Table 63 – Request Body Parameters


log File in zip format - Yes

Request Example is shown in Figure 53.

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 53

92



OMS identifier. The format of response to request for OMS availability is shown in Table 64. For

error codes see subsection 6.2.

Table 64 – Format of Response to Request for OMS Availability



Yes


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" }


Figure 54

93

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



port]/api/v2/{extension}/ping?omsId={omsId}

Method:GET





omsId Unique OMS identifier String(UUID) Yes


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


Figure 55

94



OMS identifier. The format of response to request for OMS availability is shown in Table 66. For

error codes see subsection 6.2.

Table 66 – Format of Response to Request for OMS Availability



Yes


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" }


Figure 56

95

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 cloud-based OMS.

4.5.13.1 Request



port]/api/v2/{extension}/token?omsId={omsId}&

username={username}&password={password}

Method:GET

tokenName: tokenName


The HTTP header parameters are shown in Table 67.

Table 67 – HTTP Header Parameters


tokenName User name (client device name) String Yes

For the request string parameters, see Table 68.




username User's first name String Yes

password User password String Yes


GET /api/v2/tobacco/token?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1 &username=admin&password=password HTTP/1.1 Accept: application/json Host: localhost:8080


Figure 57

96


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 69. For error codes see subsection 6.2.

Table 69 – Format of Response to Request for Security Marker



Yes

token Security marker String Yes


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", }


Figure 58

97

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


URL: http://<server-name>[:server-port]/api/v2/{extension}/ version

Method:GET




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 70. For error codes see subsection 6.2.

Table 70 – Format of Response to Request for OMS and API Version


apiVersion OMS API version String Yes

omsVersion OMS version String Yes


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" }


Figure 59

98

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


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:


port]/api/v2/{extension}/codes/blocks?omsId={omsId}&

orderId={orderId}&gtin={gtin}

Method:GET





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


GET /api/v2/{extension}/codes/blocks?omsId=CDF12109-10D3-11E6-8B6F-0050569977A1&orderId=b024ae09-ef7c-449e-b461-05d8eb116c79&gtin=01334567894339 HTTP/1.1 Accept: application/json clientToken: 1cecc8fb-fb47-4c8a-af3d-d34c1ead8c4f Host: localhost:8080

Request Example

Figure 60

99


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 72. For error codes,

see subsection 6.2.

Table 72 – Format of Response to Request for the List of MC Packet Identifiers for the Marking and Goods Code Order Specified


orderId


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


blocks List of marking code packages

Array of objects Block (JSON Array

of Block)

Yes

Table 73 – Format of MC Package List, Object “Block”


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

100

Response example is shown in Figure 61.

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 61

101

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.15).


The marking codes may be repeatedly requested if

1) they were previously requested via API;

2) 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}&gtin={gtin}&blockId={blockId}

Method:GET





orderId


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

102


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


GET /api/v2/{extension}/codes/retry?orderId=b024ae09-ef7c-449e-b461-05d8eb116c79&gtin=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 62

103


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 75. For error codes, see subsection 6.2.

Table 75 – Format of Response to Request for Re-obtainment of MC for the Goods Specified



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


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 63

104

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.13), username shall be sent within

the HTTP-header named “userName”.


Currently this method is available for the milk producers.

4.5.17.2 Request

REST request parameters are provided below:


rollout?omsId={omsId}

Method:POST



userName:{userName}




For the request body parameters, see Table 77.

Table 77 – Object “RollOutReport” Structure


usageType Type of use String (enum)

(5.3.1.9) 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-

mm-dd) Yes

105


The attribute value shall be within the following range: current date minus 5 calendar years <= productionDate <= current date.

products Information on products (see Table 80) Array of Product

Yes

produced

Information on manufacturer, Russian Federation. To be filled if =LP_INTRODUCE_GOODS_AUTO (see Table 78)

Object Produced

No (Conditionally mandatory)

import

Information on import manufacturer. To be filled if =LP_GOODS_IMPORT_AUTO (see Table 79)

Object Import No

(Conditionally mandatory)

Table 78 – Description of the Object “Produced” for Goods Made in the Russian Federation


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 79 – Description of the Object “Import” for Imported Goods


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 80 – Description of Object “Product”


code Full MC (including verification code). String Yes

106


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

107

4.5.17.2.1 Extensions for milk producers

Description of the “RollOutReport” object extension for the milk producers is shown in

Table 81.

Table 81 – Description of Object “RollOutReport” Extension for Milk Producers


accompanyingDocument Production veterinary accompanying document

String Yes


String (6) (YYMMDD)





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.

108

Request example for goods made in the Russian Federation is shown in Figure 64.

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 64

109

Request example for the imported goods is shown in Figure 65.

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 65

110


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 82. For error codes, see subsection 6.2.

Table 82 - Format of Response to Request



reportId Unique identifier of report on utilization/introduction into circulation

String (UUID) Yes


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 66

111

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”.


Currently this method is available for the milk producers.

4.5.18.2 Request

REST request parameters are provided below:


rollout?omsId={omsId}?reportId={reportId}

Method:GET



userName:{userName}



omsId Unique OMS identifier String Yes


String Yes


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 67

112

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 84. For error codes, see subsection 6.2.

Table 84 - Format of Response to Request



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


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


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 68

113

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:

1) Related information systems involved in both infocommunication and functional

exchange.

2) Data entered by system users.

Operations on:

1) analog-to-digital and digital-to-analog signal conversion;

2) optical character recognition;

3) other actions to bring information to a form suitable for computer processing

are not provided for as part of the OMS-Cloud 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:

1) Receiving of structured XML-documents generated on the basis of specified XSD-

schemes via collaborative services.

2) 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.

114

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.

115

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.

116

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 85.

Table 85 – 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», “Items of clothing, bed, table, bath and kitchen linen”, “New pneumatic rubber tires and tire casings”, “Perfume and eau de toilette”, “Photo cameras (except cine cameras), flash lights and flash bulbs”, “Dairy products”)

String

REMARK

Remarking (is only available for GG ”Items of clothing, bed, table, bath and kitchen linen”, “Footwear”, “New pneumatic rubber tires and tire casings”, “Perfume and eau de toilette”, “Photo cameras (except cine cameras), flash lights and flash bulbs”, “Bicycles and bicycle frames”, “Wheelchairs”)

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 86.

Table 86 – Possible Values of Guide “Method of Individual Serial Number Generation”

Constant Value Type

SELF_MADE No assistance String

OPERATOR By TT IS operator String

117

5.3.1.3. Guide “Manufacturing Method”

List of possible values of guide “Manufacturing Method” is shown in Table 87.

Table 87 – Possible Values of Guide “Manufacturing Method”

Constant Value Type

SELF_MADE No assistance String

CEM LMC String

CM Contract manufacturing String

CL Logistic warehouse String

5.3.1.4. Guide “MC Templates”

List of possible values of guide “MC templates” is shown in Table 88.

Table 88 – Possible Values of Guide “Manufacturing Method”

Constant Value Type

1 01 + GTIN + 21 + serial (13 chars) String



4 GTIN + serial (7 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





11 01 + GTIN + 21 + SERIAL (13 chars) String



15 GTIN + SERIAL (7 chars)+MRP (АААА) String


118

Table 89 – 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)

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

Template 14 Alternative Tobacco Products (GS1)

Template 15 Alternative Tobacco Products

Template 16 Packed water

Note: Pack-template lacks AI in template and MC.

5.3.1.5. Guide “MC Array Status”

List of possible values of guide “MC Array Status” is shown in Table 90.

Table 90 – 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

119

State diagram is shown in Figure 69.

MC Array Status

Figure 69

5.3.1.6. Guide “Aggregation Type”

List of possible values of guide “Aggregation Type” is shown in Table 91.

Table 91 – 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.7. Guide “MC Buffer Status”

List of possible values of guide “MC buffer status” is shown in Table 92.

Table 92 – Possible Values of Guide “MC Buffer Status”

Constant Value Type

PENDING MC buffer pending String

ACTIVE Buffer is created String

IN_PROCESS

В обработке

READY

Готов

REQUESTED

Запрошен

REJECTED

Отклонен

REQUEST_ERROR

Ошибка

CLOSED

Закрыт

DELETED

Удален

120

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


MC Buffer Status

Figure 70

5.3.1.8. Guide “Report Processing Status”

List of possible values of guide “Report processing status” is shown in Table 93.

Table 93 – 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

CHECK The report’s metadata get checked (this applies to the Pharmaceuticals for medical use product group)

String

ACTIVE

Активный

CLOSED

Закрыт

PENDING

В ожидании

REJECTED

Недоступен

EXHAUSTED

Исчерпан

121


READY_TO_SEND

Готов к отправке

SENT

Отправлен

PENDING

В ожидании

REJECTED

Отклонен

CHECK

На проверке

Report processing status

Figure 71

5.3.1.9. Guide “Type of Utilization”

List of possible values of guide “Type of utilization” is shown in Table 94.

Table 94 – Possible Values of Guide “Type of Utilization”

Constant Value Type

USED_FOR_PRODUCTION MC sent to production line (this value is not used)*

String

SENT_TO_PRINTER Production line sent MC to printer (this value is not used)*

String

PRINTED MC printed String

PRINTER_LOST MC lost by printer—confirmed (this value is not used)*

String

VERIFIED MC application—confirmed String

Note*: the values of the guides ”USED_FOR_PRODUCTION”, ”SENT_TO_PRINTER”

and ”PRINTER_LOST” are not used at the moment (they are marked as deprecated) and will

eventually be removed from the database.

122

5.3.1.10. Guide “Order Status”

List of possible values of guide “Order status” is shown in Ошибка! Источник ссылки не

найден..

Table 95 – 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


Order status

Figure 72

5.3.1.11. Guide “Dropout Reason”

List of possible values of guide “Dropout Reason” is shown in Table 96.

Table 96 – Possible Values of Guide “Dropout Reason”

Code Constant Description Type

0 DEFECT Defect String

APPROVED

Подтверждён

READY

Готов

PENDING

В ожидании

DECLINED

Отклонен

CREATED

Создан

CLOSED

Закрыт

123

Code Constant Description Type

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

5.3.1.12. Guide “Marking Code Type”

Table 97 shows a list of possible values for guide “Marking code type”.

Table 97 – Possible Values of Guide “Marking Code Type”

Constant Description Type

UNIT Goods item String

BUNDLE Bundle String

GROUP Group retail package String

124

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:

1) Program entry error message (Figure ).

Program entry error message

Figure 73

2) System error message (Figure ).

System error message

Figure 74

125

6.2. Error Format and Codes

6.2.1. Error format

The format of response with error is shown in Table 98.

Table 98 – Format of Response with Error


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 99.

Table 99 – Object “ProtobeansError” Format


fieldError Error description String

fieldName Field name String

Example of JSON response with error is shown in Figure 75.

{ "fieldErrors": [ { "fieldError": "string", "fieldName": "string" } ], "globalErrors": [ "string" ], "success": false }

Example of JSON response with error

Figure 75

6.2.2. Description of Errors

Error codes in response to request are shown in Table 100.

Table 100 – Data Send Error Codes

Error code Description

400 Operation not completed. Wrong input parameters

500 Operation not completed. Internal server error.

126

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 101).

Table 101 – OMS API 2.0 Services Provision Matrix

OMS API 2.0 Method OMS-

Manufacturing 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; ● ●

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 ● ●

127

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 76).

128

List of CryptoPro Software Products

Figure 76

After clicking on the "CryptoPro JCP" link, the user gets the list of library versions available for downloading (Figure 77).

129

List of “CryptoPro JCP” Versions

Figure 77

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 78).

Content of “CryptoPro JCP” Library

Figure 78

130

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 79).

Examples of “CryptoPro JCP” Use

Figure 79

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.

131

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 102).

To generate a detached signature, parameter “detached” shall contain value “true”.

Table 102 - 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); }

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.

132

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 103).

Table 103 - 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:

1) URL: address of the resource where the request is sent;

2) "@headers.txt" – file containing the HTTP header of the request (excluding “X-

Signature” parameter);

3) "@XSignature.txt" – file containing parameter “X-Signature” from the request HTTP

header;

4) "@order.json" – file containing the request data.

133

APPENDIX

LIST OF APPLICATION PROGRAMMING INTERFACE CHANGES

Version Date OMS

version List of Modifications

2.87 07/22/2020 3.1.14

The following modifications were introduced: - Corrected the numeration misprint in the template guide (see section 5.3.1.4): number 13 changed to 14, number 14 to 15, deleted extra number 15;

2.86 07/13/2020 3.1.14

The following modifications were introduced: - the description of goods groups in section 4.5 enlarged: added “Packed water” goods group; - Added the enlargement for “Order” within the request on the order creation for “Packed water” good group (see section 4.5.1.1.12); - Added new template to the Guide “MC template” with code 16 (see section 5.3.1.4); - Added the information on the rejection, aggregation and utilization (application) reports sending отчетов об отбраковке for “Packed water” goods group (see sections 4.5.2, 4.5.3, 4.5.4); - Added the enlargement for the object UtilisationReport for the goods group “Packed water” within the request for the utilization report sending (see section 4.5.4.1.5). - Excluded the information on availability of the method of application report sending for EEU Operator for “Footwear”, “Tyres and new pneumatic rubber tire casings”, “Items of clothing, bed, table, bath and kitchen linens”, “Perfume and eau de toilette”, “Photo cameras (except cine cameras), flash lights and flash bulbs” (see section 4.5.4); - Excluded the example of report sending on application for EEU Operator (see section 4.5.4.1).

2.85 7/10/2020 3.1.14

The following modifications were introduced: - Description of the CHECK (“Being checked”) status added to the “Report Processing Status” Guide (see section 5.3.1.8); - Extended description of product groups in section 4.5: alternative tobacco products added; - Extension for objects “Order” and “OrderProduct” added for order creation request for the “Alternative tobacco products” product group (see section 4.5.1.1.11); - New templates added to the “MC Templates” Guide with codes 14 and 15 (see section 5.3.1.4); - Information on the option of sending aggregation and utilization (application) reports being available for the “Alternative tobacco products” product group added (see sections 4.5.3, 4.5.4);

Шаблоны_КМ#_Справочник_

Шаблоны_КМ#_Справочник_

134

Version Date OMS


- Extension for object “AggregationReport” added for the “Alternative tobacco products” product group for request for sending an Aggregation report (see section 4.5.3.1.3); - Extension for object “UtilisationReport” added for the “Alternative tobacco products” product group for request for sending a Utilisation report (see section _Расширения_для_производителей_4.5.4.1.4); - Information on the availability of the Application report sending method for the EEU Operator added for the following product groups: “Footwear”, “New pneumatic rubber tires and tire casings”, “Items of clothing, bed, table, bath and kitchen linens”, “Perfume and eau de toilette”, “Photo cameras (except cine cameras), flash lights and flash bulbs” (see section 4.5.4); - Example of sending an Application report for the EEU Operator added (see section 4.5.4.1). - New extensions used in url API added: “lp” (for the “Items of clothing, bed, table, bath and kitchen linens” product category) and“shoes” (for the “Footwear” product category) (see section Ошибка! Источник ссылки не найден.). Extension “light” previously used for both of these product categories will be abandoned in the future; - In the provided request examples, the “light” extension will be replaced with “lp” and “shoes” throughout the document; - The description of the method of sending the Aggregation report was supplemented with a note on the method being available for the EEU Operator for the “Items of clothing, bed, table, bath and kitchen linens” product group, using the new “lp” extension (see section 4.5.3). - serviceProviderId field added to the Order high-level object for creating an MC order for distribution (see section 4.5.1.1); - Note on the “CROSSBORDER” value being available for the “Dairy products” product group added to the “Method of Goods Introduction into Circulation” Guide (see sections 5.3.1.1); - Values of the “Manufacturing Method” Guide extended (see section 5.3.1.3); - In the description of the method for creating an order for the “Dairy products” product group, in notes to fields of the “Order” extension, the detail regarding the “IMPORT” and “CROSSBORDER” methods of goods introduction into circulation being inapplicable is removed (see section 4.5.1.1.8).

2.84 6/19/2020 3.1.14

The following changes have been incorporated: - Deleted unused Guide “Marking types” with values “On a goods item”, “On a consumer packing”, “On a goods label” (see section 5.3.1); - The links to other guides across the entire document text (due to the shift the sections numeration) (see section 5.3.1);

135

Version Date OMS


- In the matrix of provision of OMS API 2.0 services a misprint of double header of OMS-Cloud in the table has been corrected (see section 7); - In the matrix of APIOMS 2.0 services removed out dated column for this document «OMS-Client» (see section 7); - In the list of terms updated the description of term introduction into circulation and specified that the term is stated for dairy products since within the document is used only for the description of report on automatic introduction into the circulation for dairy products (see section 4.5.17); - For the description of the method of report sending aggregation added a note on usage of this method by EEU operator within the goods groups “Perfume and eau de toilette”, “Photo cameras (except cine cameras), flash lights and flash bulbs” (see section 4.5.3).

2.83 6/3/2020 3.1.14

The following modifications were introduced: - A new field called REMARK has been added to the catalog of release methods, specifying the list of goods groups that the value of this field applies to (see section 5.3.1.1); - The description of the order creation method for the goods group “Dairy Products” now has notes for the fields of the “Order” extension that point out that the REMARK release method is inapplicable (see section 4.5.1.1.8); - Information has been added catalog of the methods for releasing goods into circulation, specifying that the CROSSORDER value is applicable to such goods groups as “Items of clothing, bed, table, bath and kitchen linen”, “New pneumatic rubber tires and tire casings”, “Perfume and eau de toilette”, “Photo cameras (except cine cameras) flash lights and flash bulbs”(see section 5.3.1.1); - The description of the order creation method for “Items of clothing, bed, table, bath and kitchen linen”, “New pneumatic rubber tires and tire casings”, “Perfume and eau de toilette”, “Photo cameras (except cine cameras) flash lights and flash bulbs” in the notes for the fields of the “Order” object now no longer has information on the ban on the use of the CROSSORDER value of the release method (see sections 4.5.1.1.2, 4.5.1.1.4, 4.5.1.1.5, 4.5.1.1.6); - For the goods groups “Items of clothing, bed, table, bath and kitchen linen”, “New pneumatic rubber tires and tire casings”, “Perfume and eau de toilette”, “Photo cameras (except cine cameras) flash lights and flash bulbs” the description of the “Order” method in the OrderProduct object extension now has the field exporterTaxpayerID (see sections 4.5.1.1.2, 4.5.1.1.4, 4.5.1.1.5, 4.5.1.1.6).

2.82 5/29/2020 3.1.13 The following modifications were introduced:

136

Version Date OMS


- For the 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 for cine cameras), flash lights and flash bulbs” in the “Order” object structure used in the query that creates a new order, the fields contractDate, contractNumber (see sections 4.5.1.1.2, 4.5.1.1.3, 4.5.1.1.4, 4.5.1.1.5, 4.5.1.1.6) have been removed as they are no longer used from 01.01.2020; - The values “USED_FOR_PRODUCTION”, “SENT_TO_PRINTER” and “PRINTER_LOST” of the UsageType table have been marked as deprecated and are going to be removed from it (see section 5.3.1.10); - The response to the query about the status of the MC array the field poolInfos is marked as option: it does not have to be filled in if the buffer is not active yet or if the order has been turned down (see section 4.5.7.2).

2.81 5/11/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); - Added an example of REST request for sending an MC aggregation report containing the AggregationReport base object and no extensions (used for Footwear when sent by an EEU Operator) (see Section 4.5.3.1).

2.80 5/7/2020 3.1.12

The following modifications were introduced: - Note added that the aggregation type can be applied to the “Footwear” goods group, but is only available to EEU Operators (see Section 4.5.3) - 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)

137

Version Date OMS


- Note to field serialNumberType for order creation request was changed: the initially set field value cannot 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);

− 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:

138

Version Date OMS


- 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.1


− The Note was added to the introduction into circulation method «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


− 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 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


− Note was added to the format 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


− 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”.

139

Version Date OMS


− 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

2.67 1/22/2020

3.1.10


− 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 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


− 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 utilization and automatic introduction into circulation report sending method and request for the number of document on introduction into circulation were added


− The option of repetitive MC obtaining was added.

140

Version Date OMS


− 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 method for obtaining the commodity nomenclature guide (product/info) was removed.

− GG “Dairy products” support was restored


− The order closure description was changed


− GG “Dairy products” support was removed

2.60 11/7/2019 3.1.9


− 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


− 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 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.

141

Version Date OMS


− 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


− Description of requirements for transmission of detached digital signature was updated


− Section with description of requirements for transmission of detached digital signature was added

2.54 9/30/2019


− 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 information attribute “offset” is excluded in MC obtaining response


− The compulsoriness of attribute “contactPerson” was corrected, the attribute is mandatory


− Valid marking codes according to GS1 specification were updated


− For the Tobacco industry, the “sourceReportId” attribute is updated in the extension of MC utilization report

142

Version Date OMS


2.49 9/20/2019


− 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 description of the product registration API (Product Registration API) was added.

− Non-mandatory parameter “brandcode” was added to the extension for the tobacco industry


− Restriction on the number of marking codes was added to the dropout report


− The restriction and parameter “tokenName” were added to the method of obtaining security marker by username and password

2.45 8/15/2019


− 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


− Explanation regarding the serial numbers generation method was added.

− Explanation to template 1 and 10 was added


− The maximum amount of MC in the utilization report (30,000 MC) was changed


− Template for the Light Industry was added


143

Version Date OMS


− The marking code order closure rule (Note) was added.

− The marking code order obtaining rule (Note) was added

2.40 7/22/2019


− 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.

− 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


− 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” (), 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

144

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.

145

Goods introduction into circulation (introduction into circulation), with regards to the man-

ufacturing of dairy products in the Russian Federation: the act of manufacturer offering

dairy products for retail sale, or initial transfer of dairy products, with or without charge,

from a manufacturer to a new owner or another person with the purpose of making such

person their owner or for future sale, which makes those dairy products available for dis-

tribution and (or) use;

- outside the Russian Federation (with the exception of dairy products imported from the

EEU countries): –released by customs authorities of dairy products for internal

consumption imported to the Russian Federation; outside the Russian Federation related

to the dairy products imported from EEU member-countries under the crossboarder trade

on the customs EEU territory, - import by a legal entity or a physical entity registered as

an individual entrepreneur, of dairy products to the Russian Federation;

8) 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.

9) 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.

10) 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.

11) Electronic Interface is aggregated resources and rules that enable interaction

between the goods circulation participants’ firmware and Track and Trace Information

System.

12) 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:

146

− 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.

13) 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.

14) 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;

− 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;

147

− 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



the ASCII character table.

15) 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



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



the ASCII character table.

16) 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).

17) 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.

18) 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.

19) 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.

148

20) Marking of goods with the identification means is application of goods identification

means on the consumer package, or product label, or goods.

21) 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.

22) 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.

23) 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.

24) 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.

25) 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.

26) 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.

27) 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.

28) 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.

29) 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

149

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.

30) 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).

31) 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.

32) 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.

33) Technical Support Service (TSS) is a technical support service for the Track and

Trace Information System users.

34) 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.

35) EQES is an enhanced qualified electronic signature.

150

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

151

LIST OF FIGURES

Figure 1 ...................................................................................................................................... 14

Figure 2 ...................................................................................................................................... 15

Figure 3 ...................................................................................................................................... 18

Figure 4 ...................................................................................................................................... 20

Figure 5 ...................................................................................................................................... 22

Figure 6 ...................................................................................................................................... 24

Figure 7 ...................................................................................................................................... 29

Figure 8 ...................................................................................................................................... 31

Figure 9 ...................................................................................................................................... 34

Figure 10 .................................................................................................................................... 36

Figure 11 .................................................................................................................................... 38

Figure 12 .................................................................................................................................... 40

Figure 13 .................................................................................................................................... 41

Figure 14 .................................................................................................................................... 43

Figure 15 .................................................................................................................................... 44

Figure 16 .................................................................................................................................... 45

Figure 17 .................................................................................................................................... 47

Figure 18 .................................................................................................................................... 48

Figure 19 .................................................................................................................................... 49

Figure 20 .................................................................................................................................... 51

Figure 21 .................................................................................................................................... 51

Figure 22 .................................................................................................................................... 52

Figure 23 .................................................................................................................................... 53

Figure 24 .................................................................................................................................... 56

Figure 25 .................................................................................................................................... 56

Figure 26 .................................................................................................................................... 57

Figure 27 .................................................................................................................................... 58

Figure 28 .................................................................................................................................... 59

Figure 29 .................................................................................................................................... 60

Figure 30 .................................................................................................................................... 61

Figure 31 .................................................................................................................................... 64

Figure 32 .................................................................................................................................... 67

Figure 33 .................................................................................................................................... 68

Figure 34 .................................................................................................................................... 69

Figure 35 .................................................................................................................................... 70

Figure 36 .................................................................................................................................... 71

Figure 37 .................................................................................................................................... 72

152

Figure 38 .................................................................................................................................... 73

Figure 39 .................................................................................................................................... 74

Figure 40 .................................................................................................................................... 76

Figure 41 .................................................................................................................................... 77

Figure 42 .................................................................................................................................... 78

Figure 43 .................................................................................................................................... 80

Figure 44 .................................................................................................................................... 81

Figure 45 .................................................................................................................................... 81

Figure 46 .................................................................................................................................... 82

Figure 47 .................................................................................................................................... 84

Figure 48 .................................................................................................................................... 85

Figure 49 .................................................................................................................................... 87

Figure 50 .................................................................................................................................... 88

Figure 51 .................................................................................................................................... 89

Figure 52 .................................................................................................................................... 90

Figure 53 .................................................................................................................................... 91

Figure 54 .................................................................................................................................... 92

Figure 55 .................................................................................................................................... 93

Figure 56 .................................................................................................................................... 94

Figure 57 .................................................................................................................................... 95

Figure 58 .................................................................................................................................... 96

Figure 59 .................................................................................................................................... 97

Figure 60 .................................................................................................................................... 98

Figure 61 .................................................................................................................................. 100

Figure 62 .................................................................................................................................. 102

Figure 63 .................................................................................................................................. 103

Figure 64 .................................................................................................................................. 108

Figure 65 .................................................................................................................................. 109

Figure 66 .................................................................................................................................. 110

Figure 67 .................................................................................................................................. 111

Figure 68 .................................................................................................................................. 112

Figure 69 .................................................................................................................................. 119

Figure 70 .................................................................................................................................. 120

Figure 71 .................................................................................................................................. 121

Figure 72 .................................................................................................................................. 122

Figure 73 .................................................................................................................................. 124

Figure 74 .................................................................................................................................. 124

Figure 75 .................................................................................................................................. 125

Figure 76 .................................................................................................................................. 128

Figure 77 .................................................................................................................................. 129

153

Figure 78 .................................................................................................................................. 129

Figure 79 .................................................................................................................................. 130

154

LIST OF TABLES

Table 1 – Example of Request with Handover of a Detached Signature ..................................... 9

Table 2 — List of Applicability Indicators which the System shall be Compliant with ................. 11

Table 3 – Valid MC-Symbols ..................................................................................................... 13

Table 4 – Request String Parameters ........................................................................................ 26

Table 5 – Description of JSON Format of Request for Creation and Sending of MC Emission

Order, object “Order” ..................................................................................................... 26

Table 6 – Format of Object “OrderProduct” ............................................................................... 27

Table 7 – Description of Extension for Object “OrderProduct” for Tobacco Industry ................. 28

Table 8 – Description of Extension for Object “Order” for Tobacco Industry .............................. 28

Table 9 – Description of Extension for Object “Order” for Goods Group Category “Items of

Clothing, Bed, Table, Bath and Kitchen Linen” ............................................................. 30

Table 10 – Description of “OrderProduct” Object Extension for Light Industry of Goods Group

Category “Items of Clothing, Bed, Table, Bath and Kitchen Linen” ............................... 30

Table 11 – Description of Extension for Object “Order” for Light Industry, Goods Group Category

“Footwear” ..................................................................................................................... 32

Table 12 – Description of Extension for Object “OrderProduct” for GG “Footwear” ................... 33

Table 13 – Description of Extension for Object “Order” for Tire Manufacturers, Goods Group

Category “New Pneumatic Rubber Tires and Tire Casings” ......................................... 35

Table 14 – Description of “OrderProduct” Object Extension for Tire Manufactures in the goods

group category of New Pneumatic Rubber Tires and Tire Casings. .............................. 35

Table 15 – Description of Extension for Object “Order” for Perfumery Products Manufacturers,

Goods Group Category “Perfume and Eau de Toilette” ................................................ 37

Table 16 – Description of “OrderProduct” Object Extension for the Perfumery Manufacturers of

Goods Group Category “Perfume and Eau De Toilette” ................................................ 37

Table 17 – Description of Extension for Object “Order” for Photo Products Manufacturers,

Goods Group Category “Photo Cameras (Except Cine Cameras), Flash Lights and

Flash Bulbs” .................................................................................................................. 39

Table 18 – 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” ................................................................................................. 39

Table 19 – Description of Extension for Object “Order” for Pharmaceutical Industry ................. 41

Table 20 – Description of Extension for Object “Order” for the Dairy Manufacturers ................. 42

Table 21 – Description of Extension for Object “Order” for the Dairy Manufacturers ................. 42

155

Table 22 – Description of Extension for Object “Order” for the Manufacturers of Bicycles and

Bicycle Frames .............................................................................................................. 44

Table 23 – Description of Extension for Object “Order” for the Wheelchair Manufacturers ....... 45

Table 24 – Description of extension for object “OrderProduct” for alternative tobacco products 46

Table 25 – Structure of extension for object “Order” for alternative tobacco products ............... 46

Table 26 – Format of Response to Request .............................................................................. 49

Table 27 – Request String Parameters ...................................................................................... 50

Table 28 – Object “DropoutReport” Structure ............................................................................ 50

Table 29 – Description of Extension for Object “DropoutReport” for Tobacco Industry ............. 51

Table 30 – Format of Response to Request to Send Notification on MC Disposal / Rejection .. 53


Table 32 – Object “AggregationReport” Structure ...................................................................... 55

Table 33 – Object “AggregationUnit” Structure .......................................................................... 55

Table 34 – Description of Extension for Object “AggregationReport” for Tobacco Industry ....... 56

Table 35 – Description of extension for object “AggregationReport” for alternative tobacco

products ........................................................................................................................ 60

Table 36 – Format of Response to Request to Send Information on Aggregation ..................... 61


Table 38 – Object “UtilisationReport” Structure ......................................................................... 63

Table 39 – Description of Extension for Object “UtilisationReport” for Tobacco Industry ........... 64

Table 40 – Description of Extension for Object “UtilisationReport” for Pharamceutical Industry 65

Table 41 – Description of Extension for Object “UtilisationReport” for the Dairy Manufacturers 69

Table 42 – Description of extension for object “UtilisationReport” for manufacturers of alternative

tobacco products ........................................................................................................... 70

Table 43 – Format of Response to Request to Send Report on MC Application ....................... 72


Table 45 – Format of Response to Request to Close Suborder by GTIN Specified .................. 74


Table 47 – Format of Response to Request for MC for the Goods Specified ............................ 77


Table 49 – Format of Response to Request, object “BufferInfo” ................................................ 79

Table 50 – Object “PoolInfo” Format .......................................................................................... 79


156

Table 52 – Format of Response to Request for Order Status .................................................... 83

Table 53 – Object “OrderSummaryInfo” Format ........................................................................ 83


Table 55 – Format of Response to Request for Information on Aggregation, object

“AggregationInfo” .......................................................................................................... 86

Table 56 – Object “OrderSummaryInfo” Format ........................................................................ 86

Table 57 – Description of the “AggregationInfo” Object Extension for Tobacco Industry

Manufacturers ............................................................................................................... 88


Table 59 – Format of Response to Request for the Report Processing Status .......................... 90


Table 61 – Request Body Parameters ....................................................................................... 91

Table 62 – Format of Response to Request for OMS Availability .............................................. 92


Table 64 – Format of Response to Request for OMS Availability .............................................. 94

Table 65 – HTTP Header Parameters ....................................................................................... 95


Table 67 – Format of Response to Request for Security Marker ............................................... 96

Table 68 – Format of Response to Request for OMS and API Version ..................................... 97


Table 70 – Format of Response to Request for the List of MC Packet Identifiers for the Marking

and Goods Code Order Specified ................................................................................. 99

Table 71 – Format of MC Package List, Object “Block” ............................................................. 99

Table 72 – Request String Parameters .................................................................................... 101

Table 73 – Format of Response to Request for Re-obtainment of MC for the Goods Specified

.................................................................................................................................... 103


Table 75 – Object “RollOutReport” Structure ........................................................................... 104

Table 76 – Description of the Object “Produced” for Goods Made in the Russian Federation . 105

Table 77 – Description of the Object “Import” for Imported Goods .......................................... 105

Table 78 – Description of Object “Product” .............................................................................. 105

Table 79 – Description of Object “RollOutReport” Extension for Milk Producers ..................... 107

Table 80 - Format of Response to Request ............................................................................. 110


157

Table 82 - Format of Response to Request ............................................................................. 112

Table 83 – Possible Values of Guide “Method of Goods Introduction into Circulation” ............ 116

Table 84 – Possible Values of Guide “Method of Individual Serial Number Generation” ......... 116

Table 85 – Possible Values of Guide “Manufacturing Method” ................................................ 117

Table 86 – Possible Values of Guide “Manufacturing Method” ................................................ 117

Table 87 – Description of MC Templates ................................................................................. 118

Table 88 – Possible Values of Guide “MC Array Status” ......................................................... 118

Table 89 – Possible Values of Guide “Aggregation Type” ....................................................... 119

Table 90 – Possible Values of Guide “MC Buffer Status” ........................................................ 119

Table 91 – Possible Values of Guide “Report Processing Status” ........................................... 120

Table 92 – Possible Values of Guide “Type of Utilization” ....................................................... 121

Table 93 – Possible Values of Guide “Order Status” ............................................................... 122

Table 94 – Possible Values of Guide “Dropout Reason”.......................................................... 122

Table 95 – Possible Values of Guide “Marking Code Type” .................................................... 123

Table 96 – Format of Response with Error .............................................................................. 125

Table 97 – Object “ProtobeansError” Format ........................................................................... 125

Table 98 – Data Send Error Codes .......................................................................................... 125

Table 99 – OMS API 2.0 Services Provision Matrix ................................................................. 126

Table 100 - Parameters of CMS Format Signature Generation Function. ............................... 131

Table 101 - Example of Command to Verify the Request Signature ........................................ 132

158

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

Documents

AGREED BY APPROVED BY General Director CRPT, LLC 2020 2020 · 2 RU 15861920.620111-04 33 01 ANNOTATION This document «OMS-Cloud 3.1. Special Software. Programmer’s Guide» RU 15861920.620111-04