Получить историю оплат и отгрузок заказа

В личном кабинете и админке нужно показывать, какие оплаты и отгрузки есть у заказа: сумма, дата оплаты, способ оплаты, трек-номер доставки, дата отгрузки. Данные лежат в коллекциях D7: PaymentCollection и ShipmentCollection заказа. Проблема: без знания API легко обращаться к старым методами или к сырым таблицам и терять связь с объектом заказа. Симптомы: пустой список оплат/отгрузок, неверные даты, отсутствие полей (PAY_SYSTEM_NAME, DELIVERY_NAME). Ниже — получение истории оплат и отгрузок через Order::load() и коллекции с возвратом массивов полей; проверка и типичные ошибки.

Решение

Получение полной истории оплат и отгрузок заказа через коллекции D7 API. Используйте в личном кабинете, детальных страницах заказов, отчётах.

use Bitrix\Main\Loader;
use Bitrix\Sale\Order;

function getOrderPaymentsHistory($orderId) {
    if (!Loader::includeModule('sale')) {
        return [];
    }
    
    $order = Order::load($orderId);
    if (!$order) {
        return [];
    }
    
    $paymentCollection = $order->getPaymentCollection();
    $payments = [];
    
    foreach ($paymentCollection as $payment) {
        $payments[] = [
            'ID' => $payment->getId(),
            'PAID' => $payment->getField('PAID') === 'Y',
            'SUM' => $payment->getField('SUM'),
            'CURRENCY' => $payment->getField('CURRENCY'),
            'PAY_SYSTEM_ID' => $payment->getField('PAY_SYSTEM_ID'),
            'PAY_SYSTEM_NAME' => $payment->getField('PAY_SYSTEM_NAME'),
            'DATE_PAID' => $payment->getField('DATE_PAID'),
            'DATE_BILL' => $payment->getField('DATE_BILL'),
            'PAY_VOUCHER_NUM' => $payment->getField('PAY_VOUCHER_NUM'),
            'PAY_VOUCHER_DATE' => $payment->getField('PAY_VOUCHER_DATE'),
            'COMMENTS' => $payment->getField('COMMENTS')
        ];
    }
    
    return $payments;
}

function getOrderShipmentsHistory($orderId) {
    if (!Loader::includeModule('sale')) {
        return [];
    }
    
    $order = Order::load($orderId);
    if (!$order) {
        return [];
    }
    
    $shipmentCollection = $order->getShipmentCollection();
    $shipments = [];
    
    foreach ($shipmentCollection as $shipment) {
        $shipments[] = [
            'ID' => $shipment->getId(),
            'DEDUCTED' => $shipment->getField('DEDUCTED') === 'Y',
            'ALLOW_DELIVERY' => $shipment->getField('ALLOW_DELIVERY') === 'Y',
            'DELIVERY_ID' => $shipment->getField('DELIVERY_ID'),
            'DELIVERY_NAME' => $shipment->getField('DELIVERY_NAME'),
            'TRACKING_NUMBER' => $shipment->getField('TRACKING_NUMBER'),
            'DATE_DEDUCTED' => $shipment->getField('DATE_DEDUCTED'),
            'DATE_ALLOW_DELIVERY' => $shipment->getField('DATE_ALLOW_DELIVERY'),
            'PRICE_DELIVERY' => $shipment->getField('PRICE_DELIVERY'),
            'CURRENCY' => $shipment->getField('CURRENCY')
        ];
    }
    
    return $shipments;
}

function getOrderFullHistory($orderId) {
    return [
        'payments' => getOrderPaymentsHistory($orderId),
        'shipments' => getOrderShipmentsHistory($orderId)
    ];
}

Пример использования:

$payments = getOrderPaymentsHistory(12345);
foreach ($payments as $payment) {
    if ($payment['PAID']) {
        echo 'Оплачено: ' . $payment['SUM'] . ' ' . $payment['CURRENCY'];
        echo 'Дата оплаты: ' . $payment['DATE_PAID'];
        echo 'Способ оплаты: ' . $payment['PAY_SYSTEM_NAME'];
    }
}

$shipments = getOrderShipmentsHistory(12345);
foreach ($shipments as $shipment) {
    if ($shipment['DEDUCTED']) {
        echo 'Отгружено: ' . $shipment['DELIVERY_NAME'];
        echo 'Трек-номер: ' . $shipment['TRACKING_NUMBER'];
    }
}

$history = getOrderFullHistory(12345);

Коллекции доступны только после Order::load(). DATE_PAID заполняется при оплате через платёжную систему; DATE_DEDUCTED — при отгрузке. Для истории изменений статусов заказа используйте отдельные механизмы (таблицы истории, события).

Проверка

1. Заказ с одной оплатой — вызовите getOrderPaymentsHistory для заказа, у которого есть оплата. Ожидаем массив с одним элементом; PAID = true, SUM и DATE_PAID заполнены (если оплата прошла).

2. Заказ с отгрузкой — для заказа с созданной отгрузкой getOrderShipmentsHistory должен вернуть хотя бы один элемент; при отгруженном — DEDUCTED = true, DATE_DEDUCTED и при наличии TRACKING_NUMBER заполнены.

3. Несуществующий заказ — Order::load() вернёт null, функции вернут [] или пустые массивы. В шаблоне обрабатывайте пустой результат.

4. Диагностика: пустые коллекции — убедитесь, что заказ загружен через D7 (Order::load), а не через старый API. У заказа в админке должны быть созданы оплата и/или отгрузка (разделы оплаты и доставки в карточке заказа).

Типичные ошибки

• Заказ получен не через D7 — коллекции PaymentCollection и ShipmentCollection есть у объекта Bitrix\Sale\Order. Если заказ взят через CSaleOrder или старыми методами, объекта Order нет — используйте Order::load($orderId).
• Ожидание истории изменений статусов — эти функции возвращают текущее состояние оплат и отгрузок (список сущностей с полями), а не лог «когда и что менялось». Для лога нужны таблицы истории или подписка на события.
• PAY_SYSTEM_NAME / DELIVERY_NAME пустые — поля могут подтягиваться из справочников по PAY_SYSTEM_ID и DELIVERY_ID; при необходимости дочитывайте название отдельно по ID.

Где применять

• Prod / dev: страница «Мой заказ» в ЛК, детальная страница заказа в админке, отчёты по оплатам и отгрузкам, уведомления (например письмо с трек-номером).
• Интеграции: выгрузка статусов оплаты и доставки в CRM или внешние системы.

Связанные сниппеты: Изменить статус заказа D7 и сохранить, Состав корзины заказа, Сопоставление статуса заказа и режим запроса.