Коннектор Shopify

Коннектор Shopify реализован по шаблону B (TypeScript серверный коннектор) из wiki/tasks/cms-platform-expansion.md. Использует OAuth Shopify для получения per-shop access token, шифрует его at-rest, и слушает product-вебхуки, чтобы пушить дельта-синхронизации в AACsearch.

Что поддерживается

• Онлайн-магазины Shopify на тарифах Basic, Shopify, Advanced.
• Товары, варианты, коллекции, остатки.
• Мультивалютные каталоги через Shopify Markets — альтернативные цены попадают в attributes.price_by_currency.
• Локали из Shopify Markets — каждый локалью отдельный документ.

Headless Shopify (Hydrogen / Storefront API) поддерживается, но требует ручной синхронизации со стороны вашего storefront-сервера по гайду Custom Connector.

Архитектура

Коннектор работает как Node.js-сервис рядом с монорепозиторием AACsearch. Роутер монтируется в /api/connectors/shopify:

Магазин Shopify
    │ (admin install + webhooks)
    ▼
packages/shopify-connector/src/router.ts
    ├── /oauth/install         ← старт OAuth
    ├── /oauth/callback        ← приём auth code, шифрование токена
    ├── /webhooks/products/*   ← create/update/delete товара
    ├── /webhooks/inventory/*  ← изменение остатков
    └── /sync/full             ← ручной триггер полной синхронизации
    │
    ▼
Connector API AACsearch

Файлы:

• packages/shopify-connector/src/oauth.ts — поток OAuth 2.0 Shopify
• packages/shopify-connector/src/crypto.ts — шифрование токенов AES-256-GCM
• packages/shopify-connector/src/product-mapper.ts — сущность Shopify → SyncProductInput
• packages/shopify-connector/src/webhooks.ts — HMAC-верификация + дебаунс
• packages/shopify-connector/src/sync.ts — драйверы полной и дельта-синхронизации

Установка (текущее preview)

Публичный листинг в Shopify App Store запланирован на v0.7. До этого — установка через custom app:

1. В админке Shopify откройте Settings → Apps and sales channels → Develop apps → Create an app.
2. Настройте scope Admin API: read_products, read_inventory, read_collections, read_locations.
3. Установите приложение и скопируйте Admin API access token.
4. В панели AACsearch создайте токен коннектора (Connectors → New Connector Token), привязанный к нужному индексу.
5. На сервере AACsearch добавьте в .env параметры коннектора:

SHOPIFY_SHOP_DOMAIN=mystore.myshopify.com
SHOPIFY_ADMIN_ACCESS_TOKEN=shpat_xxxxxxxx
AACSEARCH_CONNECTOR_TOKEN=ss_connector_xxxxxxxx
AACSEARCH_PROJECT_ID=org_xxxxxxxx

6. Зарегистрируйте вебхуки из админки Shopify или через API:

7. Запустите первичную полную синхронизацию из панели AACsearch или вручную:

curl -X POST https://your-aacsearch.example.com/api/connectors/shopify/sync/full \
  -H "Authorization: Bearer $AACSEARCH_CONNECTOR_TOKEN"

Маппинг полей

Маппинг товара Shopify → документ AACsearch — в packages/shopify-connector/src/product-mapper.ts. Ключевые правила:

По умолчанию документы на уровне вариантов не экспортируются — товар уходит одним документом с данными вариантов в attributes. Если магазину нужен поиск по вариантам, собирайте custom connector, который шлёт по документу на вариант.

Надёжность вебхуков

Shopify ретраит вебхуки до 19 раз в течение 48 часов при не-2xx ответе. Коннектор отвечает 200 сразу после успешной HMAC-верификации и постановки в очередь — собственно вызов Connector API идёт асинхронно. Если очередь ингеста AACsearch недоступна, обработчик вебхука логирует ошибку, а периодический job сверки пересылает дельту в следующем плановом запуске.

Провал HMAC — ответ 401 немедленно. Shopify пометит вебхук как failed и сделает backoff. Это правильное поведение — провал верификации значит подменённый payload или ротация secret без обновления коннектора.

Поиск проблем

Roadmap

Текущее preview покрывает OAuth, вебхуки products/inventory, full и delta sync. Запланировано к публичному релизу:

• Установка в один клик из Shopify App Store
• UI для per-market локалей и валют во встроенной админке
• Документы на уровне вариантов как опциональный mapper
• Bulk operations API для каталогов >100k SKU вместо REST-цикла

План реализации — wiki/tasks/cms-platform-expansion.md § A12.

Связанные страницы

• Обзор коннекторов
• Жизненный цикл Connector API
• Custom Connector — для headless Shopify (Hydrogen)
• Диагностика