Честный знак True API: руководство по получению и использованию для бизнеса

Узнайте, как получить ключ Честного знака True API, быстро интегрировать его в 1С и ERP‑системы и применять в практических сценариях для контроля и автоматизации бизнеса.

Честный знак True API – что это и какие возможности дает

Что представляет собой True API

True API – это набор REST‑интерфейсов, позволяющих бизнесу получать и отправлять данные в систему «Честный знак» в режиме реального времени. Через API можно проверять подлинность маркировки, получать информацию о статусе продукции, фиксировать операции отгрузки и возврата, а также формировать отчёты для регуляторов. Всё это происходит без необходимости открывать веб‑интерфейс, что упрощает автоматизацию процессов в ERP, CRM и в облачных платформах.

Ключевые возможности

• Проверка кода маркировки в один клик – быстрый ответ «подлинно/подделка».
• Получение полного пути движения товара (от производителя до конечного потребителя).
• Регистрация операций отгрузки, приемки, возврата и утилизации.
• Формирование и загрузка QR‑кодов в продукцию напрямую из системы.
• Поддержка массовой загрузки данных (батч‑запросы до 10 000 записей).

Мобильная автоматизация склада

Узнать больше

Технические нюансы

API построено на протоколе HTTPS и использует формат JSON для запросов и ответов. Для аутентификации применяется OAuth 2.0 с клиентскими идентификаторами, полученными в личном кабинете «Честного знака». Каждый запрос ограничен по времени выполнения (5 сек) и количеству запросов в минуту (150 req/min), что позволяет выдерживать нагрузку даже у крупных ритейлеров.

Пример простого запроса на проверку кода:

GET https://api.chek.nalog.ru/v1/verify?code=1234567890AB Headers: Authorization: Bearer <access_token>

Ответ содержит поле status (valid/invalid) и дополнительные сведения о товаре.

Преимущества интеграции для бизнеса

Внедрение True API устраняет ручную проверку маркировки, снижает риск попадания подделок в ассортимент и ускоряет процесс возврата товаров. Автоматический обмен данными с государственной системой обеспечивает полное соответствие требованиям регулятора, а также даёт возможность формировать аналитические отчёты о движении продукции, что повышает эффективность цепочек поставок.

Сравнительная таблица тарифов

Как начать работу

Для подключения к True API необходимо: 1) зарегистрировать компанию в личном кабинете «Честного знака», 2) получить клиентский ID и секрет, 3) настроить OAuth‑авторизацию в своей системе, 4) протестировать запросы в sandbox‑окружении, 5) перейти в продакшн после подтверждения соответствия техническим требованиям. После этого все операции с маркировкой могут быть выполнены автоматически, без вмешательства персонала.

Как оформить и получить API‑ключ Честного знака

Подготовка к заявке

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

• Регистрация в системе Честного знака (лицевой счёт или ИНН).
• Подтверждённый электронный адрес и телефон, привязанные к учётной записи.
• Техническое описание интеграции: какие сервисы будут использоваться, примерный объём запросов и формат данных.

Наличие этой информации ускорит процесс рассмотрения заявки и позволит избежать возвратов запросов на доработку.

Пошаговая процедура оформления

Процесс получения ключа состоит из нескольких простых шагов, которые обычно выполняются в личном кабинете партнёра.

1. Войдите в Личный кабинет и выберите раздел «API и интеграции».
2. Нажмите кнопку «Запросить API‑ключ» и заполните форму, указав название проекта, цель использования и ожидаемую нагрузку.
3. Прикрепите файл с техническим описанием (формат — PDF, DOCX) и подтвердите согласие с условиями использования API.
4. Отправьте заявку. Система автоматически создаёт тикет в службе поддержки, где вы сможете отслеживать статус.

После отправки заявки обычно требуется 1–3 рабочих дня на проверку. Если всё в порядке, вам будет отправлен электронный шаблон с инструкциями по активации ключа.

Проверка и активация ключа

Получив письмо, откройте вложенный файл — в нём будет ваш уникальный API‑KEY и ссылка на тестовый эндпоинт. Для начала работы выполните простую проверку:

curl -X GET “https://api.chekznak.com/v1/ping" -H “Authorization: Bearer YOUR_API_KEY”

Если ответ содержит {"status":"ok"}, ключ активирован и готов к использованию в продакшн‑окружении. В случае ошибки проверьте:

• Корректность формата ключа (без пробелов и скрытых символов).
• Соответствие указанных в заявке параметров (граничные значения нагрузки).
• Настройки IP‑фильтрации, если они были заданы в кабинете.

Типичные сценарии применения API

Ниже приведён короткий пример интеграции, который может пригодиться для большинства бизнес‑процессов.

POST https://api.chekznak.com/v1/labels/verify Headers: Authorization: Bearer YOUR_API_KEY Content-Type: application/json

Body: { “sku”: “12345678”, “qr_code”: “https://chekznak.com/qr/abcdef123456" }

Ответ сервера даст информацию о статусе маркировки, дате выпуска и оригинальности продукта. Такой запрос удобно внедрять в системы ERP, CRM или мобильные приложения для сканирования.

Таблица статусов заявки

Визуальная схема процесса

Полезные рекомендации

Чтобы интеграция работала стабильно, придерживайтесь следующих правил:

• Храните API‑KEY в безопасном месте (секреты в vault, переменные окружения).
• Ограничьте IP‑адреса, с которых допускаются запросы, если ваш сервис работает из фиксированных дата‑центров.
• Регулярно проверяйте лимиты запросов и обновляйте план доступа при росте объёма продаж.

Настройка и интеграция True API в 1С и ERP‑системы

Подготовка среды 1С

Перед тем как приступить к работе с True API, требуется убедиться, что конфигурация 1С поддерживает работу с внешними HTTP‑сервисами. В последних версиях платформы уже есть встроенный механизм Обработки HTTP‑запросов, но для стабильной работы рекомендуется выполнить несколько простых шагов:

• Включить в параметрах сервера опцию Разрешить внешние запросы и задать таймаут не менее 30 секунд.
• Создать отдельный каталог СервисныеОбъекты\TrueAPI и разместить в нём общие модули для аутентификации и формирования подписи.
• Настроить права доступа: пользователям, которые будут генерировать коды, нужен доступ к СервисныеОбъекты и к объектам хранения данных о маркировке.

Настройка методов True API

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

Пример функции, генерирующей коды, выглядит так:

Функция GenerateТTrueCode(productId, qty) request = Новый HTTPЗапрос(“https://api.true.ru/v1/codes/generate"); request.УстановитьМетод(“POST”); request.УстановитьТелоJSON(Новый Структура( “productId,quantity,expirationDate”, productId, qty, ТекущаяДата() + 365)); response = request.ПолучитьОтвет(); Если response.КодСостояния = 200 Тогда Возврат response.ПрочитатьТелоКакJSON(); Иначе ВызватьИсключение(“Ошибка генерации кода: " + response.ПолучитьТекст()); КонецЕсли; КонецФункции;

Интеграция с ERP‑системами

В ERP‑среде процесс обычно выглядит как цепочка: поступление заказа → подготовка отгрузки → генерация маркировочных кодов → передача кода в транспортную этикетку. Для упрощения интеграции рекомендуется использовать «триггерные» обработчики, которые автоматически вызываются при изменении статуса документа.

Типовая схема взаимодействия:

1. При подтверждении отгрузки происходит вызов GenerateCode и сохраняются полученные коды в табличную часть документа.
2. Коды передаются в модуль печати этикеток, где происходит их визуализация (штрих‑коды, QR‑коды).
3. После печати вызывается ReportUsage с параметром operationType = “PRINT”, что фиксирует факт использования кода в системе «Честный знак».

Обработка ошибок и логирование

Сервис True API отвечает кодами HTTP и детальными сообщениями об ошибках. Чтобы быстро находить проблемы, следует вести централизованный журнал запросов. В 1С удобно использовать объект ЖурналРегистрации с уровнем «Ошибка» и «Инфо». Пример записи в журнал:

Журнал = ЖурналыРегистрации.ПолучитьЖурнал(“TrueAPI”); Попытка // вызов метода API Исключение Журнал.Записать(“Ошибка при вызове " + methodName + “: " + ОписаниеОшибки, УровеньЖурнала.Ошибка); КонецПопытки;

Ключевые рекомендации:

• Всегда проверяйте КодСостояния ответа – 200 – успех, 4xx – ошибка клиента, 5xx – сервис недоступен.
• При повторных попытках используйте экспоненциальную задержку (например, 1 сек → 2 сек → 4 сек).
• Храните токен доступа в зашифрованном виде и обновляйте его по расписанию, чтобы избегать прерывания интеграции.

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

Ниже показан скриншот, где в отчете «Отгрузка» отображаются сгенерированные QR‑коды рядом с каждой строкой товара.

Практические сценарии использования True API

Интеграция в e‑commerce

Для онлайн‑ритейлеров проверка подлинности товаров в момент оформления заказа становится конкурентным преимуществом. Через True API можно автоматически запрашивать статус маркировки по штрих‑коду или QR‑коду, получая ответ «запрещено», «разрешено» или «требует подтверждения». Если товар отмечен как поддельный, система мгновенно блокирует покупку и предлагает клиенту альтернативный вариант, что сохраняет репутацию магазина и снижает возвраты.

Контроль качества продукции на производстве

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

Мобильные приложения для конечных потребителей

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

Автоматизация отчетности и взаимодействие с контролирующими органами

Компании, обязанные сдавать ежемесячные отчёты о реализованных маркированных товарах, могут сформировать их автоматически. True API предоставляет данные о всех проверенных кодах, их статусах и времени проверки. На основе этих данных формируется CSV‑файл, который сразу же передаётся в систему контроля, исключая ручной ввод и ошибки.

Пример использования API‑методов

Ключевые преимущества внедрения True API

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

Видео по теме

Полезный разбор по теме — запись с канала Клеверенс:

Полезные сервисы и обновления

Мобильная автоматизация склада

Узнать больше

Маркировка «Честный знак»

Узнать больше

Розничная торговля и инвентаризация

Узнать больше

Вопросы и ответы

Что такое True API и какие задачи оно решает?

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

Как оформить и получить API‑ключ «Честного знака»?

Необходимо зарегистрировать компанию в личном кабинете, открыть раздел «API и интеграции», заполнить форму заявки (название проекта, цель, нагрузка), загрузить техническое описание и согласиться с условиями. После проверки (1‑3 дня) ключ будет отправлен на указанный email.

Какие ограничения по запросам действуют у True API?

Один запрос может выполнять­ся не более 5 сек., лимит – 150 запросов в минуту. При массовой загрузке поддерживаются батч‑запросы до 10 000 записей.

Как интегрировать True API в 1С?

В 1С включаем внешние запросы, создаём общий модуль с функциями аутентификации, реализуем методы (RegisterProduct, GenerateCode, CheckStatus, ReportUsage) через HTTPЗапрос, обрабатываем коды ответа и ведём журнал запросов.

Какие тарифы доступны для использования True API?

Тариф Basic — 100 000 запросов в месяц, бесплатно; Standard — 500 000 запросов, полный набор методов, стоимость по согласованию; Premium — безлимит, премиум‑поддержка, SLA 99,9 %, цена по согласованию.

Как проверять статус маркировки через API?

Отправьте GET‑запрос к /v1/verification (или /v1/codes/status) с параметром code. Ответ содержит поле status — valid/invalid и дополнительные сведения о товаре.

Можно ли использовать True API в мобильных приложениях для потребителей?

Да. Приложения‑сканеры могут отправлять код в API и получать мгновенный ответ о подлинности (зелёный — подтверждено, красный — подделка), что повышает доверие к бренду.

Какие рекомендации по безопасному хранению API‑KEY?

Храните ключ в защищённом хранилище (Vault, переменные окружения), ограничьте IP‑адреса, с которых разрешены запросы, шифруйте значение и регулярно обновляйте токен доступа.