WooCommerce REST API: фильтрование и поиск заказов с примерами кода

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

При работе с заказами через WooCommerce REST API часто возникает необходимость быстро получить список заказов по определённым критериям: по дате, статусу, пользователю, сумме заказа или кастомному метаполю. Стандартные параметры API не всегда покрывают все нужды, а попытки реализовать сложные фильтры могут привести к ошибкам или чрезмерной нагрузке на сервер.

Основные симптомы проблемы:

• Отсутствие нужных параметров фильтрации в стандартных GET запросах заказов.
• Получение слишком большого объёма данных без возможности сузить выборку.
• Проблемы с производительностью при попытках обработки фильтров на стороне клиента.

Пошаговое решение: добавляем поддержку фильтров и поиска в WooCommerce REST API заказов

1. Расширяем эндпоинт заказов через фильтр woocommerce_rest_shop_order_object_query

Для реализации кастомных фильтров воспользуемся хуком woocommerce_rest_shop_order_object_query, который позволяет модифицировать WP_Query аргументы перед выполнением запроса.

add_filter('woocommerce_rest_shop_order_object_query', function($args, $request) {
    // Пример: фильтрация заказов по минимальной сумме
    if ($request->get_param('min_total')) {
        $args['meta_query'][] = [
            'key' => '_order_total',
            'value' => floatval($request->get_param('min_total')),
            'compare' => '>=',
            'type' => 'NUMERIC'
        ];
    }
    // Пример: поиск по email покупателя
    if ($email = $request->get_param('customer_email')) {
        $args['meta_query'][] = [
            'key' => '_billing_email',
            'value' => sanitize_email($email),
            'compare' => 'LIKE'
        ];
    }
    return $args;
}, 10, 2);

2. Добавляем параметры в схему REST API для документации

Чтобы новые параметры отображались в документации и работали корректно, расширим схему эндпоинта заказов:

add_filter('woocommerce_rest_shop_order_schema', function($schema) {
    $schema['properties']['min_total'] = [
        'description' => 'Минимальная сумма заказа',
        'type' => 'number',
        'context' => ['view', 'edit']
    ];
    $schema['properties']['customer_email'] = [
        'description' => 'Email покупателя для поиска',
        'type' => 'string',
        'format' => 'email',
        'context' => ['view', 'edit']
    ];
    return $schema;
});

3. Использование новых фильтров при запросе

Теперь можно выполнять запросы с фильтрами, например:

GET /wp-json/wc/v3/orders?min_total=100&customer_email=example%40mail.com

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

Чтобы убедиться, что фильтрация работает:

• Выполните тестовые запросы через Postman или curl с новыми параметрами.
• Проверьте, что в ответе содержатся только заказы, удовлетворяющие условиям.
• Убедитесь, что остальные стандартные параметры API не нарушены.

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

• Ошибка 400 или 500 при запросах с новыми параметрами: проверьте, что параметры добавлены в схему и валидируются правильно.
• Пустой результат при фильтрации по метаполям: убедитесь, что ключи метаполей указаны корректно (например, _order_total, _billing_email), и данные действительно существуют у заказов.
• Падение производительности при большом количестве заказов: оптимизируйте мета-запросы, используйте индексы базы данных и лимитируйте выборку с помощью параметров per_page и page.

Практические советы по оптимизации и безопасности

• Кэширование ответов: используйте transient API или внешние кэш-системы для хранения результатов тяжелых запросов.
• Ограничение прав доступа: убедитесь, что расширенные фильтры доступны только авторизованным пользователям с нужными правами (например, менеджерам заказов).
• Валидация входных данных: всегда фильтруйте и проверяйте параметры запроса, чтобы предотвратить SQL-инъекции и другие атаки.

Сравнение вариантов реализации фильтров заказов