Переход с True API v3 на v4: что проверить в интеграции

Чек-лист для тех, кто подключён к «Честному знаку» через API и не хочет, чтобы обмен данными остановился из-за отключённой версии метода

Как устроено версионирование в True API

True API — REST-подобный интерфейс, методы которого сгруппированы по товарным группам (одежда, обувь, молочная продукция, табак, БАД, шины и др.). У каждого метода есть номер версии в пути запроса, например /api/v3/true-api/product/info или /api/v4/true-api/product/info. Когда ЦРПТ меняет структуру ответа или логику метода несовместимым образом, он выпускает новую версию с обновлённым номером в URL, а не правит старую версию «на лету» [1].

Важные принципы, которые подтверждает официальная документация:

• Новая версия метода не обязательно означает, что весь API переходит на v4 — обновляются отдельные методы, и на один и тот же момент времени в проде могут одновременно работать методы v3 и v4 [1].
• Старая версия метода поддерживается для обратной совместимости ограниченное время — ориентировочно полгода, — после чего отключается [1].
• Изменения фиксируются в разделе истории изменений документации и в отдельном документе о планируемых изменениях, где по каждому методу указано, что именно добавляется или меняется [2].
• Помимо версии в URL, некоторые доработки идут точечно для конкретной товарной группы: например, изменения в методе получения информации о товаре по GTIN коснулись отдельно группы «Специализированная пищевая продукция и БАД к пище» [1].

На практике это означает, что нельзя один раз «переключиться на v4» и забыть об этом — версионирование продолжается, и цикл проверки актуальности методов должен быть постоянным процессом, а не разовым проектом.

Российская специфика

Работа с True API регулируется требованиями законодательства о маркировке товаров и подзаконными актами по конкретным товарным группам, а сама система — это государственная информационная система, доступ к которой строится не как обычный логин-пароль, а через усиленную квалифицированную электронную подпись (УКЭП).

Несколько особенностей, важных именно для российских компаний:

• Регистрация обязательна. Для работы с методами API нужен личный кабинет ГИС МТ с подключённой товарной группой — доступ к данным и операциям ограничен рамками зарегистрированной группы [1].
• Открытой Swagger-документации нет. Актуальное описание методов доступно в личном кабинете после авторизации; сторонним разработчикам и интеграторам рекомендуется запрашивать у ЦРПТ актуальную спецификацию под конкретную товарную группу перед началом работ [5].
• Есть тестовый контур (sandbox). Он функционально повторяет продакшен, но работает с ненастоящими данными, и тестирование в нём перед переходом на боевую среду — стандартная практика [5].
• Эмиссия кодов маркировки платная для большинства товарных групп, и эта плата взимается независимо от способа получения кода — через API или личный кабинет [5].
• Основной канал поддержки 1С-интеграций — обновления типовых конфигураций (например, «ГосИС»), которые подстраиваются под изменения версий методов; если интеграция построена поверх 1С, нужно параллельно следить не только за документацией ЦРПТ, но и за релизами конфигурации [3].

Как работает авторизация и обмен данными

Прежде чем разбирать конкретные различия v3 и v4, стоит зафиксировать общую механику работы с True API, потому что именно на этом этапе чаще всего спотыкаются новые интеграции.

Авторизация в True API — не логин-пароль, а двухшаговая процедура с криптографической подписью:

1. Клиент запрашивает у эндпоинта авторизации случайную строку для подписи (auth/key или аналог) [1] [10].
2. Полученная строка подписывается сертификатом УКЭП в формате PKCS#7 (открепленная подпись, Base64) [5] [11].
3. Подписанные данные отправляются на эндпоинт подтверждения подписи, в ответ приходит токен доступа (JWT), который затем передаётся в заголовке Authorization последующих запросов [1] [11].

Токен действует ограниченное время, и для серверных интеграций, работающих без участия человека, необходим механизм автоматического обновления токена по истечении срока действия [5]. Отдельно стоит учитывать, что часть операций в True API асинхронна: документ отправляется, система возвращает идентификатор, а результат обработки нужно опрашивать отдельным запросом — ожидание мгновенного ответа в синхронном стиле является частой ошибкой при проектировании интеграции [5].

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

В зависимости от масштаба бизнеса и уже используемых систем встречаются разные подходы к работе с True API:

• Готовая конфигурация 1С. Если товароучёт ведётся в 1С, обмен с «Честным знаком» обычно закрывает типовая или отраслевая конфигурация, и «переход на v4» сводится к своевременному обновлению конфигурации, а не к написанию кода [3].
• Самописная интеграция поверх стандартного HTTP-клиента. Для нестандартных систем (собственная ERP, WMS, кассовое ПО) интеграцию пишут напрямую поверх методов True API, и в этом случае ответственность за отслеживание версий методов и криптографии полностью лежит на разработчике [10] [11].
• Промежуточный сервис-адаптер. Часть компаний выносит работу с True API в отдельный микросервис или модуль, который инкапсулирует авторизацию, повторные попытки и версионирование методов, изолируя основную бизнес-систему от изменений API [12].

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

Практические этапы перехода на v4

1. Инвентаризация используемых методов. Составьте список всех эндпоинтов True API, которые вызывает интеграция, вместе с версией (v3, v4 и т. д.) и товарной группой, к которой они относятся.
2. Сверка с документацией ЦРПТ. По каждому методу из списка проверьте актуальный статус в документации и в разделе планируемых изменений: обновлена ли версия, добавлены ли новые обязательные параметры, объявлена ли дата отключения текущей версии [1] [2].
3. Проверка формата данных. Обратите внимание на изменения в структуре кодов идентификации — например, известны случаи, когда обратная совместимость методов требовала доработки обмена под формат кода с обрамляющими скобками и без них [9]. Аналогичные точечные изменения формата встречаются и в других методах.
4. Тестирование в sandbox. Разверните обновлённые вызовы в тестовом контуре и прогоните основные сценарии: получение и подпись документов, поиск по КИ, получение статусов [5].
5. Проверка обработки лимитов и ошибок. Настройте соблюдение минимального интервала между вызовами — при превышении система возвращает ошибку с кодом 429 и явным указанием на нарушение лимита частоты запросов [8]. Отдельно проверьте обработку асинхронных статусов и повторные попытки при временных сбоях.
6. Обновление токена и сертификатов. Убедитесь, что механизм обновления токена и работы с сертификатом УКЭП не завязан на устаревший метод авторизации, если он тоже подвергся изменению версии.
7. Поэтапный перевод в продакшен. Переключайте методы на новую версию не разом, а по мере готовности и тестирования каждого — особенно если часть методов у ЦРПТ ещё не имеет объявленной даты отключения старой версии.
8. Мониторинг после перехода. В течение нескольких недель после перехода отслеживайте логи на предмет ошибок именно по обновлённым методам — часть проблем проявляется не сразу, а при определённых комбинациях параметров или товарных групп.

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

Практика показывает несколько повторяющихся проблем при работе с True API и при переходе между версиями методов:

• Расчёт на публичную Swagger-документацию. Открытой спецификации нет, документация закрыта в личном кабинете, что затрудняет автоматизацию генерации клиентского кода и повышает риск ручных ошибок при чтении описания метода [5].
• Игнорирование лимитов частоты запросов. При массовой эмиссии кодов или выгрузке больших объёмов данных легко превысить допустимую интенсивность вызовов и получить временную блокировку или ошибку 429 [5] [8].
• Неверная обработка асинхронных операций. Ожидание синхронного результата там, где предусмотрен статус в процессе обработки, приводит к ложным ошибкам и дублированию запросов [5].
• Ошибки формата запроса из-за кодировки и заголовков. На форумах интеграторов встречаются случаи, когда неверная кодировка тела запроса или превышение допустимого размера заголовков (ошибка 413) блокировали обмен документами [7].
• Неучтённые изменения по конкретной товарной группе. Часть доработок API не затрагивает все товарные группы сразу — метод может измениться только для одной группы, и если интеграция ориентируется на общее описание метода без учёта товарной группы, изменение можно пропустить [1].
• Истечение токена без автообновления. Для непрерывно работающих серверных интеграций отсутствие автоматического продления токена приводит к внезапным сбоям обмена [5].

Рекомендации по выбору решения

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

Если интеграция самописная, завязана на несколько товарных групп, работает в высоконагруженном режиме (маркетплейс, крупный ритейл, производство) или уже сталкивалась со сбоями при прошлых изменениях API, целесообразно провести технический аудит текущей интеграции перед переходом: зафиксировать список используемых методов, точки отказа и зависимость от конкретных версий, а затем спланировать миграцию поэтапно с тестированием в sandbox.

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

Команда «Пятого фактора» на практике специализируется на ручной оптимизации интернет-магазинов на 1С-Битрикс — включая проблемы с обменом данными между сайтом и 1С, когда он «подвисает» или замедляет работу магазина. Если проблема с переходом на True API v4 связана именно с производительностью сайта на Битриксе во время обмена — например, синхронные вызовы API замедляют каталог, корзину или оформление заказа, — команда может изучить конкретный процесс на стороне сайта и предложить решение по этому участку.

Для остальных задач, напрямую не связанных с производительностью Битрикс-магазина — таких как разработка новой интеграции с нуля, доработка бизнес-логики обмена с ГИС МТ или техническая консультация по архитектуре — команда «Пятого фактора» может изучить задачу, оценить возможные варианты реализации и помочь с разработкой, интеграцией или технической консультацией.

Вывод

Переход с True API v3 на v4 — это не одномоментное переключение, а постоянный процесс сверки используемых методов с документацией ЦРПТ, потому что версии обновляются точечно, по методам и товарным группам, а старые версии отключаются с задержкой около полугода. Чтобы обмен данными не остановился, стоит вести собственный реестр используемых методов, регулярно проверять раздел изменений документации, тестировать обновления в sandbox и заранее закладывать в архитектуру обработку лимитов, асинхронных статусов и автообновление токена.

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

Источники

[1] docs.crpt.ru — Описание True API — https://docs.crpt.ru/gismt/True_API/

[2] docs.crpt.ru — Планируемые изменения в True API — https://docs.crpt.ru/gismt/Exchange/

[3] markirovka.ru — Методы True API. Официальный сайт сообщества маркировки «Честный знак» — https://markirovka.ru/community/developers/metody-true-api

[4] scribd.com — True API (архив истории версий документации) — https://ru.scribd.com/document/510383173/TRUE-API

[5] getmark.ru — True API Честный знак: подключение и работа с маркировкой — https://getmark.ru/blog/o-markirovke/true-api-chestnij-znak-podkluchenie-i-rabota-s-markirovkoj/

[6] infostart.ru — Запрос кодов маркировки товаров через API Честный знак по заданным фильтрам — https://infostart.ru/1c/tools/1923573/

[7] forum.infostart.ru — Интеграция 1С 8.3 и Честный Знак через API — https://forum.infostart.ru/forum15/topic280921/

[8] markirovka.ru — Ошибка 429: нарушено ограничение на временной интервал между вызовами — https://markirovka.ru/knowledge/lekarstva/api-mdlp/pri-otpravke-zaprosov-po-api-v-otvet-prikhodit-oshibka-429-narusheno-ogranichenie-na-vremennoy-interval-mezhdu-vyzovami-slishkom-mnogo-zaprosov-za-korotkoe-vremya

[9] olegon.ru — Как работать с API Честного Знака? (обсуждение форматов КИ и обратной совместимости) — https://olegon.ru/showthread.php?t=38701&page=9

[10] github.com — kilylabs/true-api-php-demo — https://github.com/kilylabs/true-api-php-demo

[11] help.crpt-turon.uz — НИС МПТ: API — Токен авторизации TRUE-API — https://help.crpt-turon.uz/hc/ru/articles/13197686595857

[12] totalcrm.ru — Автоматизация «Честного знака»: API, статусы, остатки и контроль без ручной рутины — https://totalcrm.ru/blog/2026/03/avtomatizaciya-%C2%ABchestnogo-znaka%C2%BB-api-statusy-ostatki-i-kontrol-bez-ruchnoj-rutiny_236

[13] 5factor.ru — официальный сайт компании — https://5factor.ru/