API модуля sale: заказы программно

Модуль sale отвечает за заказы, корзину, оплату и доставку в интернет-магазине на 1С-Битрикс. Современный способ работать с заказами из кода — объектное D7 API: классы \Bitrix\Sale\Order, Basket, PropertyValueCollection. Разберём полный цикл создания заказа.

Обзор D7 API sale

Заказ в D7 — это дерево объектов. Корневой объект Order содержит коллекции: корзину (Basket), свойства (PropertyValueCollection), оплаты (PaymentCollection) и отгрузки (ShipmentCollection).

Перед работой подключите модуль: \Bitrix\Main\Loader::includeModule('sale'); и 'catalog', если добавляете товары каталога.

Создание заказа

Заказ создаётся фабричным методом с указанием сайта и типа плательщика.

use Bitrix\Sale\Order;

$order = Order::create('s1', $userId);
$order->setPersonTypeId(1);
$order->setField('CURRENCY', 'RUB');

Первый аргумент create() — идентификатор сайта (например, s1), второй — ID пользователя-владельца заказа. Тип плательщика (PERSON_TYPE_ID) определяет набор свойств заказа: физлицо, юрлицо и т. п.

Корзина и товары

Товары кладут в объект корзины. Её либо создают новую, либо берут корзину пользователя.

use Bitrix\Sale\Basket;

$basket = Basket::create('s1');
$item = $basket->createItem('catalog', $productId);
$item->setFields([
  'QUANTITY' => 2,
  'CURRENCY' => 'RUB',
  'LID' => 's1',
  'PRODUCT_PROVIDER_CLASS' => '\Bitrix\Catalog\Product\CatalogProvider',
]);
$order->setBasket($basket);

Параметр PRODUCT_PROVIDER_CLASS важен: провайдер подтягивает актуальную цену, доступное количество и параметры товара из каталога. Без него цену придётся задавать вручную полем PRICE.

Свойства заказа

Контактные данные покупателя (ФИО, телефон, адрес) хранятся в свойствах заказа. Работают через коллекцию свойств:

$propertyCollection = $order->getPropertyCollection();
foreach ($propertyCollection as $prop) {
  $code = $prop->getField('CODE');
  if ($code === 'FIO') {
    $prop->setValue('Иванов Иван');
  }
}

Удобные шорткаты коллекции: getPhone(), getUserEmail(), getPayerName(), getAddress(). Набор свойств зависит от типа плательщика, заданного через setPersonTypeId.

Оплата и доставка

Оплату и отгрузку добавляют в соответствующие коллекции.

// Отгрузка
$shipmentCollection = $order->getShipmentCollection();
$shipment = $shipmentCollection->createItem();
$service = \Bitrix\Sale\Delivery\Services\Manager::getById($deliveryId);
$shipment->setFields([
  'DELIVERY_ID' => $deliveryId,
  'DELIVERY_NAME' => $service['NAME'],
]);
$shipment->setField('CURRENCY', 'RUB');

Для оплаты создают элемент PaymentCollection с указанием платёжной системы (PAY_SYSTEM_ID). Отгрузку обычно наполняют всеми позициями через системную отгрузку getSystemShipment(), а при необходимости резервируют товар методом tryReserve().

Сохранение и обработка ошибок

Финальный шаг — пересчёт и сохранение. Метод save() возвращает объект \Bitrix\Main\Result.

$result = $order->save();
if ($result->isSuccess()) {
  $orderId = $order->getId();
} else {
  foreach ($result->getErrorMessages() as $error) {
    // логируем ошибку
  }
}

Чтение и изменение заказа

Существующий заказ загружают методом Order::load($orderId). Дальше меняют поля, статус, свойства или корзину и снова вызывают save().

• смена статуса: $order->setField('STATUS_ID', 'F');
• отметка об оплате: у объекта Payment — $payment->setPaid('Y');
• отметка об отгрузке: $shipment->setField('DEDUCTED', 'Y');
• добавление товара в существующий заказ — через корзину загруженного заказа.

Изменение статуса, оплаты и отгрузки рассылает события sale (например, OnSaleOrderSaved, OnSaleOrderPaid), на которые можно повесить интеграции.

Итог

Создание заказа в 1С-Битрикс через D7 API — это последовательная сборка дерева объектов: Order → корзина → свойства → отгрузка и оплата → save(). Такой подход корректно пересчитывает цены, скидки и резервы, а результат всегда возвращается объектом Result с проверкой ошибок.

Мы разрабатываем программное оформление заказов, интеграции магазина с 1С и CRM, синхронизацию оплат и отгрузок. Если нужен надёжный обмен заказами или нестандартная логика оформления — поможем спроектировать и внедрить.