True API «Честного знака»: авторизация, документы, статусы и ошибки

Что такое True API простыми словами

Для работы с True API нужны доступ к ГИС МТ, УКЭП и приложение с разрешениями на нужные методы. После авторизации система отправляет документы и отдельно проверяет результат их обработки.

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

True API vs API СУЗ — в чём разница

Здесь часто возникает путаница, потому что оба интерфейса относятся к «Честному знаку», но решают разные задачи.

• True API (ГИС МТ) — отвечает за оборот уже выпущенных кодов: статусы, документы о вводе в оборот, агрегация, отгрузки, приёмки, история кода.
• API СУЗ (Станция управления заказами) — отдельный интерфейс, через который участник оборота заказывает эмиссию новых кодов маркировки у оператора (ЦРПТ) и получает их для нанесения на продукцию: СУЗ передаёт запрос в ГИС МТ через API, получает коды от оператора ЦРПТ и передаёт их обратно в учётную систему для печати и учёта.

Оба интерфейса дополняют друг друга, а не заменяют: API СУЗ не подменяет собой API ГИС МТ, а расширяет процесс управления маркированным товаром, делая его более гибким. При проектировании интеграции нужно закладывать оба контура — иначе бизнес получит только половину процесса (например, сможет отчитываться об обороте, но не сможет автоматически заказывать коды).

Как устроена авторизация по УКЭП

Самое частое заблуждение у тех, кто впервые сталкивается с True API, — ожидание обычной авторизации по логину и паролю или статичному API-ключу. На практике используется двухэтапная схема с криптографической подписью запроса.

Пошаговая схема получения токена

1. Запрос случайной строки. Клиент обращается к методу получения ключа аутентификации (.../true-api/auth/key), сервер в ответ присылает уникальный идентификатор запроса (uuid) и случайную строку данных (data)— это подтверждают опубликованные примеры реализации на PHP с использованием расширения CAdES-PHP и КриптоПро SDK.
2. Подпись строки. Полученную строку нужно подписать усиленной квалифицированной электронной подписью в формате открепленной подписи PKCS#7 (CAdES-BES), закодированной в Base64. Для этого на сервере, где выполняется интеграция, должен быть установлен криптопровайдер — например, КриптоПро CSP.
3. Обмен подписи на токен. Полученная подпись вместе с идентификатором uuid отправляется на метод авторизации (.../auth/simpleSignIn или .../auth/cert). В ответ система выдаёт токен доступа, который затем передаётся в заголовке Authorization: Bearer <токен> во всех последующих запросах к методам True API.

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

С 2025–2026 годов система дополнительно предлагает так называемый «единый токен» в формате uuid как альтернативу токену JWT— оба формата токена можно использовать в параметре Authorization: Bearer при вызове методов True API, а поддержка формата JWT сохраняется до марта 2026 года, в течение которого интеграции нужно доработать под новый формат. Это значит, что действующие интеграции нужно проверять на актуальность используемого формата авторизации отдельно.

Российская специфика: законодательство и требования

Маркировка в России — не добровольная инициатива площадки, а требование федерального законодательства. Базовый акт — Федеральный закон от 31.12.2017 № 487-ФЗ, который внёс изменения в закон «Об основах государственного регулирования торговой деятельности» и закрепил за правительством полномочия определять перечень товаров, подлежащих обязательной маркировке. По каждой товарной группе (обувь, лекарства, табак, молочная продукция, БАДы, велосипеды, безалкогольное пиво и другие) правительство принимает отдельное постановление с конкретными правилами и сроками.

Ряд практических моментов, характерных именно для российского контекста:

• УКЭП обязательна. Без действующей усиленной квалифицированной электронной подписи ни регистрация в системе, ни авторизация по API невозможны— УКЭП нужна для регистрации в системе, подписания документов и работы с кодами маркировки.
• Плата за коды. Постановлением Правительства РФ от 08.05.2019 № 577 установлен размер платы за предоставление кодов маркировки — 50 копеек без НДС за один код, с исключением для жизненно важных лекарственных препаратов дешевле 20 рублей.
• Требования к кассовому оборудованию. С конца 2025 года вводится обязательная установка технических средств получения информации о товаре (ТС ПИОТ) на кассовых зонах розницы— это требование установлено постановлениями Правительства РФ № 515 и № 303, а ТС ПИоТ представляют собой программные и программно-аппаратные решения, работающие в связке с ККТ для сбора и передачи данных о маркированных товарах.
• Особые правила для импорта. Для импортёров нанесение кодов маркировки должно происходить до подачи таможенной декларации, а не после выпуска товара, при этом статья 15.12 КоАП предусматривает обязательную конфискацию предмета правонарушения.
• Разрешительный режим по товарным группам. Отдельные категории (например, корма для животных) переходят на онлайн- и офлайн-проверки в рамках разрешительного режима, что напрямую влияет на логику работы кассового и учётного ПО.

Варианты реализации интеграции

У компании обычно есть три реалистичных пути.

1. Работа через личный кабинет вручную. Подходит для очень небольших объёмов — как ориентир в отраслевых материалах встречается порог около нескольких десятков маркированных единиц в день, при котором ручная обработка в личном кабинете ещё остаётся приемлемой, а API оправдывает себя при дальнейшем масштабировании бизнеса.

2. Готовое отраслевое решение. Модули для 1С, специализированные конфигурации для касс и складского учёта — типовой путь для среднего бизнеса, где не требуется писать интеграцию с нуля, а достаточно настроить готовый модуль обмена, для чего в личном кабинете нужно сгенерировать токен доступа к API в разделе управления доступом к API.

3. Индивидуальная интеграция по API. Прямое подключение к True API и API СУЗ из собственной учётной или ERP-системы — вариант для компаний с нестандартными процессами, высокой нагрузкой (розничные сети, производство, дистрибуция) или требованием работать в двух режимах одновременно — онлайн через API и офлайн через локальный модуль на случай обрыва связи, с поддержкой агрегации и интеграцией с ЭДО для автоматической приёмки УПД.

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

Практические этапы подключения

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

1. Регистрация участника оборота на сайте «Честного знака» и подключение нужной товарной группы в личном кабинете ГИС МТ.
2. Получение и установка УКЭП, а также криптопровайдера (чаще всего КриптоПро CSP) на сервере, откуда будет выполняться авторизация.
3. Генерация доступа к API в личном кабинете — идентификаторов и, при необходимости, регистрация учётной системы, после которой в окне регистрации отображаются название учётной системы, её идентификатор, идентификатор клиента и секретный ключ, необходимые для формирования запросов аутентификации.
4. Тестирование на демонстрационном (тестовом) контуре перед выходом в промышленную среду — это позволяет отработать сценарии эмиссии, ввода в оборот и агрегации без реальных последствий и штрафов, поскольку тестовый контур полностью повторяет боевую систему, но изолирован от реальных данных: коды в нём бесплатны, а ошибки не приводят к штрафам.
5. Реализация обмена данными: получение токена, отправка и получение документов, обработка ответов и ошибок, синхронизация статусов кодов.
6. Настройка автоматического обновления токена и мониторинга — без этого механизма интеграция будет «отваливаться» каждые несколько часов.
7. Переход в промышленный контур и регулярный мониторинг версий документации True API — она обновляется, а часть методов планово выводится из поддержки.

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

Ограничения, ошибки и риски

• Лимит запросов. Количество запросов в секунду не должно превышать 50 от одного участника оборота товаров — при нарушении этого требования участник может быть заблокирован. Это критично для интеграций с высокой частотой обращений: без очередей и троттлинга на своей стороне легко упереться в лимит.
• Ограниченный срок жизни токена. Как отмечалось выше, токен действует около 10 часов — интеграция должна сама следить за истечением срока и обновлять токен, иначе документы просто перестанут отправляться.
• Закрытая и часто меняющаяся документация. Официального открытого API-портала с актуальной спецификацией нет: описание нужно искать в личном кабинете или у интегратора, а версии документа регулярно обновляются, из-за чего интеграции, написанные «один раз и навсегда», со временем начинают конфликтовать с новыми правилами.
• Плановое отключение старых методов. ЦРПТ периодически выводит из поддержки устаревшие методы API в пользу новых версий — интеграцию нужно поддерживать в актуальном состоянии, иначе в какой-то момент она перестанет работать без предупреждения на уровне бизнес-процесса.
• Штрафы за нарушение правил оборота. Ошибки в интеграции — не только техническая, но и юридическая проблема: нарушение порядка маркировки может повлечь ответственность по ст. 15.12 и 15.12.1 КоАП РФ, вплоть до конфискации товара.
• Требования к криптосредствам. Не любая электронная подпись подходит для автоматизации через API — например, некоторые облачные подписи плохо совместимы с автоматическими серверными сценариями, это нужно проверять заранее, а не постфактум на этапе продакшена.

Как выбрать решение

Если объём операций небольшой и стабилен — вероятно, достаточно личного кабинета или готового модуля для учётной системы. Если объём растёт, есть несколько торговых точек или производственных линий, требуется работа в офлайн-режиме при потере связи или нужна интеграция сразу с несколькими системами (ЭДО, кассы, склад, ERP) — имеет смысл рассматривать индивидуальную интеграцию по API. Ключевые вопросы, на которые стоит ответить до начала разработки: какая товарная группа подключается, какие операции нужны (только чтение статусов или полный цикл — заказ, ввод в оборот, агрегация, отгрузка), кто будет поддерживать интеграцию после запуска и как будет организовано обновление токена и мониторинг ошибок. Для операций с транспортной упаковкой отдельно настраивается модуль агрегации кодов маркировки и SSCC.

Точных сроков и стоимости интеграции заранее назвать нельзя — они зависят от количества товарных групп, состояния существующей учётной системы, необходимости доработки кассового ПО под ТС ПИОТ и объёма тестирования на демонстрационном контуре.

Как может помочь «Пятый фактор»

Основная сложность подключения True API обычно не в самом факте вызова API, а в сопутствующих задачах: настройке криптографии для автоматической подписи запросов, обработке ошибок и кодов статусов, сопоставлении данных между учётной системой и ГИС МТ, а также в поддержании интеграции актуальной по мере обновления документации и вывода старых методов из эксплуатации. Команда «Пятого фактора» может изучить текущий процесс учёта маркированных товаров, оценить, достаточно ли готового решения или нужна индивидуальная разработка, и помочь с архитектурой обмена данными, интеграцией с 1С или другой учётной системой, а также с настройкой автоматического обновления токенов и мониторинга ошибок.

Заключение

True API — рабочий, но не самый прозрачный инструмент: закрытая документация, обязательная криптографическая авторизация через УКЭП и жёсткие лимиты запросов задают высокий порог входа для тех, кто подключается впервые. При этом технология полностью решает задачу автоматизации оборота маркированных товаров — если правильно спроектировать обмен данными, протестировать его на демонстрационном контуре и заложить автоматическое обновление токена. Чтобы обсудить задачу или получить консультацию, свяжитесь с командой «Пятого фактора» любым удобным способом.

Источники

1. docs.crpt.ru — «Описание True API» — https://docs.crpt.ru/gismt/True_API/
2. Сообщество «Честный знак» — «Документация АПИ (СУЗ, True API)» — https://markirovka.ru/community/transfer-EDI/dokumentatsiya-api-suz-true-api-
3. Сообщество «Честный знак» — «Где взять описание true api?» — https://markirovka.ru/community/rezhim-proverok-na-kassakh/gde-vzyat-opisanie-true-api
4. Сообщество «Честный знак» — «На сайте Честный Знак нет документации по API» — https://markirovka.ru/knowledge/lekarstva/api-mdlp/na-sayte-chestnyy-znak-net-dokumentatsii-po-api
5. GetMark — «True API Честный знак: подключение и работа с маркировкой» — https://getmark.ru/blog/o-markirovke/true-api-chestnij-znak-podkluchenie-i-rabota-s-markirovkoj/
6. 1AB — «Интеграция 1С с системой маркировки «Честный Знак»» — https://www.1ab.ru/blog/detail/integratsiya-1s-s-sistemoy-markirovki-chestnyy-znak/
7. TotalCRM — «API Честного ЗНАКА: как подключиться к ЭДО Лайт, ГИС МТ и Национальному каталогу» — https://totalcrm.ru/blog/2025/11/api-chestnogo-znaka-kak-podklyuchitsya-k-edo-lajt-gis-mt-i-nacionalnomu-katalogu_60
8. ASP-News — ««Честный знак»: гайд как выбрать интеграцию в 2026 году» — https://asp-news.ru/marking/интеграция-честный-знак-схема-работы-api/
9. Truemark — «Маркировка Честный ЗНАК 2026: товары, коды, сроки» — https://truemark.ru/markirovka-chestnyj-znak/
10. Astral — «Как работать с ГИС МТ «Честный ЗНАК»: инструкция и требования 2026» — https://astral.ru/aj/elem/kak-rabotat-s-gis-mt-chestnyy-znak/
11. Docs.domino.ru — «Маркировка ГИС МТ "Честный знак". Проверка с использованием ТС ПИОТ» — https://docs.domino.ru/books/markirovka-gis-mt-chestnyy-znak-proverka-s-ispolzovaniem-ts-piot/export/html
12. Бернев А.Э. — «Маркировка «Честный знак» при импорте: режим» — https://bernev.com/publications/chestnyi-znak-pri-importe/
13. GetMark — «Песочница Честный знак: тестовый контур, регистрация, настройка» — https://getmark.ru/blog/o-markirovke/pesochniza-chestnij-znak-testovij-kontur/
14. GitHub / kilylabs — «true-api-php-demo» — https://github.com/kilylabs/true-api-php-demo
15. Сообщество «Честный знак» — «Единый токен uuid при авторизации по сертификату с МЧД» — https://markirovka.ru/community/developers/edinyy-token-uuid-pri-avtorizatsii-po-sertifikatu-s-mchd
16. Retail.ru — «Процесс получения кодов маркировки защитят от злоумышленников» — https://www.retail.ru/news/protsess-polucheniya-kodov-markirovki-zashchityat-ot-zloumyshlennikov-3-marta-2021-202395/
17. Инфостарт — «ЦРПТ отключит доступ к API маркировки по статичным токенам» — https://infostart.ru/journal/news/uchet-nalogi-pravo/tsrpt-otklyuchit-dostup-k-api-markirovki-po-statichnym-tokenam_1499353/
18. Cleverence — «API СУЗ и API ГИС МТ: автоматизация маркировки и снижение рисков» — https://www.cleverence.ru/articles/markirovka-tovarov/-api-suz-i-api-gis-mt-kak-avtomatizirovat-markirovku-i-snizit-operatsionnye-riski/
19. Cleverence — «СУЗ Честный Знак в 1С: настройка обмена и заказ кодов маркировки» — https://www.cleverence.ru/articles/markirovka-tovarov/-suz-chestnyy-znak-kak-nastroit-obmen-s-suz-v-1s-i-zapustit-zakaz-kodov-markirovki/
20. Честный ЗНАК (официальный сайт) — «Новости» — https://xn--80ajghhoc2aj1c8b.xn--p1ai/info/releasenotes/chto-novogo-v-sisteme-s-02-06-2025-po-06-06-2025/
21. Сообщество «Честный знак» — «Как получить доступ к апи честного знака, для личного использования» — https://markirovka.ru/community/ask-expert/kak-poluchit-dostup-k-api-chestnogo-znaka-dlya-lichnogo-ispolzovaniya