Описание API для работы с ТС ПИоТ

Сервис предназначен для проверки кодов маркировки (КМ) в Честном знаке через модуль ТС ПИоТ, запущенный на Цифровой кассе, для выполнения требований разрешительного режима.

Версия сервиса v1 поддерживает онлайн-проверку КМ в Честном знаке в соответствии с методическими рекомендациями ЦРПТ.

Для начала работы с сервисом необходимо предварительно пройти процедуру регистрации компании (магазина) и получить учетные данные (логин, пароль, идентификатор группы ККТ) посредством Личного кабинета Цифровой кассы Эвотор, зарегистрировать личный кабинет в АО ЕСП и приобрести лицензию ТС ПИоТ, зарегистрировать личный кабинет в Честном знаке и выпустить токен для ККТ.

Подключение ТС ПИоТКак начать работу с ТС ПИоТ на Цифровой кассе

Общий алгоритм взаимодействия с сервисом через API

После получения учетных данных необходимо запросить токен авторизации используя метод из API фискализации (коннектор АТОЛ Онлайн).

Для отправки кода маркировки на проверку в ТС ПИоТ необходимо воспользоваться POST-запросом. В случае корректного запроса сервис пришлет ответ, содержащий уникальный идентификатор, присвоенный данному запросу, и статус.

Результат проверки КМ через ТС ПИоТ может быть получен двумя способами:

В случае, если в запросе на регистрацию был указан callback_url, сервис по результатам обработки вернет POST запрос на этот URL;
В случае, если callback_url не был указан, или запрос не пришел в течение 300 секунд с момента отправки, клиент самостоятельно может запросить результат обработки GET-запросом к сервису, описанному в разделе Получение результата проверки.

Регистрация запроса на проверку кода маркировки

Описание

Метод позволяет зарегистрировать запрос на проверку кода маркировки в ТС ПИоТ.

Запрос

POST https://fiscalization.evotor.ru/tspiot/v1/<group_code>/check-codes

Заголовок запроса должен содержать параметры:

Content-type: application/json; charset=utf-8
Token: <token>

При технической невозможности передать token в заголовке запроса можно передать параметр в строке запроса.

https://fiscalization.evotor.ru/tspiot/v1/<group_code>/check-codes?token=<token>

Пример запроса
curl -X POST "https://fiscalization.evotor.ru/tspiot/v1/2f8f6e97-ab0a-4b5c-bd39-31bc1adee6d8/check-codes" \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "token: token123" \
    -d '{
        "codes": [
            "0104670540176099215MpGKy",
            "MDEwNDYwNzAxMDM1MDI0NjIxNWtSZEctMSVXKFVtblx1MDAxZDkzZEdWeg=="
        ],
        "callback_url": "callback-site.ru/callback"
    }'

Параметры запроса:

Поле	Тип	Обязательное	Описание
group_code	string	Да	Идентификатор группы ККТ
token	string	Да	Авторизационный токен
codes	array	Да	Массив кодов маркировки в формате GS1, нанесенных на товар, подлежащий маркировке средствами идентификации. Максимум 200 символов для каждого кода. Максимум 128 кодов маркировки. Рекомендуется кодировать строку в base64 непосредственно после сканирования.
callback_url	string	Нет	URL, на который необходимо ответить после обработки запроса. Максимальная длина строки – 256 символов.

Ответ на запрос

При отсутствии ошибок сервис вернет пакет, содержащий уникальный идентификатор проверки, присвоенный сервисом, и статус обработки.

Способы получения результатов проверки по ее идентификатору описаны в разделе Получение результата обработки документа.

Пример ответа
{
    "uuid": "f8326d53-3fb3-4f35-8856-cfd25f045488",
    "status": "wait"
}

Параметры ответа

Поле Тип Описание

uuid string Уникальный идентификатор. Максимальная длина строки – 128 символов. Используется для получения результата обработки запроса. Если запрос не удалось зарегистрировать, проверке не будет присвоен uuid.

status

enum (string)

Поле	Тип	Описание
uuid	string	Уникальный идентификатор. Максимальная длина строки – 128 символов. Используется для получения результата обработки запроса. Если запрос не удалось зарегистрировать, проверке не будет присвоен `uuid`.
status	enum (string)	Статус. Возможные значения: `done` – зарегистрирован; `fail` – ошибка; `wait` – ожидание.

Статус. Возможные значения:

done – зарегистрирован;
fail – ошибка;
wait – ожидание.

Пример ответа с ошибкой
{
    "error": {
        "text": "Не распознан токен запроса",
        "type": "system",
        "code": 10,
        "error_id": "20001"
    }
}

Параметры объекта error Возвращается только при наличии ошибки

Поле	Тип	Описание
code	integer	Код ошибки
error_id	string	Уникальный идентификатор ошибки
text	string	Текст ошибки (кодировка utf–8)
type	enum	Тип источника ошибки

Получение результата проверки

Описание

Результат проверки КМ через ТС ПИоТ может быть получен двумя способами:

В случае, если в запросе на регистрацию был указан callback_url, сервис по результатам обработки вернет POST запрос на этот URL;
В случае, если callback_url не был указан, или запрос не пришел в течение 300 секунд с момента отправки, клиент самостоятельно может запросить результат обработки GET-запросом к сервису.

Пакет с результатом обработки документа одинаков для обоих способов получения.

Запрос

GET https://fiscalization.evotor.ru/tspiot/v1/<group_code>/report/<uuid>

Заголовок запроса должен содержать параметры:

Content-type: application/json; charset=utf-8
Token: <token>

При технической невозможности передать token в заголовке запроса можно передать параметр в строке запроса.

https://fiscalization.evotor.ru/tspiot/v1/<group_code>/report/<uuid>?token=<token>

Параметры заголовка и строки запроса:

group_code: идентификатор группы ККТ;
uuid: уникальный идентификатор, присвоенный проверке после выполнения запроса на регистрацию;
token: авторизационный токен.

Пример запроса результата обработки документа
curl -X GET "fiscalization.evotor.ru/tspiot/v1/2f8f6e97-ab0a-4b5c-bd39-31bc1adee6d8/report/93ffec76-37d5-4232-be50-9d39010aa770" \
    -H "Content-Type: application/json; charset=utf-8" \
    -H "token: token123"

Ответ на запрос

При отсутствии ошибок сервис вернет пакет, содержащий уникальный идентификатор проверки, присвоенный сервисом ранее, статус обработки и массив с отдельными элементами для каждого кода маркировки. Элемент массива содержит ответ ТС ПИоТ и флаг, разрешающий продажу товара.

Пример ответа
{
    "uuid": "ad47ad9d-0109-4bc7-8ea1-3423a690189e",
    "status": "done",
    "payload":
    {
        "codesResponse":
        [
            {
                "code": 0,
                "description": "ok",
                "allowed": true,
                "codes":
                [
                    {
                        "cis": "0104670540176099215MpGKy",
                        "found": false,
                        "valid": false,
                        "printView": "0104670540176099215MpGKy",
                        "gtin": "04670540176099",
                        "groupIds":
                        [],
                        "verified": false,
                        "realizable": false,
                        "utilised": false,
                        "isBlocked": false,
                        "ogvs":
                        [],
                        "errorCode": 0,
                        "isTracking": false,
                        "sold": false,
                        "grayZone": false,
                        "packageType": "UNIT",
                        "producerInn": "7725344604",
                        "expireDate": "",
                        "productionDate": "",
                        "message": "",
                        "variableExpirations":
                        {},
                        "productWeight": 100,
                        "prVetDocument": "",
                        "isOwner": true,
                        "eliminationState": "",
                        "mrp": 100,
                        "smp": 100,
                        "innerUnitCount": 2,
                        "soldUnitCount": 3,
                        "parent": "",
                        "productionSerialNumber": "",
                        "productionBatchNumber": "",
                        "factorySerialNumber": "",
                        "packageQuantity": 2
                    }
                ],
                "reqId": "c9188551-817a-85a7-93e4-7042d907ab13",
                "reqTimestamp": "1757681987579",
                "isCheckedOffline": false
            },
            {
                "code": 0,
                "description": "ok",
                "allowed": false,
                "codes":
                [
                    {
                        "cis": "0104607010350246215kRdG-1%W(Umn\u001d93dGVz",
                        "valid": true,
                        "verified": false,
                        "utilised": false,
                        "realizable": false,
                        "sold": false,
                        "isBlocked": false,
                        "message": "cannot find code [0104607010350246215kRdG-1%W(Umn\u001d93dGVz] in db",
                        "grayZone": false,
                        "found": false,
                        "errorCode": 10,
                        "isTracking": false,
                        "gtin": "04607010350246",
                        "printView": "0104607010350246215kRdG-1%W(Umn",
                        "isOwner": false
                    }
                ],
                "isCheckedOffline": false
            }
        ]
    }
}

Параметры ответа

Поле Тип Описание

uuid string Уникальный идентификатор. Максимальная длина строки – 128 символов.

status

enum (string)

Поле	Тип	Описание
uuid	string	Уникальный идентификатор. Максимальная длина строки – 128 символов.
status	enum (string)	Статус. Возможные значения: `done` – зарегистрирован; `fail` – ошибка; `wait` – ожидание.
payload	object	Включает в себя массив `codesResponse`

Статус. Возможные значения:

done – зарегистрирован;
fail – ошибка;
wait – ожидание.

payload object Включает в себя массив codesResponse

Параметры элемента массива codesResponse

Поле	Тип	Описание
allowed	boolean	Решение ПМСР. Возможные значения: `True` – ПМСР разрешает продажу товара; `False` – ПМСР запрещает продажу товара.
reqId	uuid	Идентификатор проверки КМ по РР. Необходимо передавать в теге 1265 фискального чека. Возвращается, если товар разрешен к продаже (`allowed: True`).
reqTimestamp	string	Время проверки КМ по РР. Необходимо передавать в теге 1265 фискального чека. Возвращается, если товар разрешен к продаже (`allowed: True`).
isCheckedOffline	boolean	Флаг проверки в оффлайне: `True` — проверка в ЛМ ЧЗ; `False` — проверка в ГИС МТ. В настоящий момент поддержка ЛМ ЧЗ не реализована в соответствиями с методическими рекомендациями ЛМ ЧЗ. Проверки производятся только в режиме онлайн через ГИС МТ — всегда возвращается `isCheckedOffline: False`.
version	uuid	Версия Локального модуля Честного знака (ЛМ ЧЗ). Возвращается, если была проведена проверка в ЛМ ЧЗ (`isCheckedOffline: True`).
inst	uuid	Идентификатор экземпляра ЛМ ЧЗ. Возвращается, если была проведена проверка в ЛМ ЧЗ (`isCheckedOffline: True`).
code	number	Код ответа ТС ПИоТ
description	string	Описание ответа ТС ПИоТ
codes	array of objects	Массив, содержащий один элемент со сведениями о коде маркировки

Параметры элемента массива codes

Элемент массива codes содержит сведения о проверенном КМ из Честного знака. Сведения могут использоваться для настройки дополнительных правил блокировки продаж на стороне клиента API, например чтобы блокировать продажу товаров с истекающим сроком годности.

Параметр	Тип	Описание	Комментарий
cis	string	КИ / КиЗ из запроса
found	boolean	Признак наличия кода в ГИС МТ	Возможные значения: true — «Код найден»; false — «Код не найден»
valid	boolean	Результат проверки валидности структуры КИ / КиЗ	Возможные значения: true — «Структура валидная»; false — «Структура не валидная»
printView	string	КИ без крипто-подписи / КиЗ
gtin	string	Код товара
groupIds	array[integer]	Массив идентификаторов товарных групп
verified	boolean	Результат проверки крипто-подписи КМ	Возможные значения для всех товарных групп, кроме «Товары из натурального меха»: true — проверка крипто-подписи завершилась успешно; false — проверка крипто-подписи завершилась с ошибкой. Возможные значения для товарной группы «Товары из натурального меха»: true — КиЗ найден в «ИР Маркировки»; false — КиЗ не найден в «ИР Маркировки»
realizable	boolean	Признак возможности реализации КИ / КиЗ	Признак показывает, находится ли КИ / КиЗ в статусе «В обороте», то есть выполнено ли необходимое условие для реализации в розницу. Возможные значения: true – КИ / КиЗ в статусе «В обороте»; false – КИ / КиЗ в статусе, отличном от «В обороте»
utilised	boolean	Признак нанесения КИ / КиЗ на упаковку	Возможные значения: true — «КИ / КиЗ нанесён»; false — «КИ / КиЗ не нанесён»
expireDate	string	Дата и время истечения срока годности	Формат yyyy-MM-dd’T’HH:mm:ss.SSSz
variableExpirations	object	Информация о вариативном сроке годности	Информация о сроках годности в зависимости от условий хранения возвращается из карточки товара в НКМТ в формате: "<индекс>: <дата>". Формат даты: yyyy-MMddTHH:mm:ss.SSSZ. Параметр возвращается только для товарной группы «Молочная продукция»
productionDate	string	Дата производства продукции	Формат yyyy-MM-dd’T’HH:mm:ss.SSSz
productWeight	number	Переменный вес продукции (в граммах)	Возвращается только для товарной группы «Молочная продукция» (не возвращается для товаров из Республики Беларусь)
prVetDocument	string	Производственный ветеринарный сопроводительный документ	Возвращается только для товарной группы «Молочная продукция» (не возвращается для товаров из Республики Беларусь)
isOwner	boolean	Признак того, что в запросе указан владелец кода	Возможные значения: true — КИ / КиЗ принадлежит участнику, ИНН которого был указан в запросе; false — КИ / КиЗ не принадлежит участнику, ИНН которого был указан в запросе. Для товарных групп «Молочная продукция», «Упакованная вода» всегда возвращается значение «true». Параметр возвращается, если в запросе было указано значение параметра «inn» («ИНН предполагаемого владельца кода»)
isBlocked	boolean	Признак того, что розничная продажа продукции заблокирована по решению ОГВ	Возможные значения: true — продажа заблокирована; false — продажа не заблокирована.
ogvs	array[string]	Органы государственной власти, установившие блокировку на КИ	Возвращается, если значение поля «isBloсked» («Признак заблокированного КИ») = «true». Возможные значения: RAR — Росалкогольтабакконтроль; FTS — ФТС России; FNS — ФНС России; RSHN — Россельхознадзор; RPN — Роспотребнадзор; MVD — МВД России; RZN — Росздравнадзор
message	string	Сообщение об ошибке
errorCode	integer	Код ошибки	Возможные значения: 0 — ошибки отсутствуют; 1 — ошибка валидации КМ; 2 — КМ не содержит GTIN; 3 — КМ не содержит серийный номер; 4 — КМ содержит недопустимые символы; 5 — ошибка верификации крипто-подписи КМ (формат крипто-подписи не соответствует типу КМ); 6 — ошибка верификации крипто-подписи КМ (криптоподпись невалидная); 7 — ошибка верификации крипто-подписи КМ (крипто-ключ не валиден); 8 — КМ не прошел верификацию в стране эмитента; 9 — Найденные AI в КМ не поддерживаются; 10 — КМ не найден в ГИС МТ; 11 — КМ не найден в трансгране
isTracking	boolean	Признак контроля прослеживаемости в товарной группе	Возможные значения: true — контроль прослеживаемости в товарной группе для данного КИ / КиЗ включен; false — контроль прослеживаемости в товарной группе для данного КИ / КиЗ выключен
sold	boolean	Признак продажи товара	Возможные значения: true — товар продан; false — товар не продан
eliminationState	number	Признак использования причин выбытия, разрешающих продажу КМ	Заполняется на основании причины вывода из оборота КМ. Возможные значения: 1 — «BY_SAMPLES» («Продажа по образцам») / «DISTANCE» («Дистанционная продажа»); 2 — «OWN_USE» («Использование для собственных нужд») / «PRODUCTION_USE» («Использование для производственных целей»)
mrp	number	Максимальная розничная цена	В копейках. Только для товарных групп «Альтернативная табачная продукция», «Никотиносодержащая продукция», «Табачная продукция»
smp	number	Единая минимальная цена (ЕМЦ)	Значение указывается в копейках. Параметр возвращается только для товарной группы «Табачная продукция»
grayZone	boolean	Признак принадлежности табачной продукции к «серой зоне»	Возможные значения: true — принадлежит; false — не принадлежит
innerUnitCount	integer	Количество единиц товара в потребительской упаковке / Фактический объём / Фактический вес	Параметр может содержать следующие значения: количество единиц товара (только для товарных групп «Альтернативная табачная продукция», «Духи и туалетная вода», «Медицинские изделия»); фактический объём кега, мл (только для товарной группы «Пиво, напитки, изготавливаемые на основе пива, слабоалкогольные напитки»); фактический вес, г (только для товарной группы «Молочная продукция»)
soldUnitCount	integer	Счётчик проданного и возвращённого товара	Параметр может содержать следующие значения: количество проданных единиц товара (только для товарных групп «Альтернативная табачная продукция», «Духи и туалетная вода», «Медицинские изделия»); проданный объём кега, мл (только для товарной группы «Пиво, напитки, изготавливаемые на основе пива, слабоалкогольные напитки»); проданный вес, г (только для товарной группы «Молочная продукция»)
packageType	string	Тип упаковки	См. «Справочник "Типы упаковки"». Для товарной группы «Товары из натурального меха» значение всегда «UNIT»
parent	string	КИ агрегата	Кроме товарной группы «Товары из натурального меха»
producerInn	string	ИНН производителя	Параметр не будет возвращаться для молочной продукции Республики Беларусь
productionSerialNumber	string	Номер производственной серии	Параметр возвращается только для товарной группы «Медицинские изделия»
productionBatchNumber	string	Номер производственной партии	Параметр возвращается только для товарной группы «Медицинские изделия»
factorySerialNumber	string	Заводской серийный номер	Параметр возвращается только для товарной группы «Медицинские изделия»
packageQuantity	integer	Ёмкость КИГУ	Количество потенциально вмещаемых вложений

Пример ответа с ошибкой
{
    "uuid": "48676746-b452-459b-a8fe-16db3f4b5825",
    "status": "fail",
    "error": {
        "text": "Отсутствует лицензия ТС ПИоТ",
        "type": "tspiot",
        "code": 500,
        "error_id": "69d7aed4ac29f70ab434fb5f2c5189b5"
    }
}

Параметры объекта error

Возвращается только при наличии ошибки

Поле	Тип	Описание
code	integer	Код ошибки
error_id	string	Уникальный идентификатор ошибки
text	string	Текст ошибки (кодировка utf–8)
type	string	Тип источника ошибки

Описание API для работы с ТС ПИоТ

Общий алгоритм взаимодействия с сервисом через API​

Регистрация запроса на проверку кода маркировки​

Ответ на запрос​

Получение результата проверки​

Ответ на запрос​

Общий алгоритм взаимодействия с сервисом через API

Регистрация запроса на проверку кода маркировки

Ответ на запрос

Получение результата проверки

Ответ на запрос