Обмен данными между 1С и 1С-Битрикс: пространство имен Bitrix\Sale\Exchange\OneC

В данной статье мы рассмотрим, как устроено пространство имен Bitrix\Sale\Exchange\OneC, используемое для интеграции «1С-Битрикс: Управление сайтом» с 1С. Вы узнаете, какие классы здесь присутствуют, за что они отвечают и как их можно применять на практике для импорта/экспорта заказов, оплат, отгрузок, профилей пользователей и пр.

$Пространство имен Bitrix\Sale\Exchange\OneC$

1. Назначение пространства имен Bitrix\Sale\Exchange\OneC

Пространство имен Bitrix\Sale\Exchange\OneC отвечает за двунаправленный обмен данными между «1С-Битрикс: Управление сайтом» и 1С (чаще всего в формате CommerceML). Основная задача — корректно принимать (импортировать) или формировать (экспортировать) такие сущности, как:

Заказы (Order),
Платежи (Payment),
Отгрузки (Shipment),
Профили пользователей (ProfileDocument / UserProfileDocument),
и другие объекты, связанные с заказами.

При стандартной интеграции (через /bitrix/admin/1c_exchange.php) большинство классов из этого пространства имен вызывается автоматически. Однако если вам требуется тонкая кастомизация обмена или углубленная отладка, важно понимать, какие именно классы задействованы и как они взаимодействуют.

2. Основные классы и их группы

Ниже рассмотрим упорядоченный список классов, разбив их на группы по назначению.

2.1. Коллизии (Conflict / Collision)

CollisionOrder
CollisionPayment
CollisionProfile
CollisionShipment
ImportCollision

Эти классы необходимы, чтобы фиксировать и обрабатывать конфликты (коллизии) при обмене. Например, если статус заказа в 1С противоречит статусу на сайте. Каждый класс связан со своей сущностью — заказ, платеж, профиль покупателя, отгрузка.

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

2.2. Конвертеры (Converter)

Converter
ConverterDocumentInvoice
ConverterDocumentOrder
ConverterDocumentPayment
ConverterDocumentPaymentInvoice
ConverterDocumentProfile
ConverterDocumentShipment
ConverterDocumentShipmentInvoice
ConverterFactory

Эти классы отвечают за преобразование (конвертацию) данных из одного формата в другой. Как правило, речь идет о том, чтобы:

Преобразовать структуру XML (CommerceML) в набор полей, понятных модулю «Интернет-магазин» (и наоборот).
Сопоставить поля (ID, GUID, суммы, статусы) 1С и «1С-Битрикс».
«Подсобрать» внутренние объекты (заказы, оплаты) из разрозненных данных.

Например:

ConverterDocumentOrder — логика конвертации для заказов;
ConverterDocumentShipment — для отгрузок;
ConverterDocumentPayment (и его «Invoice»-вариации) — для платежей;
ConverterDocumentProfile — для профилей пользователей.

ConverterFactory — «фабрика», которая выдает нужный ConverterDocument* на основании типа документа (заказ, оплата, отгрузка, профиль).

2.3. Критерии (Criterion)

CriterionOrder
CriterionPayment
CriterionProfile
CriterionShipment
CriterionShipmentInvoice
ImportCriterionBase
ImportCriterionOneCCml2

Критерии определяют, как сопоставлять полученный объект из 1С и уже существующую сущность на сайте (ищут «совпадение» по какому-то полю/идентификатору). Например, если в XML от 1С у заказа GUID = 1234, то CriterionOrder проверит: «Есть ли в Битрикс заказ с внешним кодом 1234?». Если да — обновляем, если нет — создаем новый.

ImportCriterionBase и ImportCriterionOneCCml2 — «базовые» классы, описывающие общую логику для формата CommerceML2.

2.4. Документы (Document)

DocumentBase
DocumentImport
DocumentImportFactory
DocumentType
OrderDocument
PaymentDocument, PaymentCardDocument, PaymentCashDocument, PaymentCashLessDocument
ProfileDocument, UserProfileDocument
ShipmentDocument

Классы, описывающие «документы обмена». В контексте модуля «Интернет-магазин» под «документом» может пониматься заказ, отгрузка, оплата, пользовательский профиль — то, что 1С отправляет или принимает в XML.

DocumentBase — базовый абстрактный класс, хранящий структуру «документа» (поля, методы get/set).
OrderDocument — описание «Заказа».
ShipmentDocument — описание «Отгрузки».
PaymentDocument (и разновидности Card, Cash, CashLess) — «Оплата» в разных формах.
ProfileDocument, UserProfileDocument — данные пользователя, его реквизиты, адреса и т. п.
DocumentImport и DocumentImportFactory — классы, обобщающие логику импорта: фабрика создает конкретный OrderDocument или ShipmentDocument исходя из того, что пришло в XML.
DocumentType — перечисление (константы) типа «ORDER», «PAYMENT», «SHIPMENT», «PROFILE» и т. д.

2.5. Настройки (Settings)

ExportSettings
ImportSettings
SettingsBase

Классы для хранения и управления настройками обмена. Например:

Учитывать ли НДС, какие статусы выгружать, какие поля синхронизировать, как реагировать на дубли.
SettingsBase — общий базовый класс для настроек.
ImportSettings — настройки, влияющие на импорт.
ExportSettings — настройки, влияющие на экспорт.

3. Сценарий использования на практике

В большинстве проектов достаточно стандартного механизма (скрипт /bitrix/admin/1c_exchange.php, который автоматически задействует многие описанные классы). Но иногда требуется дополнительная логика, например:

Сопоставление нестандартных полей (артикулы, кастомные реквизиты).
Особые правила при конфликте статусов.
Связь с кастомными сущностями Битрикс или внешними сервисами.

3.1. Настройка стандартного обмена

Админка Битрикс: В разделе «Магазин» → «Настройки» → «Интеграция с 1С» задаете URL для обмена, логин, пароль, форматы (CML2).
В 1С: Подключаете типовую обработку «Выгрузка на сайт», указываете адрес, логин/пароль, какие поля передавать и с какой периодичностью.
Проверка безопасности: Обычно обмен идёт по HTTPS, доступ закрыт под логин/пароль, чтобы никто извне не смог получить или подменить данные.

3.2. Процесс импорта (упрощенная схема)

1С формирует XML (CommerceML), отправляет на https://site.ru/bitrix/admin/1c_exchange.php?type=sale&mode=import.
Битрикс внутри этого скрипта:
- Определяет, какой это тип документов (order, payment, shipment).
- Вызывает DocumentImportFactory, который создает соответствующий OrderDocument, PaymentDocument или ShipmentDocument.
- Применяет ConverterDocument*, чтобы преобразовать данные в формат, понятный модулю «Интернет-магазин».
- Использует Criterion*, чтобы найти, есть ли уже соответствующий объект.
- Создает или обновляет заказ (платеж, отгрузку) в базе Битрикс.
- При возникновении противоречий фиксирует их через Collision*.
После импорта новые/обновленные заказы видны в админке сайта (раздел «Магазин» → «Заказы»).

3.3. Процесс экспорта

Битрикс формирует XML, используя ExportSettings и соответствующие ConverterDocument* классы.
1С забирает этот XML по регламенту (раз в час, день) или по кнопке «Обмен» в 1С.
1С обновляет у себя информацию о заказах, оплатах, контрагентах.

4. Пример кастомного кода (упрощенно)

Ниже псевдокод, как вы могли бы вручную обрабатывать входящий XML (если вдруг не используете стандартный /bitrix/admin/1c_exchange.php):


use Bitrix\Sale\Exchange\OneC\DocumentImportFactory;
use Bitrix\Sale\Exchange\OneC\ConverterFactory;
use Bitrix\Sale\Exchange\OneC\DocumentType;
use Bitrix\Sale\Exchange\OneC\ImportSettings;

function customOneCImportHandler($xmlString)
{
    // 1. Создаем фабрику документов
    $documentFactory = new DocumentImportFactory();
    
    // 2. Разбираем входящий XML -> массив (упрощенно)
    $parsedData = parseXmlToArray($xmlString); // ваш метод
    
    // 3. Перебираем все "Документы" из XML
    foreach ($parsedData['Документы'] as $docData)
    {
        // (a) Определяем тип документа (например, заказ)
        $type = defineDocumentType($docData); // может вернуть DocumentType::ORDER и т.д.
        
        // (b) Создаем соответствующий объект (OrderDocument, ShipmentDocument...)
        $document = $documentFactory->create($type);

        // (c) Заполняем данными
        $document->setFields($docData);

        // 4. Получаем конвертер для этого типа
        $converter = ConverterFactory::create($type);

        // 5. Можно настроить импорт
        $importSettings = new ImportSettings();
        // При необходимости донастраиваем параметры

        // 6. Преобразуем документ в поля, понятные ядру Битрикс
        $entityFields = $converter->resolveParams($document, $importSettings);

        // 7. Сохраняем в базе (создаем/обновляем заказ, оплату и т.д.)
        $result = saveOrUpdateOrderInBitrix($entityFields);
        if (!$result->isSuccess())
        {
            // Логируем ошибку
        }
    }
}

В реальном проекте эти действия обычно уже реализованы «под капотом» стандартного механизма 1С-обмена. Но вы можете переопределять или расширять его, если нужно что-то нестандартное (кастомные поля, свои правила коллизий и т.д.).

5. Рекомендации и часто задаваемые вопросы

Коллизии (Collisions):
Если статус заказа в 1С = «Отправлен», а на сайте = «Отменен», то возникает конфликт. Системе нужно понять, какие данные считать приоритетными. Вы можете использовать Collision*-классы и логи в админке, чтобы отслеживать такие случаи.
Критерии (Criterion*):
Определяют, как искать соответствие между данными 1С и данными сайта. По умолчанию — по GUID или внешнему коду. Если нужно искать по другим полям (например, по артикулу), можно расширить логику, наследуясь от CriterionOrder и т.п.
Производительность (большие выгрузки):
При больших каталогах или большом количестве заказов важно включать «пошаговый режим» обмена и увеличивать max_execution_time, memory_limit. Следите за логами /bitrix/log/ и настройками «Интернет-магазина».
Безопасность:
Используйте HTTPS и сложные пароли для доступа к обмену. Не делайте публичный URL /bitrix/admin/1c_exchange.php доступным без авторизации.
Гибкость настроек:
В большинстве случаев ImportSettings, ExportSettings можно настроить прямо в административном разделе Битрикс. Но при желании — и на уровне PHP-кода.

6. Заключение

Пространство имен Bitrix\Sale\Exchange\OneC — ключевое звено в механизме обмена данными между 1С и «1С-Битрикс: Управление сайтом». В нем собраны:

Классы-конвертеры (ConverterDocument*), превращающие XML CommerceML в объекты Битрикс и наоборот.
Классы-документы (OrderDocument, ShipmentDocument, PaymentDocument, ProfileDocument и др.), описывающие структуру данных при обмене.
Критерии (Criterion*), которые решают, обновлять ли существующую запись или создавать новую.
Коллизии (Collision*), позволяющие фиксировать и разбирать противоречивую информацию.
Настройки (ImportSettings, ExportSettings), влияющие на процесс импорта/экспорта.

Типовой сценарий обмена (через /bitrix/admin/1c_exchange.php) скрывает большую часть внутренней кухни. Но если требуется нестандартная интеграция — вы можете напрямую использовать данные классы (через фабрики и конвертеры), чтобы настраивать обмен под свои нужды.

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

В тексте статьи символ звёздочки (*) после названия (например, Criterion*, ConverterDocument*) применяется как условное обозначение группы однотипных классов, начинающихся или содержащих в названии этот префикс.

Зачем нужна звёздочка

Упрощение упоминания нескольких классов: Когда есть несколько родственных или похожих классов, чьи названия начинаются одинаково (например, ConverterDocumentOrder, ConverterDocumentPayment, ConverterDocumentProfile и т.д.), удобно написать ConverterDocument* вместо полного списка. Это сокращает текст и даёт понять, что речь идёт обо всех классах, подпадающих под общий шаблон.
Наглядно указывает на «пакет» классов: В тексте статьи стоит задача не подробно перечислить каждый класс, а обозначить всю группу. Символ «*» — это просто общепринятый «шаблон» (wildcard), говорящий «все классы, имена которых начинаются на ConverterDocument».
Используется вместо полного списка: Вместо того чтобы упоминать сразу ConverterDocumentOrder, ConverterDocumentPayment, ConverterDocumentShipment и другие, автор делает общее указание: «есть целая группа классов, которая начинается с ConverterDocument». Точно так же для критериев Criterion* имеется в виду CriterionOrder, CriterionPayment, CriterionProfile и т. д.

Таким образом, звёздочка – это упрощённый способ сослаться на все классы, которые имеют общее «имя-основу».

Теги: D7, справочник