WooCommerce через API и MCP: 132 операции, два id в одном пути и массив вместо объекта

Обзор

WooCommerce — самый распространённый в мире движок интернет-магазина: плагин поверх WordPress, ставится на любой хостинг, открытый код. У него есть официальный REST API v3, и доступ к нему выдаётся самообслуживанием — в админке магазина WooCommerce → Настройки → Дополнительно → REST API → «Добавить ключ». Никаких заявок и одобрений: пара consumer_key/consumer_secret готова сразу.

Mira подключает этот API целиком — 132 операции в 22 разделах — и отдаёт его в Claude через MCP. Ниже — что там есть на самом деле и три места, где устройство WooCommerce расходится с тем, что видели предыдущие коннекторы Mira.

Что доступно

У WooCommerce нет своего Swagger — и это нормально

Точка Банк и Модульбанк отдают настоящую машиночитаемую спецификацию прямо на боевом хосте: скачал JSON, разобрал программой, готов снимок контракта. WooCommerce так не может — весь REST API описан только человеческим текстом на отдельном сайте документации, страница на ресурс, таблица параметров у каждого метода.

Это не повод собирать таблицу вызовов «по памяти» — путь к решению из инструкции для агентов Mira: собрать снимок построчной транскрипцией документации и явно сказать, что это не автоматическая выгрузка. Обязательные поля тела для создания каждой сущности — name у товара, code у купона, email у клиента — набирались отдельным проходом по документации, независимо от таблицы вызовов, специально для того, чтобы тест контракта мог поймать расхождение, а не просто подтвердить сам себя.

Один путь — два идентификатора

У большинства прошлых коннекторов Mira (Модульбанк, Точка) в пути ровно один переменный параметр, и общий приём «id» подставлялся в любой из них. WooCommerce ломает это допущение: вложенные ресурсы несут сразу два числовых идентификатора. Вариация товара живёт по адресу /products/{product_id}/variations/{id}, заметка заказа — по /orders/{order_id}/notes/{id}, способ доставки внутри зоны — по /shipping/zones/{id}/methods/{instance_id}.

Общий приём здесь тихо подставил бы одно значение не в тот параметр — и ошибка обнаружилась бы только на живом магазине, отказом «товар не найден» с чужим номером. Поэтому у WooCommerce общего фолбэка нет вовсе: вызывающий обязан назвать оба имени точно, и справочное действие показывает оба явно.

Массив вместо объекта — редкий, но настоящий случай

Почти везде тело запроса WooCommerce — JSON-объект с именованными полями: {"name": "...", "regular_price": "..."}. Ровно одна операция ломает этот паттерн: замена регионов зоны доставки принимает голый JSON-массив целиком — [{"code": "US"}, {"code": "CA", "type": "state"}] — и этот список ЗАМЕНЯЕТ прежний набор регионов, а не дополняет его. Обычная сборка тела «взять поля из перечисленного списка и собрать объект» здесь неприменима вообще — пришлось завести отдельный механизм, который отправляет параметр целиком как есть, минуя привычную сборку по именам полей.

Барьер: создание платёжного поручения — не то же самое, что возврат денег

69 из 132 операций меняют данные магазина: любое создание, изменение, удаление, пачечная операция. Но только одна тратит деньги по-настоящему — оформление возврата по заказу, потому что по умолчанию WooCommerce пытается вернуть деньги ЧЕРЕЗ ПЛАТЁЖНЫЙ ШЛЮЗ, а не просто сделать учётную пометку. Удаление самой записи о возврате, наоборот, ничего не возвращает и не списывает повторно — это только правка бухгалтерии задним числом.

Отдельно стоит смена статуса и цены заказа: она видна покупателю (письмо о смене статуса, обновлённый итог в личном кабинете), но WooCommerce не различает на уровне API «тихое» изменение от «видного» — значит и барьер здесь одинаковый для любой правки заказа, а различие остаётся только в тексте предупреждения.

HTTPS обязателен — не совет, а техническое требование

Официальная авторизация WooCommerce — HTTP Basic по паре ключей — работает корректно только по HTTPS: без шифрования канала заголовок с ключами магазина ушёл бы в сеть открытым текстом. У WooCommerce есть и второй способ для магазинов без сертификата — подпись параметров запроса по протоколу OAuth 1.0a, — но он остаётся зафиксированным долгом: сертификат Let's Encrypt бесплатен и стандартен для любого современного WordPress-хостинга, а магазин без него — редкое и явно рискованное исключение, которое не стоит обслуживать ценой лишней сложности у всех остальных.

Живая проверка

Живых ключей consumer_key/consumer_secret от боевого магазина WooCommerce нет — раздел появится, когда владелец магазина их выпустит. Разбор адреса и тела, барьер записи, HTTP Basic из пары ключей и разбор отказа проверены против собственного HTTP-сервера в тестах (перехват на транспорте — тот же приём, что у Авито, Модульбанка и ЮKassa), а не против настоящего wp-json/wc/v3.