01 · Обзор
Один файл — актуальная номенклатура
Каталог предназначен для автоматической загрузки данных HALLA в сайты, проектные системы, конфигураторы и внутренние базы партнёров.
Каждая успешно опубликованная версия — это полный снимок текущего публичного каталога. Его не нужно объединять с предыдущим файлом: новая версия полностью заменяет старую.
Если серия или продукт отсутствуют в новом успешно проверенном снимке, их следует считать больше не опубликованными в партнёрском каталоге.
Публичный доступ
Без токенов, логинов и IP-ограничений
Безопасный контракт
Только разрешённые публичные поля
Стабильная версия
Совместимые дополнения внутри v1
02 · Ресурсы
Что использовать
Все адреса постоянные. Для регулярного обмена используйте сжатую версию, а XSD — для автоматической проверки структуры.
03 · Состав данных
Только публичная часть каталога
Структура не повторяет внутреннюю базу HALLA. Перед публикацией данные проходят отдельный нормализующий слой.
Передаётся
- Серии
- Название, публичный ключ, описание, категории и URL
- Продукты
- Артикул, название, серия и публичные характеристики
- Характеристики
- Ключ, название, значение, тип и единица измерения
- Изображения
- Публичные URL, назначение и альтернативный текст
- Документы
- Тип, название, формат и публичный URL
Не входит в публичный контракт
Без цен и складских остатков
- цены, остатки и доступность продукции
- внутренние идентификаторы ERP и базы данных
- служебные статусы, даты и импортные метаданные
- административные настройки и сведения о хранении файлов
- поля, которые не входят в публичное представление каталога
Новые внутренние поля по умолчанию остаются закрытыми и не появляются в XML автоматически.
04 · Правила контракта
Как интерпретировать каталог
Полный снимок каталога
Новый успешно проверенный файл целиком заменяет предыдущий. Это не журнал изменений и не набор частичных обновлений.
Стабильные идентификаторы
Канонический идентификатор продукта — article. Серии и категории связаны стабильными публичными ключами.
Файлы по ссылкам
Изображения и документы передаются как публичные URL. Бинарные файлы не встраиваются внутрь XML.
05 · Синхронизация
Надёжная загрузка за пять шагов
Интеграция должна сохранять последнюю корректную версию, даже если очередное обновление временно недоступно или не проходит проверку.
- 01СкачайтеДля регулярной синхронизации используйте catalog-v1.xml.gz и временный файл.
- 02РаспакуйтеПроверьте целостность gzip и корректность XML в кодировке UTF-8.
- 03ПроверьтеВалидируйте структуру по XSD и сравните фактические количества с атрибутами корневого элемента.
- 04ЗаменитеТолько после успешной проверки атомарно замените предыдущий снимок новым.
- 05Сохраните резервПри ошибке оставьте в работе последнюю успешно проверенную версию.
Не чаще одного раза в 8 часов
Более частый опрос согласуйте с HALLA отдельно. Используйте условные HTTP-запросы и кеш-валидаторы, когда они доступны.
06 · Пример XML
Минимальная структура
Необязательные элементы и атрибуты могут отсутствовать. Используйте XSD как формальное описание полного контракта.
<?xml version="1.0" encoding="UTF-8"?>
<halla-catalog schema-version="1.0"
generated-at="2026-07-19T00:00:00.000Z"
series-count="1"
product-count="1">
<parameter-definitions>
<parameter key="luminous_flux" value-type="integer" unit="lm">
<name>Световой поток</name>
</parameter>
</parameter-definitions>
<categories/>
<series-list>
<series key="aliot" url="https://halla.ru/series/aliot">
<name>ALIOT</name>
</series>
</series-list>
<products>
<product article="1.101-140R-20-930" series-key="aliot"
url="https://halla.ru/series/aliot">
<name>ALIOT 140 R</name>
<specifications>
<specification key="luminous_flux">1450</specification>
</specifications>
</product>
</products>
</halla-catalog>07 · Совместимость
Версия 1 допускает безопасные дополнения
В пределах версии 1 могут появляться новые необязательные элементы и атрибуты. Интеграция должна игнорировать незнакомые необязательные поля, которые ей не нужны.
Переименование или удаление поля, изменение его смысла либо перевод необязательного поля в обязательное потребуют публикации отдельной версии каталога.
Нужна помощь?
Обсудим интеграцию
Укажите вашу систему и предполагаемый сценарий использования каталога.
hello@halla.ru