Битрикс – как добавить или обновить свойство в заказе

В интернет-магазинах на 1С-Битрикс часто возникает необходимость изменить свойства уже созданного заказа. Например:

• Добавить комментарий менеджера

• Обновить трек-номер доставки

• Установить флаг оплаты

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

1. Базовая функция для обновления свойств заказа

Код функции

/**
 * Обновляет или добавляет свойство заказа
 * @param int $prop_id - ID свойства
 * @param mixed $value - Новое значение
 * @param int $order_id - ID заказа
 * @param bool $check_order - Проверять существование заказа
 * @return bool|int - ID записи или false при ошибке
 */
function UpdateOrderProperty($prop_id, $value, $order_id, $check_order = true) 
{
    if (!CModule::IncludeModule('sale')) {
        AddMessage2Log('Module sale not installed', 'UpdateOrderProperty');
        return false;
    }
    
    // Проверка существования заказа (если требуется)
    if ($check_order && !CSaleOrder::GetByID($order_id)) {
        AddMessage2Log("Order {$order_id} not found", 'UpdateOrderProperty');
        return false;
    }
    
    // Получаем данные свойства
    $arOrderProp = CSaleOrderProps::GetByID($prop_id);
    if (!$arOrderProp) {
        AddMessage2Log("Property {$prop_id} not found", 'UpdateOrderProperty');
        return false;
    }
    
    // Проверяем, есть ли уже такое свойство у заказа
    $dbPropValue = CSaleOrderPropsValue::GetList(
        array(),
        array('ORDER_ID' => $order_id, 'ORDER_PROPS_ID' => $prop_id)
    );
    
    $arFields = array(
        'NAME' => $arOrderProp['NAME'],
        'CODE' => $arOrderProp['CODE'],
        'ORDER_PROPS_ID' => $prop_id,
        'ORDER_ID' => $order_id,
        'VALUE' => $value,
    );
    
    if ($arPropValue = $dbPropValue->Fetch()) {
        // Обновляем существующее значение
        if (!CSaleOrderPropsValue::Update($arPropValue['ID'], $arFields)) {
            AddMessage2Log("Failed to update property {$prop_id} for order {$order_id}", 'UpdateOrderProperty');
            return false;
        }
        return $arPropValue['ID'];
    } else {
        // Добавляем новое значение
        $id = CSaleOrderPropsValue::Add($arFields);
        if (!$id) {
            AddMessage2Log("Failed to add property {$prop_id} for order {$order_id}", 'UpdateOrderProperty');
            return false;
        }
        return $id;
    }
}

Как использовать?

// Пример 1: Обновить свойство с ID=22 в заказе 3668
UpdateOrderProperty(22, 'Новое значение', 3668);

// Пример 2: Очистить свойство (передать пустую строку)
UpdateOrderProperty(22, '', 3668);

2. Дополнительные улучшения

2.1. Обновление свойства по коду (вместо ID)

Если удобнее работать с символьными кодами, можно использовать такую функцию:

function UpdateOrderPropertyByCode($prop_code, $value, $order_id) 
{
    if (!CModule::IncludeModule('sale')) return false;
    
    $prop = CSaleOrderProps::GetList(array(), array('CODE' => $prop_code))->Fetch();
    if (!$prop) {
        AddMessage2Log("Property with code '{$prop_code}' not found", 'UpdateOrderPropertyByCode');
        return false;
    }
    
    return UpdateOrderProperty($prop['ID'], $value, $order_id, true);
}

Пример:

UpdateOrderPropertyByCode('TRACK_NUMBER', 'RU123456789', 3668);

2.2. Массовое обновление свойств

Если нужно изменить несколько свойств сразу:

function UpdateOrderProperties(array $properties, $order_id) 
{
    foreach ($properties as $prop_id => $value) {
        UpdateOrderProperty($prop_id, $value, $order_id, false);
    }
    return true;
}

Пример:

UpdateOrderProperties([
    22 => 'Комментарий менеджера',
    23 => 'Дата доставки: 2024-05-20',
], 3668);

3. Где применять эти функции?

• В обработчиках событий (например, OnSaleOrderSaved)

• В cron-заданиях (например, для автоматического обновления статусов)

• В административном разделе (при ручном изменении заказов)

4. Полезные ссылки

Документация CSaleOrderPropsValue
Работа с заказами в Битрикс

Вывод

Теперь вы знаете, как гибко управлять свойствами заказов в Битрикс. Используйте готовые функции из статьи, чтобы автоматизировать процессы в интернет-магазине!