WooCommerce: как использовать хук woocommerce_order_status_changed для синхронизации статусов заказов

Диагностика проблемы: необходимость синхронизации статусов заказов в WooCommerce

При работе с WooCommerce часто возникает задача синхронизировать статусы заказов с внешними системами — CRM, складским учётом или сервисами рассылок. Например, при смене статуса заказа с «в обработке» на «завершён» нужно автоматически обновить запись во внешней базе. Без правильного хука и обработки таких изменений возможны рассинхронизации и потеря данных.

Пошаговое решение: использование хука woocommerce_order_status_changed

Хук woocommerce_order_status_changed срабатывает при изменении статуса заказа. Его сигнатура:

do_action( 'woocommerce_order_status_changed', $order_id, $old_status, $new_status, $order );

Где:

• $order_id — ID заказа
• $old_status — предыдущий статус (например, 'processing')
• $new_status — новый статус (например, 'completed')
• $order — объект WC_Order

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

add_action( 'woocommerce_order_status_changed', 'sync_order_status_to_crm', 10, 4 );
function sync_order_status_to_crm( $order_id, $old_status, $new_status, $order ) {
    if ( 'completed' === $new_status ) {
        $customer_email = $order->get_billing_email();
        $order_total = $order->get_total();
        // Пример: отправка данных в CRM через API
        $response = wp_remote_post( 'https://example-crm.local/api/update_order', [
            'body' => json_encode([
                'order_id' => $order_id,
                'status' => $new_status,
                'email' => $customer_email,
                'total' => $order_total
            ]),
            'headers' => [
                'Content-Type' => 'application/json',
                'Authorization' => 'Bearer your_api_token'
            ]
        ] );
        if ( is_wp_error( $response ) ) {
            error_log( 'CRM sync failed for order #' . $order_id );
        }
    }
}

Настройка и тестирование

• Добавьте код в файл functions.php вашей темы или в кастомный плагин.
• Измените URL и параметры запроса под ваши API.
• Для теста создайте заказ в WooCommerce и смените его статус на completed.

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

Чтобы убедиться, что синхронизация работает:

• Проверьте логи сервера на наличие ошибок (например, error_log в коде).
• Убедитесь, что внешний сервис получил и обработал запрос (через логи API или интерфейс CRM).
• Используйте error_log или дебаггер для вывода информации внутри функции.

Частые ошибки и способы их исправления

• Пропущены параметры в add_action: если указать меньше 4 аргументов, объект $order не передастся, что ограничит функционал. Решение: добавить четвертый параметр 4 и указать количество принимаемых аргументов.
• Неправильный статус: сравнивайте статусы без префиксов, например, completed, а не «завершён». Используйте точные значения статусов.
• Проблемы с API: проверьте URL, токены и формат данных. Используйте wp_remote_post с обработкой ошибок.
• Кэширование: если изменения не видны, очистите кэш сайта и браузера.

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

• Всегда проверяйте и фильтруйте данные, получаемые из заказа перед отправкой внешним сервисам.
• Добавляйте обработку ошибок и логирование для отслеживания сбоев.
• Минимизируйте время выполнения функции, чтобы не замедлять оформление заказа.
• Если синхронизация занимает время, рассмотрите асинхронную отправку через WP Cron или внешние очереди.

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

Метод	Преимущества	Недостатки	Пример
Хук woocommerce_order_status_changed	Точный момент смены статуса, доступ к объекту заказа	Выполнение в синхронном режиме, можно замедлить процесс	Код из статьи
WP Cron для периодической синхронизации	Асинхронность, не блокирует оформление заказа	Задержка обновления, возможна рассинхронизация	Периодический скрипт с запросом статусов
Вебхуки WooCommerce	Нативный механизм, отправка событий в реальном времени	Требуется настройка и обработка на стороне сервера	Настройка в админке WooCommerce