WooCommerce: отмена и возврат заказов через REST API

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

В WooCommerce стандартный REST API поддерживает базовые операции с заказами, но отмена заказа или инициирование возврата через API не всегда очевидны. Часто разработчики сталкиваются с ошибками 401, 403 или с тем, что статус заказа не меняется после запроса. Основные причины:

• Недостаток прав пользователя, под которым выполняется запрос.
• Отсутствие нужного эндпоинта для возврата товара (refund).
• Некорректный формат запроса или данные.
• Отсутствие поддержки возвратов в стандартном REST API WooCommerce (для возврата нужен отдельный запрос).

Пошаговое решение: отменяем и создаём возврат заказа через WooCommerce REST API

1. Проверка прав доступа и аутентификации

Для работы с заказами через REST API используйте ключи API с правами read_write. Пример установки ключей в WooCommerce админке: WooCommerce → Settings → Advanced → REST API.

Для авторизации в запросах используйте Basic Auth или OAuth 1.0a. Пример Basic Auth на PHP с использованием cURL:

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://example.com/wp-json/wc/v3/orders/123');
curl_setopt($ch, CURLOPT_USERPWD, 'consumer_key:consumer_secret');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

2. Отмена заказа (смена статуса на "cancelled")

Чтобы отменить заказ, отправьте PATCH-запрос на эндпоинт заказа с изменением статуса:

PATCH /wp-json/wc/v3/orders/{order_id}

{
  "status": "cancelled"
}

Пример на PHP:

$data = ['status' => 'cancelled'];
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://example.com/wp-json/wc/v3/orders/123');
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, 'PATCH');
curl_setopt($ch, CURLOPT_USERPWD, 'consumer_key:consumer_secret');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

3. Создание возврата (refund) для заказа

WooCommerce REST API не позволяет напрямую редактировать возвраты в заказах через стандартный эндпоинт заказа. Для этого используется эндпоинт /wp-json/wc/v3/refunds.

Пример создания возврата:

POST /wp-json/wc/v3/refunds

{
  "amount": "10.00",
  "reason": "Товар повреждён",
  "order_id": 123
}

PHP пример:

$refund_data = [
  'amount' => '10.00',
  'reason' => 'Товар повреждён',
  'order_id' => 123
];

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://example.com/wp-json/wc/v3/refunds');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_USERPWD, 'consumer_key:consumer_secret');
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($refund_data));
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, ['Content-Type: application/json']);
$response = curl_exec($ch);
curl_close($ch);
echo $response;

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

• Запросите заказ по ID GET /wp-json/wc/v3/orders/{order_id} и проверьте поле status — должно быть cancelled после отмены.
• Для возврата проверьте список возвратов GET /wp-json/wc/v3/refunds?order_id=123, чтобы убедиться, что возврат создан.
• Проверьте в админке WooCommerce, что заказ изменил статус, а возврат отображается в истории заказа.

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

• 401 Unauthorized / 403 Forbidden — проверьте права ключей API и правильность аутентификации.
• 400 Bad Request — убедитесь, что JSON-формат корректен, обязательные поля заполнены, например, amount для возврата.
• Изменение статуса заказа не работает — проверьте, что заказ существует и не находится в состоянии, блокирующем смену статуса (например, уже выполнен).
• Возврат не создаётся — убедитесь, что вы используете эндпоинт /refunds, а не пытаетесь добавить возврат через заказ.

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

• Используйте HTTPS для всех запросов к REST API.
• Ограничьте права ключей API только необходимыми (read_write только для тех, кто действительно должен менять данные).
• Логируйте успешные и неуспешные запросы для быстрого выявления проблем.
• При массовом обновлении заказов используйте пакетные запросы с интервальным выполнением, чтобы не перегружать сервер.

Чек-лист для интеграции отмены и возврата через REST API WooCommerce

1. Получить и проверить ключи API с правами read_write.
2. Убедиться в корректной аутентификации (Basic Auth или OAuth).
3. Отправить PATCH-запрос на изменение статуса заказа на cancelled.
4. Создать возврат через POST-запрос на эндпоинт /refunds с обязательным полем amount.
5. Проверить результаты через GET-запросы и админку WooCommerce.
6. Обработать и логировать ошибки.

Таблица сравнения способов отмены и возврата заказов в WooCommerce через API