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

curl -X PUT https://example.com/wp-json/wc/v3/orders/123 \ 
 -u consumer_key:consumer_secret \ 
 -H "Content-Type: application/json" \ 
 -d '{"status": "cancelled"}'

curl -X POST https://example.com/wp-json/wc/v3/refunds \ 
 -u consumer_key:consumer_secret \ 
 -H "Content-Type: application/json" \ 
 -d '{
   "amount": "10.00",
   "reason": "Product defect",
   "order_id": 123
 }'

Шаблоны для WP Плагины для WP

Проблемы при отмене и возврате заказов через WooCommerce REST API

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

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

• Заказ остаётся в статусе "processing" или "completed" после запроса отмены.
• Ответ API содержит ошибки с кодом 400 или 403.
• Возврат средств не происходит, хотя статус заказа изменяется.
• Ошибка 401 Unauthorized при попытке изменить заказ.

Диагностика проблемы

Для выявления точной причины необходимо проверить следующие моменты:

• Права доступа API: убедитесь, что используемый ключ имеет права на изменение заказов.
• Корректность статуса: WooCommerce ограничивает переходы между статусами, например, нельзя отменить заказ, который уже завершён.
• Обработка возврата: изменение статуса не инициирует возврат платежа. Для этого нужно работать с платежным шлюзом или вручную создавать возврат.
• Формат запроса: неверная структура JSON может приводить к ошибкам 400.

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

1. Проверка прав доступа

В настройках WooCommerce API убедитесь, что ключ имеет права write для заказов. Если нет, создайте новый ключ с нужными правами.

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

Для отмены заказа достаточно изменить его статус на cancelled. Например, используя cURL:

curl -X PUT https://example.com/wp-json/wc/v3/orders/123 \ 
 -u consumer_key:consumer_secret \ 
 -H "Content-Type: application/json" \ 
 -d '{"status": "cancelled"}'

Важно: заказ должен быть в статусе, разрешающем отмену (например, processing или on-hold), иначе REST API вернёт ошибку.

3. Оформление возврата средств

WooCommerce REST API не поддерживает полноценное создание возвратов через endpoint заказов. Для этого нужно использовать отдельный endpoint возвратов (Refunds), доступный начиная с WooCommerce 3.0. Пример создания возврата:

curl -X POST https://example.com/wp-json/wc/v3/refunds \ 
 -u consumer_key:consumer_secret \ 
 -H "Content-Type: application/json" \ 
 -d '{
   "amount": "10.00",
   "reason": "Product defect",
   "order_id": 123
 }'

Этот запрос создаст возврат на сумму 10.00 для заказа с ID 123. Возврат обработает платёжный шлюз, если он поддерживает возвраты через WooCommerce.

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

Чтобы убедиться, что отмена и возврат прошли успешно:

• Запросите заказ через REST API и проверьте, что status изменился на cancelled.
• Проверьте список возвратов для заказа через endpoint /wc/v3/refunds?order=123, чтобы убедиться, что возврат создан.
• В админке WooCommerce проверьте, что заказ отображается с правильным статусом и возврат отражён в истории транзакций.
• Если возврат платежа не произошёл, проверьте логи платёжного шлюза.

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

• Ошибка 401 Unauthorized: неверные ключи или недостаточные права доступа API. Решение: проверить ключи и права.
• Ошибка 400 Bad Request: неверный формат запроса или попытка изменить статус неподдерживаемым образом. Решение: проверить JSON и текущий статус заказа.
• Статус не меняется: заказ уже завершён или отменён, либо изменение статуса запрещено логикой WooCommerce. Решение: проверить текущий статус и использовать допустимые переходы.
• Возврат средств не создаётся: платёжный шлюз не поддерживает возвраты через API WooCommerce или требуется ручная обработка. Решение: проверить совместимость платёжного шлюза и документацию.

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

• Используйте права доступа API с минимумом необходимых разрешений (принцип наименьших прав).
• Ограничьте доступ по IP или настройте Basic Auth/.htaccess для защиты ключей API.
• Логируйте запросы на изменение заказов и возвраты для аудита и отладки.
• При массовом обновлении заказов используйте пакетные запросы и обрабатывайте ошибки 429 Too Many Requests, чтобы избежать блокировок.

Сравнение вариантов реализации отмены и возврата заказов