ICOM: API - Integration, instruction

The purpose of the special Order Management Station (OMS) software is for manufacturers and importers to perform key operations in the production of labeled products, including:

• generation of orders for issuance of labeling codes;
• receiving (uploading) ordered labeling codes;
• generation of reports on application (use) of labeling codes;
• generation of reports on aggregation of finished, packaged products with applied means of digital identification;
• generation of reports on rejection (write-off) of defective products with applied means of digital identification.

ICOM is used in the labeling of the following product groups:

* OMS is used until the specified date (Cloud 3.1).

The documentation provides a description of the program interaction interface (API) of the order management station - OMS (ICOM), in which the interaction is performed via HTTP protocol using JSON format.

The basic sequence of invocation of OMS (ICOM) methods when creating a new order for issuing labeling codes:

1. Checking the availability of OMS services (ICOM).
2. Creating an order for the issuance of labeling codes.
3. Retrieve labeling codes from the order buffer.
4. Closing an order/sub-order by the specified GTIN.
5. Creating a labeling code report.
6. Creating a label code aggregation report.
7. Creating a report on writing off (discarding) labeling codes.

The API also provides auxiliary methods:

1. Retrieve report / report processing status by report ID.
2. Obtaining the list of orders of participants of goods circulation / obtaining the status of orders.
3. Retrieving a list of labeling code package identifiers.
4. Retrieving labeling codes from an order.

The key differences between the OMS (ICOM) and the OMS (Cloud 3.1):

1. The possibility of submitting the "Report on application (use) of labeling codes" (api/v2/{extension}/utilization) is implemented:

• the report on application (use) of marking codes is generated by the participants of the turnover independently (taking into account the production cycle)
• the report may contain the date of production ("productionDate"), production series number ("seriesNumber") and expiration date ("expirationDate") of the labeled products.

2. Method "Creating an order for issuing labeling codes" (api/v2/{extension}/orders):

• an error was fixed, when for some parameters ("quantity", "templateId"), which are numeric (integer), it was allowed to pass a string;
• an error was fixed, when some parameters ("templateId"), which are mandatory, were missing in the query;
• added optional field "Rate" ("rateType"), required for ordering labeling codes, the service for which is provided by the Operator without charging a fee.

3. Method "Receiving labeling codes from a sub-order" (api/v2/{extension}/codes):

• an error was fixed, when the "lastBlockId" parameter was processed incorrectly - if only a part of the ordered codes is unloaded from the order, the request for unloading the remaining part of the labeling codes from the same order must contain the value of the "lastBlockId" parameter equal to the identifier of the code packet received in the previous request ("BlockId"), otherwise the first received code packet will be unloaded.

4. Method "Receiving labeling codes array status from an order" (api/v2/{extension}/ buffer/status):

• an error was fixed, in the description of the "poolInfos" parameter in the response - the "poolInfos" parameter is optional and is filled in only after the first package of labeling codes ("BlockId") has been unloaded, the "poolInfos" parameter is not filled in for rejected orders and orders from which labeling codes were not unloaded.

5. Method " Receiving the list of orders" (api/v2/{extension}/orders):

• the possibility of forming the list of orders taking into account the order status ("status") and creation date (from "dateFrom" to "dateTo") has been implemented

6. Method "Create a report on labeling code aggregation" (api/v2/{extension}/aggregation):

• an error was fixed, where a "string" was allowed in a query for some parameters ("aggregatedItemsCount", "aggregationUnitCapacity") that were numeric ("integer").

7. Support for the following methods has been discontinued:

• method "Get version of OMS and API" (api/v2/{extension}/version)
• method "Get security token by username and password" (api/v2/{extension}/token)
• method "Get aggregation information" (api/v2/{extension}/aggregation/info)

Restrictions when creating orders and reports:

Labeling Code Issuance Order:

• no more than 150 thousand codes for each product (GTIN) in an order
• no more than 10 goods (GTIN) in one order
• no more than 100 active orders (after order fulfillment and receipt of marking codes the order must be closed, thus confirming order fulfillment and receipt of marking codes)

Report on the application of labeling codes:

• no more than 30 thousand codes in one report

Labeling Code Aggregation Report:

• no more than 11 thousand codes in one report (the total number of aggregated codes and formed aggregates is taken into account)

Report on the write-off of labeling codes:

• no more than 30 thousand codes in one report