Внешний код в 1С-Битрикс: что это и как работает

Внешний код (поле XML_ID) — это строковый идентификатор, по которому «1С-Битрикс: Управление сайтом» связывает свои объекты с объектами других систем, чаще всего с конфигурациями 1С (Управление торговлей, Комплексная автоматизация, ERP). Если внутренний ID товара или раздела существует только внутри базы сайта, то внешний код — «общий язык» между сайтом и учётной системой.

Без внешнего кода обмен данными между 1С и сайтом превращается в хаос: при каждой выгрузке товары и разделы создавались бы заново, появлялись бы дубли, а заказы теряли бы привязку к контрагентам. Именно по XML_ID механизм обмена понимает, что товар «Смартфон X» в 1С и товар с тем же кодом на сайте — это один и тот же объект.

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

Что такое внешний код и чем он отличается от ID

У каждого элемента инфоблока в Битриксе есть два ключевых идентификатора. Внутренний ID — автоинкрементное число, которое база данных присваивает автоматически при создании записи. Он уникален только в пределах конкретного сайта и никогда не меняется. Внешний код XML_ID — строка, которую заполняет либо внешняя система при обмене, либо администратор вручную, либо сам Битрикс при импорте.

Принципиальная разница в области действия: ID понятен только сайту, а XML_ID понятен обеим сторонам обмена. Когда 1С выгружает товар, в файле обмена (формат CommerceML) указывается его идентификатор — обычно GUID из 1С. Битрикс записывает этот идентификатор в XML_ID и при следующих выгрузках ищет товар именно по нему.

Где хранится внешний код у разных объектов

Поле XML_ID присутствует практически у всех сущностей, участвующих в обмене. У товаров и торговых предложений оно хранится в элементах соответствующих инфоблоков. Важный нюанс: у торгового предложения внешний код часто составной — он содержит идентификатор товара и идентификатор предложения через разделитель, что отражает связь «товар — вариант» в 1С.

У разделов каталога внешний код тоже заполняется при выгрузке структуры номенклатуры из 1С. Если разделы создавались на сайте вручную, а потом включён обмен, возможна ситуация, когда один и тот же раздел существует в двух экземплярах: «ручной» без XML_ID и выгруженный из 1С с кодом. Это классический источник дублей в каталоге.

Кроме каталога, внешние коды есть у свойств и значений свойств (списков), типов цен, складов, единиц измерения, контрагентов и профилей покупателей. У заказов внешний код появляется, если заказ выгружался в 1С и получил там свой идентификатор. У пользователей, синхронизированных с контрагентами, код хранится в служебных полях модуля интернет-магазина.

Как внешний код используется при обмене с 1С

Стандартный обмен между 1С и Битриксом работает по протоколу CommerceML. 1С формирует XML-файлы (import.xml, offers.xml, prices.xml, rests.xml), где каждый объект снабжён идентификатором. Битрикс при обработке файла сначала ищет объект по этому идентификатору в поле XML_ID: нашёл — обновляет, не нашёл — создаёт новый элемент и записывает код.

Тот же принцип действует в обратную сторону при выгрузке заказов. Заказ с сайта передаётся в 1С, там создаётся документ, и его идентификатор может вернуться на сайт как внешний код заказа. Благодаря этому последующие обновления статуса или оплаты находят «свой» заказ на обеих сторонах.

Если в настройках обмена включена опция деактивации или удаления элементов, отсутствующих в файле выгрузки, Битрикс ориентируется именно на список внешних кодов из файла. Объекты, чьих кодов нет в выгрузке, помечаются неактивными или удаляются — поэтому потеря XML_ID у части каталога может привести к массовой деактивации товаров.

Как посмотреть и при необходимости задать внешний код

Посмотреть внешний код товара можно в административном разделе: откройте элемент инфоблока каталога — поле «Внешний код» находится на основной вкладке рядом с названием. В списке элементов инфоблока колонку с внешним кодом можно вывести через настройки отображения списка, что удобно для массовой проверки.

Ручное заполнение XML_ID оправдано, когда обмен ещё не настроен, а привязка нужна заранее: например, вы готовите каталог на сайте и заранее проставляете коды, которые потом совпадут с идентификаторами из 1С. Либо когда сайт обменивается с самописной системой, где коды формируются по собственным правилам.

1. 1
   Откройте административный раздел и перейдите в список элементов инфоблока каталога
2. 2
   Включите отображение колонки «Внешний код» через настройки списка
3. 3
   Откройте карточку товара и сверьте значение с идентификатором в 1С или в файле выгрузки
4. 4
   Убедитесь, что код не пустой и не содержит лишних пробелов или дублирующихся значений

// Получить внешний код товара через API Битрикс
$res = CIBlockElement::GetByID($productId);
if ($item = $res->GetNext()) {
    echo $item["XML_ID"];
}

Типичные проблемы с внешними кодами и их решение

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

Вторая типичная ситуация — «битые» торговые предложения, когда предложение отвязалось от товара. Такое происходит, если составной внешний код предложения изменился, а связь с родительским товаром при этом потерялась. Проверять нужно и код предложения, и привязку к элементу каталога в карточке.

Третья группа проблем — конфликты при выгрузке из нескольких источников. Если один и тот же инфоблок наполняется из двух разных 1С или из 1С и файла поставщика, системы могут присваивать разные коды одним объектам или, наоборот, одинаковые коды разным объектам. В таких схемах правила формирования XML_ID нужно согласовывать заранее и документировать.

Как проверить, что обмен по внешним кодам работает правильно

После настройки или изменения обмена выполните контрольную выгрузку на небольшой группе товаров. Сравните количество элементов в 1С и на сайте: оно должно совпадать, а у каждого элемента на сайте должен быть заполнен внешний код, соответствующий идентификатору в файле выгрузки. Файл обмена можно открыть в текстовом редакторе и найти значения тегов идентификаторов.

Дополнительный признак здоровой синхронизации — отсутствие роста числа элементов при повторных выгрузках без изменения данных. Если каждый обмен добавляет новые товары, значит сопоставление по XML_ID не работает и нужно искать причину: пустые коды, разные форматы идентификаторов, ошибки в настройках соответствия инфоблоков.

FAQ: частые вопросы о внешнем коде