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

Отгрузки

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

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

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

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

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


  • Получение отгрузок:
  • Получение конкретной отгрузки
  • Добавление отгрузки
  • Редактирование отгрузки
  • Удаление отгрузки
  • Получение стоимости доставки
  • Получение статуса отгрузки
  • Управление флагом разрешения доставки
  • Управление флагом отгрузки доставки
  • Изменение стоимости доставки
  • Получение распределенного количества товара по отгрузкам
  • Получение стоимости всех доставок в заказе:
  • Установка склада самовывоза для отгрузки
  • Получение списка доступных служб доставок с учетом настроенных ограничений
  • Получение отгрузок:

    • Работа с коллекцией
      $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);
      }
      

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

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

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

    • Вариант 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);
      

    Редактирование отгрузки

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

    • $r = $payment->setField($fieldName, $value);
      
    • $r = $payment->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())
    {
    	...
    }
    

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

    $price = $shipment->getPrice();
    

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

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

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

    • Доставка разрешена
      $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());
      }
      

    Изменение стоимости доставки

    $price = 123;
    $shipment->setBasePriceDelivery($price);
    

    В метод так же можно передать второй параметр: является ли цена кастомной. Если да, то передается true. По умолчанию он равен false.

    $shipment->setBasePriceDelivery($price, true);
    

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

    $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-2019, «1С-Битрикс», 2019
    Наверх