API «Честного ЗНАКа» в 2026 году: True API, СУЗ, токены и ошибки

Проверено 4 сентября 2026 года. Продавцы описывают работу с маркировкой почти одинаково: «нужно руками зайти в «Честный ЗНАК», зайти в маркировку, заказать, вывести». API нужен ровно затем, чтобы этот маршрут перестал быть ручным. Но API «Честного ЗНАКа» — это не один интерфейс, а несколько контуров с разной авторизацией и разными ключами, и пока они не разложены по полкам, интеграция буксует на первом же запросе.

Разбираем, из чего состоит API ГИС МТ, где лежит ключ доступа и кто в кабинете вообще имеет право его видеть, что на самом деле произошло с переходом на единый токен, во сколько обходится сгоревший заказ кодов и когда своя интеграция окупается, а когда дешевле не начинать.

Из чего состоит API «Честного ЗНАКа»

Участник оборота сталкивается с тремя контурами. Они живут на разных адресах, требуют разных ключей и не заменяют друг друга.

Лекарственные препараты живут отдельно: у них свой контур МДЛП со своей документацией и своей схемой авторизации. Методы ГИС МТ к нему не подходят.

Третья строка таблицы обманчиво простая. Пока в карточке каталога не заполнены обязательные поля, GTIN не получить, а значит и заказывать нечего: какие атрибуты обязательны в Национальном каталоге — там же видно, какие из них придётся передавать через API.

Что подготовить до первого запроса и кто в кабинете увидит ключ

Половина «зависших» интеграций упирается не в код, а в доступы. Собрать нужно вот что:

• Организация зарегистрирована в ГИС МТ, документы оператора подписаны, нужные товарные группы подключены: метод по неподключённой группе вернёт отказ.
• УКЭП с сертификатом, добавленным в кабинет участника, — подпись нужна не человеку в браузере, а серверу.
• Криптопровайдер на стороне сервера: КриптоПро CSP или совместимое ПО, умеющее собирать открепленную подпись.
• Ключ доступа Национального каталога — он лежит в кабинете: раздел «Национальный каталог» → имя пользователя → «Профиль» → вкладка «Данные участника», оттуда копируется иконкой.
• Устройство эмиссии и ключ СУЗ, если вы собираетесь заказывать коды, а не только отчитываться об обороте.

Отдельная развилка — party_id. Официального способа получить его в кабинете нет: техподдержка «Честного ЗНАКа» прямо отправляет за ним к сервисной организации, которая подключала вашу учётную систему. Это не отговорка оператора, а признак того, что часть параметров обмена живёт у интегратора, а не у вас.

Задержка на доступах стоит денег не сама по себе, а через товар. Пока ключ не выдан и группа не подключена, коды не заказать, а продавать немаркированный товар нельзя: часть 2 статьи 15.12 КоАП грозит юрлицу штрафом до 300 000 ₽ с конфискацией партии. Поэтому доступы собирают до того, как разработчик садится за код, а не параллельно.

Как устроена авторизация

Авторизация в True API идёт только через УКЭП и состоит из трёх шагов:

1. Запрос данных для подписи. Система возвращает идентификатор запроса и случайную строку.
2. Подпись строки. Строку подписывают сертификатом участника в формате открепленной подписи и кодируют в Base64. Здесь ломается больше всего интеграций: подписывают весь ответ целиком вместо самого значения либо забывают про кодирование.
3. Обмен подписи на токен. В ответ приходит токен, дальше он идёт в заголовке Authorization: Bearer.

Токен не продлевается сам. В сообществе «Честного ЗНАКа» участники называют срок жизни в десять часов, представитель системы механику подтверждает: истёк — запрашивай заново тем же методом. Практический вывод один: обновляйте токен фоново по расписанию, а не по факту ошибки 401, иначе часть запросов будет теряться на границе срока.

Единый токен UUID: что произошло на самом деле

Здесь выдача массово отстаёт от реальности, и это стоит проговорить отдельно. В июле 2025 года «Честный ЗНАК» объявил единый токен в формате UUID и написал, что поддержка формата JWT сохраняется до марта 2026 года. Эту дату растащили по статьям и форумам, она до сих пор висит в исходном виде на официальной странице сообщества.

Дальше случилось другое. В феврале 2026 года в релизных заметках появилась формулировка, которую участники цитируют в ветке сообщества про единый токен:

Запуск использования Единого токена авторизации в формате UUID перенесён на неопределённый срок из-за необходимости обновления инфраструктуры True API, в связи с этим из описания следующих методов удалено упоминание данного токена.

Релизные заметки «Честного ЗНАКа», февраль 2026 года

То есть переход не отложен до осени и не завершён — он снят с календаря, а упоминание нового токена вычищено из описания методов. Что это значит для вас на сентябрь 2026 года: JWT остаётся рабочей схемой, срочно переписывать авторизацию не нужно. Но формат токена в коде зашивать нельзя и валидировать его как JWT тоже нельзя — когда переход вернут в план, интеграция ляжет не на запросе, а на разборе строки.

Заказ кодов через СУЗ: тридцать дней и пятьдесят копеек

Коды заказывают не в True API, а в станции управления заказами. Схема одна для всех групп:

1. Создать заказ на эмиссию с GTIN, количеством и способом выпуска.
2. Дождаться статуса «Доступен» — эмиссия занимает время, мгновенного ответа не будет.
3. Забрать коды постранично, отмечая полученные, чтобы не выгружать их повторно.
4. Подать отчёт о нанесении, если для вашей товарной группы он предусмотрен.

У забора кодов есть срок. По базе знаний «Честного ЗНАКа», коды можно получить в течение 30 календарных дней после перехода заказа в статус «Доступен», если вы забираете их сами, и в течение 365 дней, если коды получает сервис-провайдер — например типография. Не забранные в срок коды аннулируются.

Здесь и проходит граница между «мы подключили API» и «мы закрыли задачу». Заказ, статус, забор кодов, отчёт о нанесении и связка кода с товаром должны жить в одной очереди с ретраями, а не в четырёх вкладках браузера. В SelSup эта цепочка собрана в один маршрут: карточка создаётся для площадки и каталога, коды заказываются и печатаются по шаблону этикетки, статусы возвращаются к заказу. Посмотреть на своей товарной группе, как это выглядит, можно на разборе — показать заказ кодов и ввод в оборот на моих данных.

Если вы ещё не решили, нужна ли вообще интеграция, начните с ручного маршрута: как заказать код маркировки и КИЗ в кабинете — по нему видно, сколько операций придётся автоматизировать.

Версии методов: почему интеграция ломается без вашего участия

True API — это REST-подобный интерфейс, и номер версии зашит прямо в путь запроса: /api/v3/true-api/…, /api/v4/true-api/…. Когда оператор меняет логику метода несовместимо, он выпускает новую версию, а старую через какое-то время отключает.

• Отключение старых методов идёт по рассылке и по документации. В сообществе «Честного ЗНАКа» лежат письма оператора системы участникам: «за вами замечена активность по использованию методов API ГИС МТ (facade), которые будут отключены», с отсылкой к разделу «Прекращение поддержки описания API ГИС МТ».
• Дату отключения оператор называет по конкретному методу. Представитель системы в той же ветке отвечает участнику по его ИНН: сколько раз вызывался метод и когда он перестанет работать.
• Версии обновляются точечно. На один момент времени у вас в проде спокойно живут методы разных версий, и «переключиться на v4 целиком» не получится.
• Часть доработок касается одной товарной группы. Если ориентироваться на общее описание метода без привязки к группе, изменение легко пропустить.

Отсюда практика, которую стоит завести с первого дня: держите собственный реестр вызываемых методов с версией и товарной группой. Без него письмо про отключение читать бесполезно — вы не знаете, что именно у вас вызывается.

Ошибка 429: лимит частоты и как в него не упереться

Массовая выгрузка кодов или проверка большого списка КИЗ упирается в лимит вызовов. База знаний «Честного ЗНАКа» описывает механику прямо: при превышении возвращается ошибка 429 с указанием действующего значения лимита для конкретного метода, например «Нарушено ограничение на временной интервал между вызовами! Действующий интервал: 100 мс».

Важная деталь, которую пропускают: лимит считается в разрезе УКЭП и конкретного метода. Две интеграции под одной подписью делят один лимит на двоих. Если обмен с площадками и обмен с маркировкой у вас крутятся под общим сертификатом, троттлинг нужен общий, а не по сервисам.

Регистрация в ГИС МТ с 1 марта 2026 года: новая причина отказа

С 1 марта 2026 года система сверяет наличие уведомления о начале отдельных видов предпринимательской деятельности в едином реестре уведомлений. Основание — постановление Правительства от 29.12.2025 № 2192, а по мясным изделиям — постановление от 28.02.2026 № 205.

Уточнение, которое стоит внести и в наш прошлый текст, и в чужие: проверка работает при регистрации участника и товарной группы в ГИС МТ, а не на каждой операции с оборотом. Но для интеграции это всё равно новый класс отказа, не связанный с формой запроса: тело корректное, подпись валидна, а работа не начинается, потому что сведений об организации нет в реестре. Повторная отправка не поможет — нужно действие на Госуслугах.

Разбор сумм по частям статьи и по товарным группам — в отдельном материале про штрафы за отсутствие маркировки «Честный ЗНАК».

Три пути к маркировке: руками, готовый сервис, своя интеграция

Выбор здесь не про технологическую моду, а про объём операций и про то, кто будет держать это в рабочем состоянии через полгода. Учтите ещё один контур: коды уходят к покупателю вместе с УПД, а документы подписываются в ЭДО — у «Честного ЗНАКа» для этого есть бесплатный сервис ЭДО Лайт, и его тоже придётся встроить в маршрут.

Плюсы и минусы своей интеграции

• Получаете точное совпадение с вашими процессами — платите тем, что каждый нестандартный сценарий придётся описать и потом поддерживать самим.
• Получаете независимость от графика поставщика — платите обязанностью читать релизные заметки и держать реестр методов.
• Получаете полный контроль над данными кодов — платите ответственностью за их хранение: если коды нигде не сохранены, связку товара, заказа и документа после сбоя не восстановить.
• Получаете возможность выжать скорость — платите работой с лимитами: без очереди и троттлинга упрётесь в 429 на первой же массовой выгрузке.

Ручную часть, которая остаётся при любом пути, видно на экране: коды и этикетки печатаются пачкой по выбранным позициям, а не по одной карточке.

Кому своя интеграция подходит, а кому нет

Подходит

• Есть своя ERP или WMS, в которой уже живут остатки и заказы, и маркировка должна встать внутрь этого контура.
• Несколько товарных групп с разными правилами, и готовый модуль закрывает только часть из них.
• Есть разработчик, который останется — не подрядчик на один релиз, а человек, который через полгода прочитает письмо про отключение метода.
• Объём измеряется тысячами кодов в день, и цена ошибки в ручном переносе выше стоимости сопровождения.

Не подходит

• Коды вбиваются руками, а склад держится на одном человеке — интеграция не уберёт эту зависимость, она добавит к ней ещё и код.
• Учёт ведётся в Excel, и связка «товар — код — заказ» существует только в голове. Сначала нужен учёт, потом обмен.
• Товарная группа одна, позиций десятки — ручной маршрут в кабинете и массовая загрузка товаров файлом честно справляются.
• Некому дежурить: интеграция без мониторинга токена и очередей молча копит непроведённые документы.

Частые ошибки интеграции

Календарь изменений: что уже отключили и что перенесли

Этого списка нет ни у кого в выдаче, а без него непонятно, какая часть чужих инструкций ещё действует.

• Июль 2025 «Честный ЗНАК» объявляет единый токен в формате UUID и обещает поддержку JWT до марта 2026 года. Дата расходится по статьям и форумам.
• Февраль 2026 Запуск единого токена перенесён на неопределённый срок, упоминание UUID убрано из описания методов. JWT остаётся рабочей схемой.
• 1 марта 2026 При регистрации участника и товарной группы в ГИС МТ проверяется уведомление о начале деятельности в едином реестре: постановления № 2192 и № 205.
• Сентябрь 2026 Новой даты перехода на UUID нет. Формат токена в коде по-прежнему нельзя считать постоянным.

Стоит ли писать своё API

Главный аргумент против своей разработки — не бюджет первого релиза, а сопровождение. Правила товарных групп меняются несколько раз в год, методы отключают по расписанию оператора, а вопрос «кто прочитает следующее письмо оператора» решается один раз и навсегда. Если ответа нет, интеграция превратится в источник тихих отказов.

Если хочется сначала увидеть, как маршрут выглядит целиком — от карточки в каталоге до вывода из оборота, — это разбирается за один разговор на ваших товарных группах: записаться на разбор работы с маркировкой.

Что почитать дальше

• Виды и статусы кодов маркировки — чтобы понимать, какой статус вернёт метод проверки и что он означает для товара.
• Национальный каталог: зачем он продавцу — оттуда интеграция берёт GTIN и атрибуты карточек.
• Статусы карточек в «Честном ЗНАКе» — если карточка не публикуется, коды заказать не на что.
• Перемаркировка товаров — сценарий, который приходится закрывать любой интеграции: код испорчен или утерян.

Частые вопросы

Можно ли работать с API без электронной подписи

Нет. Токен True API выдаётся только после проверки подписи участника. Ключ доступа Национального каталога работает по своей схеме, но операции с оборотом без УКЭП недоступны.

Где взять x-api-key

Ключ доступа участника лежит в кабинете: «Национальный каталог» → имя пользователя → «Профиль» → вкладка «Данные участника». Видят его роли «Руководитель организации» и «Администратор». Идентификатор устройства эмиссии в СУЗ выдаётся отдельно и пользовательский токен не заменяет.

Чем True API отличается от СУЗ

True API отвечает за оборот: ввод, отгрузку, приёмку, проверку кодов и документы. СУЗ отвечает за заказ и выдачу самих кодов. Разные адреса, разные ключи, поэтому рабочая интеграция обычно ходит в оба контура.

Нужно ли срочно переходить на токен UUID

Нет. В феврале 2026 года запуск единого токена перенесён на неопределённый срок, упоминание убрано из описания методов, JWT продолжает работать. Но формат токена нельзя зашивать в код и валидировать как JWT — иначе возврат перехода в план сломает разбор строки.

Где взять документацию

Открытого Swagger у «Честного ЗНАКа» нет. Описание методов лежит в разделе «Помощь» кабинета ГИС МТ на промышленном контуре и в базе знаний кабинета «Реестр интеграторов», часть материалов — на портале docs.crpt.ru. Сторонние перепечатки устаревают быстрее, чем выходят релизы: пример с датой «март 2026» это показывает.

Можно ли не делать это руками

Можно, и это честнее, чем звучит: сама работа с «Честным ЗНАКом» никуда не денется, но перестанет быть ручной. Заказ кодов, печать этикетки, ввод в оборот и вывод собираются в один маршрут, а статусы кодов возвращаются к заказу, а не ищутся в кабинете. Что именно снимется на вашей товарной группе, видно на разборе — посмотреть маршрут кодов без ручного переноса. Если учёт ведётся в Excel и товарная группа одна, честный ответ — сначала порядок в учёте, потом обмен.

Что делать с ошибкой 429

Не повторять запрос сразу. В ответе приходит действующее значение интервала для метода, лимит считается в разрезе УКЭП и метода, поэтому нужна общая очередь на все интеграции под одним сертификатом, а не отдельная на каждый сервис. Если обмен с площадками у вас идёт под тем же сертификатом, учитывайте и его: как это устроено, разбирали в материале про интеграцию 1С с маркетплейсами.