При интеграции учетных систем 1С с ГИС МТ (Честный ЗНАК) разработчики часто сталкиваются с ситуацией, когда данные в личном кабинете (веб-интерфейсе) отображаются корректно, но соответствующий запрос через API warehouse/balance возвращает пустой массив balances. Это создает сложности при сверке остатков и автоматизации объемно-сортового учета (ОСУ), особенно для таких товарных групп, как молочная продукция и упакованная вода. В данной статье мы подробно разберем основные причины этой проблемы, проанализируем технические нюансы работы с True API и найдем решение, которое поможет вам корректно получать данные.
Одной из самых распространенных ошибок, как выяснилось в ходе практики, является некорректная передача параметров пагинации. Рассмотрим подробнее, как работает механизм страниц в API Честного ЗНАКА. В большинстве современных систем нумерация страниц может начинаться как с 1, так и с 0. В документации ГИС МТ четко указано (хотя это легко пропустить), что параметр pageNumber должен начинаться с 0.
Если ваша система запрашивает данные, начиная с pageNumber = 1, а количество остатков в организации невелико (помещается на одну страницу), API воспримет ваш запрос как попытку получить вторую страницу данных. Поскольку данных для второй страницы нет, система вернет пустой массив вместо ошибки, что и вводит разработчика в заблуждение. Проанализируем пример формирования параметров запроса в 1С:
// Пример формирования параметров для HTTP-запроса
ПараметрыЗапроса = Новый Структура;
ПараметрыЗапроса.Вставить("pageNumber", 0); // Важно: начинаем с нуля!
ПараметрыЗапроса.Вставить("limit", 100); // Количество записей на страницу
Проверьте ваш код на наличие инкремента страницы. Если вы используете циклы для обхода всех страниц остатков, убедитесь, что первая итерация передает именно 0.
Метод warehouse/balance требует обязательного указания кода товарной группы. Для каждой группы существуют свои правила ведения баланса. Выясним причину, по которой данные могут отсутствовать для определенных категорий:
Проанализируем ситуацию: если запрос по одной организации (где только молоко) работает, а по другой (где молоко + пиво) — нет, следует проверить, передаете ли вы фильтр по конкретной группе. Если фильтр не указан, API может вести себя нестабильно или возвращать пустой результат из-за смешения типов учета.
Зачастую разработчики забывают, что остатки в Честном ЗНАКЕ привязаны к конкретным идентификаторам. Метод получения баланса работает в контексте виртуального склада. Рассмотрим, на что нужно обратить внимание:
Даже при наличии валидного токена авторизации, у него могут быть ограниченные права. Разберем шаги для проверки:
В разделе «Администрирование» личного кабинета ГИС МТ необходимо проверить права доступа для используемого сертификата. Бывают случаи, когда после добавления новых товарных групп права на использование API для старых групп нужно «переподтвердить». Выясним, имеет ли ваш API-ключ доступ к методам получения баланса конкретно для группы milk или water.
Важно учитывать, что ГИС МТ — это высоконагруженная система, и данные между различными подсистемами (документооборот и баланс) обновляются не мгновенно. Рассмотрим ситуацию, когда метод warehouse/operations видит входящий документ, а warehouse/balance еще нет.
Latency (задержка) может составлять от нескольких минут до нескольких часов. Если вы только что подписали УПД, не ожидайте моментального появления товара на балансе через API. Рекомендуется реализовать в 1С механизм отложенного запроса остатков с повторными попытками через определенный интервал времени.
Посмотрим на пример кода, который выполняет запрос к API для получения баланса с учетом правильной пагинации и заголовков. Это поможет вам структурировать свой запрос правильно.
Функция ПолучитьОстаткиЧЗ(Токен, КодГруппы)
Соединение = Новый HTTPСоединение("markirovka.crpt.ru", 443, , , , , Новый ЗащищенноеСоединениеOpenSSL());
// Формируем путь с параметрами (pageNumber=0!)
ПутьЗапроса = "/api/v4/true-api/warehouse/balance?productGroup=" + КодГруппы + "&pageNumber=0&limit=100";
Запрос = Новый HTTPЗапрос(ПутьЗапроса);
Запрос.Заголовки.Вставить("Authorization", "Bearer " + Токен);
Запрос.Заголовки.Вставить("Content-Type", "application/json");
Попытка
Ответ = Соединение.Получить(Запрос);
Если Ответ.КодСостояния = 200 Тогда
// Читаем JSON и анализируем массив balances
Возврат Ответ.ПолучитьТелоКакСтроку();
Иначе
Сообщить("Ошибка запроса: " + Ответ.КодСостояния);
Возврат Неопределено;
КонецЕсли;
Исключение
Сообщить("Ошибка связи: " + ОписаниеОшибки());
Возврат Неопределено;
КонецПопытки;
КонецФункции
Для успешного получения баланса через API Честного ЗНАКА необходимо выполнить следующие шаги:
pageNumber начинается с 0.productGroup в параметрах запроса.warehouse/operations: если они обработаны с ошибками, товар на баланс не встанет.Соблюдение этих правил позволит избежать получения пустых массивов в ответах API и обеспечит надежную работу вашей интеграции с системой маркировки.