WooCommerce: автоматическое изменение статуса заказа при возврате через API

Диагностика проблемы: почему статус заказа не меняется при возврате через API

При интеграции WooCommerce с внешними сервисами возврата средств (например, платёжными шлюзами или CRM) часто возникает ситуация, когда возврат оформляется в системе, но статус заказа в WooCommerce не обновляется. Это приводит к несоответствию состояния заказа, неправильным отчётам и ошибкам в учёте.

Причины могут быть следующие:

• Отсутствие обработчика события возврата в WooCommerce;
• API-запрос изменяет данные возврата, но не меняет статус заказа;
• Использование нестандартных статусов без правильного присвоения;
• Ошибки в коде, которые не инициируют смену статуса после возврата.

Пошаговое решение: как автоматически менять статус заказа при возврате через API

1. Подключаем хук для обработки возвратов

WooCommerce не имеет встроенного универсального хука для возврата, но можно использовать событие изменения метаданных заказа или событие изменения статуса оплаты.

Оптимальный вариант — после успешного возврата через API вызвать функцию, которая изменит статус заказа на нужный, например, refunded.

2. Пример кода для автоматического обновления статуса заказа

add_action('woocommerce_order_refunded', 'auto_update_order_status_on_refund', 10, 2);
function auto_update_order_status_on_refund($order_id, $refund_id) {
    $order = wc_get_order($order_id);
    if (!$order) {
        return;
    }

    // Проверяем, что возврат значимый и сумма возврата больше 0
    $refund = wc_get_order($refund_id);
    if ($refund && $refund->get_total() > 0) {
        // Меняем статус заказа на refunded
        $order->update_status('refunded', 'Статус автоматически обновлен после возврата через API');
    }
}

3. Обработка возврата из внешних API

Если возврат происходит через внешний API, необходимо убедиться, что после успешного возврата вызывается функция, которая обновляет статус заказа в WooCommerce.

Пример интеграции с внешним API (псевдо-код):

function handle_external_refund($order_id, $refund_amount) {
    // Логика запроса к API возврата
    $api_response = external_api_refund_call($order_id, $refund_amount);

    if ($api_response['success']) {
        // Создаем возврат в WooCommerce
        $order = wc_get_order($order_id);
        $refund = wc_create_refund(array(
            'amount' => $refund_amount,
            'reason' => 'Возврат через внешний API',
            'order_id' => $order_id,
        ));

        if (is_wp_error($refund)) {
            error_log('Не удалось создать возврат: ' . $refund->get_error_message());
            return false;
        }

        // Обновляем статус заказа
        $order->update_status('refunded', 'Автоматический возврат через внешний API');
        return true;
    }
    return false;
}

Проверка результата после внедрения

• Создайте тестовый заказ в WooCommerce с оплатой.
• Имитируйте возврат через API или вручную создайте возврат в админке.
• Убедитесь, что после возврата статус заказа обновился на refunded.
• Проверьте логи ошибок PHP и WooCommerce на отсутствие ошибок.
• Проверьте, что уведомления клиенту и администратору отправляются корректно (если настроены).

Частые ошибки и как их исправить

• Статус не меняется: Проверьте, что хук woocommerce_order_refunded действительно вызывается. Для отладки добавьте запись в лог внутри функции.
• Ошибка при создании возврата: Функция wc_create_refund может возвращать WP_Error. Проверьте права пользователя и корректность параметров.
• Несоответствие статусов: Используйте стандартные статусы WooCommerce (например, refunded). Если нужен кастомный статус, зарегистрируйте его и добавьте в список разрешённых.
• Конфликт с другими плагинами: Отключите плагины, которые могут перезаписывать статусы заказов или блокировать обновления.

Практические советы по безопасности и производительности

• Всегда проверяйте права пользователя и источник API-запроса, чтобы избежать несанкционированного изменения заказов.
• Используйте nonce и проверку аутентификации в API-вызовах.
• Логируйте критичные операции, чтобы быстро выявлять ошибки.
• Избегайте прямого изменения статусов без проверки возврата — это может привести к рассинхронизации данных.

Чек-лист для настройки автоматического обновления статуса заказа при возврате

• Подключён хук woocommerce_order_refunded с корректной функцией обратного вызова.
• Создание возврата через wc_create_refund производится с проверкой ошибок.
• Статус обновляется вызовом $order->update_status('refunded').
• Обеспечена проверка возврата от внешнего API перед обновлением заказа.
• Проведено тестирование на тестовом заказе с имитацией возврата.
• Настроено логирование и проверка прав доступа.

Сравнение вариантов реализации обновления статуса заказа

Метод	Преимущества	Недостатки	Пример использования
Хук woocommerce_order_refunded	Простой, встроенный механизм Работает при стандартных возвратах	Не срабатывает при возвратах вне WooCommerce Зависит от корректного создания возврата	Автоматическое обновление статуса после возврата
Прямой вызов $order->update_status() из API	Гибкость, контроль из внешних систем	Требует дополнительной логики и проверки Риск рассинхронизации	Интеграция с внешним API возврата
Кастомные cron-задачи для проверки возвратов	Автоматическое исправление ошибок Подходит для массовых возвратов	Сложнее в реализации Дополнительная нагрузка на сервер	Периодический аудит статусов заказов