Коннекторы CMS

Коннектор держит коллекцию в соответствии с каталогом магазина. Магазин никогда не пишет в поисковый индекс напрямую: каждое изменение попадает в журнал коннектора, а очередь применяет журнал к коллекции. Из журнала же собирается индекс при пересборке, поэтому документ, попавший в индекс в обход журнала, при следующей пересборке может из него пропасть. Всё, чем владеет CMS, загружайте через коннектор, а не прямым импортом.

Поддерживаемые платформы

integrations/catalog.json перечисляет модули CMS и их состояние:

API коннекторов принимает также провайдеров bitrix24, woocommerce, yml, sitemap и custom. Провайдер — это метка коннектора: все они пишут через один и тот же вебхук или pull, описанные ниже. Чтобы загрузить фид Яндекс Маркета в коллекцию без модуля, используйте YML-фиды.

Два способа подключить магазин

Ни то, ни другое не является API-ключом. Секрет коннектора не умеет искать и читать настройки, а ключ установки API тенанта отклоняет. Полный ключ магазину в браузере не нужен никогда: главное правило виджета действует и для модулей CMS — браузер обращается только к нашему API и только с ключом области search.

Коннекторы

Создание

В консоли Sources → Add source спрашивает название, целевую коллекцию, провайдера, режим синхронизации, расписание и, в режиме pull, адрес и токен. Из кода — createConnector:

curl -X POST https://api.aacsearch.com/v1/connectors \
  -H "X-NOVA-API-KEY: $NOVA_API_KEY" -H "Content-Type: application/json" \
  -d '{"name":"Main catalogue","collection":"products","provider":"bitrix","sync_mode":"push"}'

Ответ 201 содержит secret подписи один раз; дальше API возвращает только secret_preview, а updateConnector секрет не меняет. Сохраните id и секрет в модуле (connector_id / connector_secret).

В организации может быть один коннектор на пару «коллекция + провайдер». Второй коннектор bitrix для той же коллекции создать нельзя: если модуль потерял секрет, вставьте в модуль id и секрет существующего коннектора из Sources.

Список, просмотр и удаление коннекторов

listConnectors (GET /connectors) выводит все коннекторы организации; getConnector (GET /connectors/{connectorId}) возвращает один — секрет в ответе никогда не приходит, только secret_preview. deleteConnector (DELETE /connectors/{connectorId}) удаляет коннектор, его журнал и его задачи; уже проиндексированные документы остаются в коллекции.

Перед запуском модуль может вызвать handshakeConnector (POST /connectors/handshake), чтобы сообщить, что он такое (cms, version), какое издание маркетплейса он использует (sku), и какие возможности может предоставить. Массив effective в ответе — это пересечение заявленного, допустимого для SKU и покрытого тарифом организации; denied объясняет каждую отклонённую возможность (not_declared, sku или plan, с минимальным тарифом при отказе по плану). Вызывайте его один раз после установки и затем по расписанию — он не хранит состояния, платформа ничего из него не сохраняет.

Push: подписанный вебхук

Магазин отправляет события каталога в POST /connectors/{connectorId}/webhook (ingestConnectorWebhook). API-ключа в запросе нет — он аутентифицируется HMAC:

• X-Signature-Timestamp — Unix-время в секундах; отметка, отличающаяся от часов сервера больше чем на пять минут, отклоняется.
• X-Signature — HMAC-SHA256 в hex от timestamp + "." + сырое тело на секрете коннектора. Подписывайте ровно те байты, которые отправляете: пересборка JSON после подписи её ломает.

BODY='{"events":[{"event":"update","external_id":"42","name":"Дрель аккумуляторная 18 В","price":84.0},{"event":"delete","external_id":"17"}]}'
TS=$(date +%s)
SIG=$(printf '%s.%s' "$TS" "$BODY" | openssl dgst -sha256 -hmac "$CONNECTOR_SECRET" -hex | sed 's/^.* //')
curl -X POST "https://api.aacsearch.com/v1/connectors/$CONNECTOR_ID/webhook" \
  -H "Content-Type: application/json" \
  -H "X-Signature-Timestamp: $TS" -H "X-Signature: $SIG" \
  -d "$BODY"

Тело — один объект события или { "events": [ … ] }:

event, element_id, iblock_id, source_revision и event_id — служебные ключи конверта, в документ они не попадают. Внутри одного пакета для одного external_id побеждает последнее событие.

Ответ считает то, что попало в журнал, и называет задачу применения:

{ "success": true, "data": { "received": 2, "upserted": 1, "deleted": 1, "job_id": "cnjob_…" } }

Что делает задача применения

Каждый принятый пакет становится задачей коннектора (kind: ingest_batch) в очереди. Задача читает перечисленные в ней строки журнала и отправляет обновления в коллекцию импортом emplace — переданные поля меняются, остальные сохраняются (см. действия записи), — а удалённые документы удаляет. Готовой задача считается, только когда движок подтвердил каждый документ. Временная ошибка возвращает задачу в очередь; отсутствие коллекции завершает задачу ошибкой и переводит коннектор в error с текстом. Задачу, простоявшую в queued или processing больше 30 минут, снова ставит в очередь восстановительный cron.

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

Pull: для магазинов без исходящих соединений

Некоторые хостинги закрывают исходящие соединения. С sync_mode: "pull" платформа сама забирает изменения у магазина:

• pull_url — эндпоинт журнала изменений магазина; у модуля Битрикса это https://shop.example/bitrix/tools/aac.search/pull-outbox.php.
• pull_token отправляется в X-AACSEARCH-TOKEN и в Authorization: Bearer. Это собственная опция модуля pull_token, а не API-ключ; API её никогда не возвращает (pull_token_set говорит, сохранена ли она).
• Запрос — GET pull_url?afterSequence=<курсор>&limit=100, ответ — { items: [{ sequence, externalId, action, data }], hasMore, sequence } (action — UPSERT/UPDATE или DELETE/DELETED). Курсор хранит платформа и сдвигает его только после того, как пакет поставлен в очередь.
• За один проход — не больше 10 страниц. Полученные события идут через тот же журнал и очередь задачей kind: pull.

schedule_cron должен совпадать с триггером платформы: */15 * * * * (по умолчанию, если пусто) или 0 3 * * *.

Полная и инкрементальная синхронизация

Вызова «забрать весь каталог» у платформы нет: и то, и другое — события, которые отправляет магазин.

• Инкрементальная — модуль отправляет изменённые и удалённые товары по мере изменения (push) или выкладывает их в журнал изменений (pull).
• Полная — модуль заново отправляет каждый товар событием обновления; повторная отправка неизменённого документа безвредна.

В модуле Битрикса полная выгрузка — это страница Переиндексация, первая выгрузка мастера или команда из консоли; см. первую и дельта-индексацию.

Установки CMS

Установка CMS управляет магазином из консоли, а не со страницы настроек модуля. Её используют модуль Битрикса начиная с 1.8.1 и PrestaShop.

Из консоли для установки ставятся три команды: Reindex catalog (reindex), Sync changes (resync) и Discover catalogs (refresh_capabilities). Модуль берёт одну команду за раз с арендой на 120 секунд, продлевает её и сообщает прогресс; после истечения аренды следующий проход продолжает ту же команду. Команда completed, когда данные дошли до журнала — индекс может ещё обрабатывать их.

Где смотреть статус синхронизации

• Sources (/dashboard/sources) — коннекторы, проблемные первыми: статус (idle, syncing, error, paused), последняя синхронизация, последняя ошибка и метка quiet у включённого источника, молчащего больше суток.
• Карточка источника (/dashboard/sources/{id}) — последние 30 задач (listConnectorJobs, GET /connectors/{id}/jobs; статусы queued, processing, ready, error, со статистикой, ошибкой и постраничным limit) и журнал (listConnectorDocuments, GET /connectors/{id}/documents, постранично через limit/offset); пока задача идёт, экран обновляется сам.
• CMS stores (/dashboard/integrations/cms) — последний контакт установки, применённая ревизия, версии модуля и CMS, последняя ошибка и недавние команды с прогрессом.

Экраны консоли подробно описаны в разделе Консоль → Данные.

Ограничения и коды ошибок

Выключенный или неизвестный коннектор отвечает 404. Трафик коннектора проверяется по состоянию организации, хотя API-ключа в нём нет: приостановленная организация — 402, исчерпанная квота запросов — 429, состояние не удалось проверить — 503. Те же проверки повторяются перед тем, как задача из очереди пишет в коллекцию.

Удаление коннектора удаляет его журнал и задачи; документы, уже лежащие в коллекции, остаются.

Протокол рантайма CMS

Всё выше — то, что вызывает ваш собственный сервер или страница настроек модуля. У модуля есть и собственный протокол «машина-машина» на /cms/runtime/* и /cms/installations/{id}/commands* — heartbeat, аренда и отчёт по трём командам из установок CMS, чтение прав установки и схемы источника, постановка в очередь событий источника, поведенческих событий и рекомендаций для привязанного источника. Он аутентифицируется ключом установки, а не API-ключом, и рассчитан на собственный код модуля CMS, а не на ручной вызов владельцем магазина — полную форму запроса и ответа для каждой операции cms смотрите в справочнике API, а не в этом ручном разборе.