Синхронизация коннектора

Коннектор считается «онлайн», когда сервер получил от него heartbeat в течение последних 5 минут. «Неизвестно» — между 5 и 30 минутами. «Офлайн» — более 30 минут.

Если ваш коннектор неожиданно переходит в офлайн, пройдите по этим проверкам.

Симптомы

Дерево решений

Статус коннектора = офлайн?
  ├─ Вызов heartbeat возвращает 200?
  │  ├─ нет  → см. [Ошибки аутентификации](/troubleshooting/auth-errors)
  │  └─ да  → процесс коннектора молча падает; проверьте логи процесса
  └─ Задержка синхронизации статуса; обновите через 2 мин

Задача синхронизации зависла в "running"?
  ├─ Задача > 30 мин? → вероятно, троттлинг воркера; см. [Ошибки индексации](/troubleshooting/ingest-failures)
  └─ Задача < 30 мин? → ждите; большие каталоги требуют времени

Данные устарели несмотря на "онлайн"?
  ├─ Был ли сброшен дельта-курсор?
  └─ Доходят ли изменения документов до коннектора вообще?

Проверка 1: heartbeat работает от начала до конца

С хоста, на котором работает коннектор:

curl -i -X POST https://app.aacsearch.com/api/connectors/<connectorId>/heartbeat \
  -H "Authorization: Bearer ss_connector_..." \
  -H "Content-Type: application/json"

Ожидаемый ответ:

HTTP/1.1 200 OK
{ "status": "ok", "timestamp": "2026-05-11T12:00:00.000Z" }

Если 401, см. Ошибки аутентификации. Если 200, но дашборд всё ещё показывает офлайн, подождите 2 минуты — дашборд кеширует lastUsedAt для производительности.

Проверка 2: рукопожатие успешно

Каждый коннектор должен вызывать handshake при запуске. Перезапустите его вручную:

curl -X POST https://app.aacsearch.com/api/connectors/handshake \
  -H "Authorization: Bearer ss_connector_..." \
  -H "Content-Type: application/json" \
  -d '{ "moduleVersion": "1.0.0", "platform": "prestashop" }'

Ожидается 200 с projectId, indexSlug, метаданными connector. Возвращённый здесь projectId — это то, что вы передаёте как :projectId в последующих вызовах синхронизации.

Если ответ говорит, что коннектор disabled или not_found, повторно включите его из Коннекторы → коннектор → Настройки.

Проверка 3: жизненный цикл задачи синхронизации

Задача синхронизации проходит через:

pending → running → completed (или failed)

curl -X GET https://app.aacsearch.com/api/v1/projects/<projectId>/sync-jobs \
  -H "Authorization: Bearer aa_admin_..."

Строки задачи включают status, documentsTotal, documentsProcessed, error, startedAt, completedAt.

Проверка 4: полный vs дельта-режим

Разные коннекторы поддерживают разные режимы. Ответ handshake объявляет какие:

{
  "connector": {
    "id": "prestashop",
    "syncModes": ["full", "delta"]
  }
}

Если ваш коннектор поддерживает только full, а вы вызываете sync/delta, запрос возвращает 400 sync_mode_not_supported. Переключитесь на sync/full (медленнее, но работает всегда).

Для высокочастотного отслеживания изменений sync/delta — правильный выбор: он отправляет только документы, изменённые с последнего курсора.

Проверка 5: дельта-курсор застрял

sync/delta управляется курсором, хранящимся в коннекторе. Если курсор неверен (например, сброшен на далеко будущую метку времени), ничего нового не будет подобрано.

Сбросьте курсор из собственного UI администрирования коннектора (каждый CMS-модуль имеет кнопку «принудительная полная повторная синхронизация») или вызовите sync/full один раз для заполнения.

# Сброс и переустановка базовой линии
curl -X POST https://app.aacsearch.com/api/projects/<projectId>/sync/full \
  -H "Authorization: Bearer ss_connector_..." \
  -H "Content-Type: application/json" \
  -d '{ "products": [...] }'

После успешного sync/full локальный курсор коннектора должен продвинуться до «сейчас».

Проверка 6: сетевая доступность

Если хост, на котором работает коннектор, находится в частной сети, он должен иметь возможность достичь https://app.aacsearch.com исходяще на порт 443. Проверьте:

curl -v https://app.aacsearch.com/api/health
# ожидается HTTP/1.1 200 OK

Если не удаётся, файрвол или прокси блокирует исходящий трафик. Добавьте app.aacsearch.com в белый список.

Проверка 7: область действия токена коннектора

Токен коннектора должен иметь область connector_write. Если вы по ошибке создали ключ ss_search_* и попытались использовать его как токен коннектора, каждый вызов коннектора вернёт 403 forbidden.

// Серверная сторона, с административным ключом
const keys = await admin.listKeys();
const yours = keys.find((k) => k.id === "key_...");
console.log(yours.scopes); // должно содержать "connector_write"

Создайте правильный тип в Поиск → API-ключи → Создать ключ → тип "Connector". См. API-ключи.

Частые ошибки задач

Матрица решений

Диагностический пакет

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

• Жизненный цикл API коннектора — полный справочник эндпоинтов
• Онбординг коннектора
• Ошибки индексации
• Ошибки аутентификации