Shopify через API и MCP: 262 действия REST, один GraphQL и три пробела в открытой спецификации, которых там официально нет

Обзор

Shopify — крупнейшая в мире платформа интернет-магазинов, и у неё, что удивительно для API такого масштаба, нет официальной машиночитаемой спецификации REST. Есть отличная документация для людей и полная схема для GraphQL — а вот Swagger или OpenAPI для REST Admin API Shopify не публикует вовсе, хотя сам REST объявлен «устаревшим» только с октября 2024 года и остаётся рабочим до сих пор.

Mira подключает Shopify — 262 действия REST Admin API (товары, заказы, клиенты, склад, скидки, доставка, метаполя, вебхуки, контент витрины и ещё две дюжины разделов) плюс одно действие graphql для всего, чего в REST нет, — и отдаёт это в Claude через MCP. Ниже — что там есть на самом деле и с чем пришлось разбираться отдельно.

Доступ без единой заявки

Владелец магазина заводит доступ сам: админка → Settings → Apps and sales channels → Develop apps → Create an app → выбрать нужные разделы (Admin API scopes) → Install app. На выходе — постоянный токен shpat_…, показанный один раз. Ни заявки, ни ожидания, ни похода к нам за OAuth-согласием.

У Shopify есть и второй способ — публичное OAuth-приложение для сторонних разработчиков из Shopify Partners, авторизующее ЛЮБОЙ магазин через страницу согласия. Он нужен, если ты строишь приложение для чужих магазинов и хочешь попасть в Shopify App Store. Mira читает данные ОДНОГО подключённого магазина — self-service токена для этого достаточно, и партнёрский поток остаётся зафиксированным долгом на случай, если это когда-нибудь изменится.

Спецификации нет — пришлось собирать вручную

Официального Swagger/OpenAPI для REST Admin API у Shopify нет. Лучшее, что нашлось в открытом доступе — сторонний проект, автоматически разобравший документацию shopify.dev в OpenAPI-формат для версий API с 2020 по «unstable». Это 970 путей — солидный охват, но не безупречный: скрейпер терял целые ресурсы между прогонами по разным версиям API, а три ресурса не появлялись НИ В ОДНОЙ версии вовсе.

Первым делом обнаружилось, что базовый список и создание заказов (GET/POST /orders.json) отсутствовали в спецификации начиная с версии 2020-07 — притом что в версиях 2020-01 и 2020-04 они ещё были. Заказы же не исчезают из REST API просто так: значит, скрейпер их потерял, а не Shopify их убрал. Решение — собрать снимок объединением путей ВСЕХ версий сразу, а не только последней: то, что пропало в поздних прогонах, восстанавливается из ранних.

Следующим пробелом оказался Product Variant — вариант товара (цена, sku, остаток), одна из самых используемых сущностей API вообще, — которого не было НИ В ОДНОЙ из версий скрейпленной спецификации. Транзакции по заказу (Transaction, оформление списания и возврата денег) — то же самое, целиком пропавший ресурс. Базовый CRUD правил скидок (PriceRule) — туда же: вложенные промокоды в спецификации были, самого правила — нет.

Все три пробела закрыты не по памяти, а сверкой с живыми страницами shopify.dev — с указанием конкретной страницы и даты сверки прямо в исходниках. Заодно нашлось, что путь снятия удержания с отгрузки (release_hold) в источнике устарел: спецификация показывала старую форму без идентификатора отгрузки в адресе, а актуальный REST требует именно его.

REST — таблицей, GraphQL — одним действием

262 действия REST описаны таблицей: адрес, метод, параметры, барьер записи — всё данными, а не рукописными обработчиками. Тело у Shopify почти всегда обёрнуто в один ключ ресурса — {"product": {...}}, {"order": {...}} — и таблица фиксирует именно этот ключ, а не поля внутри него. Ровно два действия нарушают этот шаблон: отмена заказа принимает плоские поля без обёртки, а изменение порядка товаров в «умной» коллекции — и вовсе query-параметрами при пустом теле.

GraphQL Admin API таблицей не покрыт — у него единая типовая схема в тысячи полей, а не набор REST-путей. Вместо этого — одно действие graphql, принимающее произвольный запрос: барьер записи срабатывает, если в тексте запроса встречается слово mutation. Консервативно — модель может прочитать данные без подтверждения, а написать без разрешения на запись у источника не сможет.

Где деньги двигаются, а где только выглядят так

Из 130 действий под барьером записи только два реально двигают деньги магазина. Оформление возврата (POST /orders/{id}/refunds.json) исполняется платёжным шлюзом НЕМЕДЛЕННО при создании — в отличие, например, от Модульбанка, где платёж сначала лежит черновиком и только отдельное подписание его проводит. А вот предпросчёт возврата (тот же ресурс, тот же метод POST) деньги не трогает вовсе — это просто расчёт суммы, который Shopify прямо документирует как предпросчёт без применения.

Второе денежное действие — проведение транзакции по заказу — устроено ещё интереснее: один и тот же вызов покрывает и списание денег с карты покупателя, и возврат, в зависимости от параметра kind в теле запроса. Различать это на уровне таблицы означало бы разбирать содержимое запроса как код, чего остальные коннекторы Mira не делают нигде, — поэтому барьер здесь намеренно консервативен: вызов помечен тратящим целиком.

Чего нет — и почему

Исключать из таблицы можно только по трём поводам: эндпоинт удалён или объявлен deprecated в выбранной версии, вызов требует OAuth-приложения (или конкретного тарифа) или он вовсе не выполним без multipart-запроса. Под это подпадают всего три группы, и у каждой — прямая цитата источника. Billing API (16 действий, выставление счёта владельцу магазина за подписку) физически недоступен custom app: Shopify отвечает на такой запрос отказом «Apps without a public distribution cannot use the Billing API» — это привилегия приложений из App Store. Устаревший Checkout API (10 действий) Shopify называет deprecated прямым текстом: «The REST Checkout API is deprecated as of version 2024-07». Директория сотрудников (Users, 3 действия) документирована как «available for … custom apps installed on Shopify Plus stores» — не коммерческие данные, а вдобавок требует тарифа, которого может не быть.

Всё, что раньше исключалось по мотиву «это работа сайтостроителя, а не коммерческие данные» — блоги и статьи, комментарии, темы оформления, Script Tags, редиректы, юридические страницы, сохранённые фильтры поиска клиентов, токены Storefront API, сводка по способам оплаты, самодиагностика приложения, — в таблицу вернулось: у shopify.dev нет отдельной цитаты, которая объявляла бы именно ЭТИ ресурсы устаревшими или недоступными custom app, а «не коммерческие данные» — не повод, который правило признаёт. Правка кода темы или Script Tag остаётся под тем же барьером записи, что и любое другое изменение, — но с явным примечанием: это код, видимый любому покупателю магазина сразу. Shopify Payments (отчётность встроенного платёжного шлюза, 6 действий) и Sales Channel Listing (публикация в сторонний канал продаж, 11 действий) тоже вернулись — у первого нет отдельной цитаты про custom app (только практическая оговорка: шлюз недоступен в большинстве стран мира, включая Россию, ровно как у раздела «Отчёты» про Shopify Plus), у второго веб-проверка не нашла отдельного заявления shopify.dev про deprecated или retired — есть только общая пометка REST как legacy, которая касается всего REST Admin API одинаково.

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

Живых ключей от боевого магазина Shopify нет — раздел появится, когда владелец магазина их даст. Разбор адреса и тела, барьер записи, заголовок X-Shopify-Access-Token (Shopify не использует схему Bearer), разбор конверта отказа и обработка GraphQL — включая разницу между протокольными ошибками и business-ошибками мутации внутри data — проверены против собственного HTTP-сервера в тестах, тем же приёмом, что у остальных коннекторов Mira, а не против *.myshopify.com.