Документация для разработчиков
Темная тема

Отгрузки

Внимание! Отгрузки всегда связаны с заказом. Использовать метод \Bitrix\Sale\Shipment::save() для сохранения категорически запрещается. При изменении отгрузки может произойти изменение связанных сущностей, которые не будут сохранены. Необходимо выполнять сохранение через заказ: \Bitrix\Sale\Order::save(). Помимо всего этого в одной из ближайших версий вызов \Bitrix\Sale\Shipment::save() будет генерировать ошибку уровня E_WARNING.


Описание и добавление

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

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

  • либо количество товара уменьшится,
  • либо товар полностью из системной отгрузки переместится в обычную отгрузку.

В первом случае с этой отгрузкой ничего нельзя сделать: ни отгрузить, ни удалить. Поэтому правильнее ее исключать во время обхода коллекции (см. примеры Работа с коллекцией без системной отгрузки или Получение конкретной отгрузки).

Добавление отгрузки

  • Вариант 1:
    /*
     * $collection - объект класса \Bitrix\Sale\ShipmentCollection
     */
    
    $shipment = $collection->createItem();
    $shipment->setField('DELIVERY_ID', 10);
    
    /*
     * метод \Bitrix\Sale\ShipmentCollection::createItem принимает один необязательный параметр: 
     * $delivery - объект службы доставки
     */
    $service = \Bitrix\Sale\Delivery\Services\Manager::getById(10);
    $shipment = $collection->createItem($service);
    
  • Вариант 2:
    /*
     * в метод \Bitrix\Sale\Shipment::create тоже можно передать объект платежной системы
     */
    $service = \Bitrix\Sale\Delivery\Services\Manager::getById(10);
    $shipment = \Bitrix\Sale\Shipment::create($collection, $service);
    
    $collection->addItem($shipment);
    

Получение

  • Работа с коллекцией
    $collection = $order->getShipmentCollection();
    foreach ($collection as $shipment)
    {
    	// ...
    }
    
  • Работа с коллекцией без системной отгрузки
    $collection = $order->getShipmentCollection()->getNotSystemItems();
    foreach ($collection as $shipment)
    {
    	// ...
    }
    
  • Работа с массивом

    Помимо объектов есть возможность напрямую обращаться к базе через метод \Bitrix\Sale\ShipmentCollection::getList($parameters), либо \Bitrix\Sale\Shipment::getList($parameters). Оба этих метода работают аналогично.

    Метод всегда возвращает объект Bitrix\Main\DB\Result, из которого можно получить данные с помощью метода fetch().

    Параметр Описание С версии
    $parameters Массив, структура которого полностью соответствует структуре ORM'ного getList.
    // получение списка отгрузок для заказа 1234
    $dbRes = \Bitrix\Sale\ShipmentCollection::getList([
    	'select' => ['*'],
    	'filter' => [
    		'=ORDER_ID' => 1234, 
    	]
    ]);
    
    while ($item = $dbRes->fetch())
    {
    	var_dump($item);
    }
    

Редактирование

Возможные варианты:

  • $r = $shipment->setField($fieldName, $value);
    
  • $r = $shipment->setFields([
    	$fieldName1 => $value1,
    	$fieldName2 => $value2,
    	...
    ]);
    

В обоих случаях результатом работы метода является объект класса \Bitrix\Sale\Result.

Список доступных для редактирования полей:

"STATUS_ID", // статус отгрузки
"BASE_PRICE_DELIVERY", // базовая стоимость доставки
"ALLOW_DELIVERY", // флаг разрешения доставки: Y/N
"DATE_ALLOW_DELIVERY", // дата разрешения доставки
"EMP_ALLOW_DELIVERY_ID", // ID пользователя, который разрешал доставку
"DEDUCTED",  // флаг отгрузки: Y/N
"DATE_DEDUCTED", // дата отгрузки
"EMP_DEDUCTED_ID", // ID пользователя, который отгружал отгрузку
"REASON_UNDO_DEDUCTED", // причина отмены отгрузки
"DELIVERY_ID", //  ID службы доставки
"DELIVERY_DOC_NUM", // номер документа отгрузки
"DELIVERY_DOC_DATE", // дата документа отгрузки
"TRACKING_NUMBER", // трэк-номер
"XML_ID", //XML_ID
"PARAMS", // 
"DELIVERY_NAME", // название службы доставки
"COMPANY_ID", // ID компании, занимающейся отгрузкой
'MARKED', // промаркирована ли отгрузка
'REASON_MARKED', // причина маркировки
'DATE_MARKED', // дата маркировки
'EMP_MARKED_ID', // кем промаркирована отгрузка
"CANCELED", // отменена ли отгрузка
"DATE_CANCELED",
"EMP_CANCELED_ID",
'RESPONSIBLE_ID', // ID пользователя, ответственного за отгрузку
'EMP_RESPONSIBLE_ID', // ID пользователя, который назначил ответственного
'DATE_RESPONSIBLE_ID', // дата назначения ответственного
"COMMENTS", // комментарий
"CURRENCY", // валюта
"CUSTOM_PRICE_DELIVERY", // Флаг, установлена ли цена вручную
'UPDATED_1C', // обновлена ли через 1С
'ID_1C', // ID в 1С
'VERSION_1C', // версия документа отгурзки от 1С
'EXTERNAL_PAYMENT', // флаг Y/N: внешняя отгрузка или нет
"TRACKING_STATUS", // статус отправления
"TRACKING_LAST_CHECK", // дата последней проверки статуса отправления
"TRACKING_DESCRIPTION", // описание статуса отправления
'ACCOUNT_NUMBER', // номер отгрузки
'DISCOUNT_PRICE' // сумма итоговой скидки/наценки для отгрузки

Удаление

Возвращает объект типа \Bitrix\Sale\Result.

$r = $shipment->delete();
if ($result->isSuccess())
{
	...
}

Получение статуса

$statusId = $shipment->getField('STATUS_ID');

Получение конкретной отгрузки

$collection = $order->getShipmentCollection();
  • по ID
    $shipment = $collection->getItemById($id);
    
  • по внутреннему индексу
    $shipment = $collection->getItemByIndex($index);
    
  • по коду
    $shipment = $collection->getItemByShipmentCode($code);
    

Получение стоимости доставки

$price = $shipment->getPrice();

Флаги разрешения и отгрузки доставки

Управление флагом разрешения доставки

  • Доставка разрешена
    $r = $shipment->allowDelivery();
    if (!$r->isSuccess())
    {
    	var_dump($r->getErrorMessages());
    }
    
  • Доставка не разрешена
    $r = $shipment->disallowDelivery();
    if (!$r->isSuccess())
    {
    	var_dump($r->getErrorMessages());
    }
    

Управление флагом отгрузки доставки

  • Доставка отгружена
    $r = $shipment->setField('DEDUCTED', 'Y');
    if (!$r->isSuccess())
    {
    	var_dump($r->getErrorMessages());
    }
    
  • Доставка не отгружена
    $r = $shipment->setField('DEDUCTED', 'N');
    if (!$r->isSuccess())
    {
    	var_dump($r->getErrorMessages());
    }
    

Получение распределенного количества товара по отгрузкам

$shipmentCollection = $order->getShipmentCollection();
$quantity = $collection->getBasketItemDistributedQuantity();

Получение стоимости всех доставок в заказе

  • без учета скидок/наценок
    $shipmentCollection = $order->getShipmentCollection();
    $price = $collection->getBasePriceDelivery();
    
  • с учетом скидок/наценок
    $shipmentCollection = $order->getShipmentCollection();
    $price = $collection->getBasePriceDelivery();
    

Установка склада самовывоза для отгрузки

$order = \Bitrix\Sale\Order::load(123);
    
$collection = $order->getShipmentCollection();

$shipment = $collection->getItemById(1);

$storeId = '2';
$shipment->setStoreId($storeId);
    
$order->save();

В примере заказ уже существует. Для нового заказа код аналогичный.

Получение списка доступных служб доставок с учетом настроенных ограничений

$deliveryList = \Bitrix\Sale\Delivery\Services\Manager::getRestrictedList($shipment, $mode);
Параметры Описание С версии
$shipment Объект отгрузки.
$mode Одно из двух значений:
  • \Bitrix\Sale\Services\Base\RestrictionManager::MODE_CLIENT
  • \Bitrix\Sale\Services\Base\RestrictionManager::MODE_MANAGER

По умолчанию: \Bitrix\Sale\Services\Base\RestrictionManager::MODE_CLIENT. В режиме клиента возвращается список только тех служб доставок, которые попадают под ограничения.

В режиме менеджера возвращается полный список служб доставок (доставки, которые не подают под ограничения, имеют ключ RESTRICTED).


Пользовательские комментарии

Мы будем рады, если разработчики добавят свои комментарии по практическому использованию методов системы.

Для этого нужно всего лишь авторизоваться на сайте

Но помните, что Пользовательские комментарии, несмотря на модерацию, не являются официальной документацией. Ответственность за их использование несет сам пользователь.

Также Пользовательские комментарии не являются местом для обсуждения функционала. По подобным вопросам обращайтесь на форумы.
© «Битрикс», 2001-2020, «1С-Битрикс», 2020
Наверх