Очередь обмена — жизненный цикл задачи, повторы и агент
Между изменением в одной системе и записью в другую всегда стоит задача в очереди. Это не про ожидание, а про надёжность: изменение сначала фиксируется, потом выполняется. Поэтому сбой МойСклад не мешает менеджеру работать, а неудачную задачу можно повторить.
Откуда берутся задачи
У задачи всего два источника, и оба только ставят её в очередь:
- Событие Битрикс24 — сделку, контакт, компанию или оплату создали либо изменили. Это задача на экспорт. Подробнее — Экспорт.
- Вебхук МойСклад — изменился заказ, контрагент или входящий платёж. Это задача на импорт. Подробнее — Импорт.
Жизненный цикл задачи
- Задача создана. Изменение в CRM или вебхук ставят задачу. Сразу после этого модуль запускает её в фоне — уже после того, как Битрикс24 ответил пользователю, поэтому сохранение сделки не замедляется. Обычно документ уезжает за несколько секунд.
- Задача выполняется. Модуль читает запись в её текущем виде, ищет пару во второй системе и создаёт или обновляет её.
- Итог. Успех — «Выполнена». Сбой (МойСклад не ответил, превышен лимит запросов) — задача возвращается в очередь и будет повторена. После третьей неудачи она переходит в «Ошибка» и больше не повторяется сама.
Что повторяется, а что нет
Повтор помогает только от временных сбоев — тех, что проходят сами:
- МойСклад не ответил: обрыв связи, таймаут;
- превышен лимит запросов к API МойСклад (ответ 429);
- ошибка на стороне сервера МойСклад (ответы 5xx).
Стабильные ошибки повтором не лечатся: МойСклад отклонил запрос (ответы 4xx — недопустимое значение, ограничение тарифа), список длиннее допустимого числа страниц, ответ МойСклад, который модуль не смог разобрать. Если такая ошибка ломает обмен целиком, задача тоже израсходует три попытки и перейдёт в «Ошибка» — устраните причину и запустите её заново.
Если при импорте заказа из МойСклад не удалось загрузить его контрагента, модуль сначала ищет уже связанный контакт или компанию. Не нашёл:
- при временном сбое задача уходит на повтор — сделку без контрагента модуль не создаёт;
- при стабильной ошибке сделка создаётся без контрагента сразу, без лишних попыток, а причина пишется предупреждением в Диагностика → Логи.
Подробный текст ответа МойСклад на неудачный запрос списка пишется в Диагностика → Логи, а в «Последнюю ошибку» задачи попадают только адрес запроса, код ответа и коды ошибок МойСклад.
Три правила, которые объясняют поведение очереди
Модуль не запоминает, как выглядела сделка в момент сохранения: он читает её заново, когда доходит до обработки. Поэтому десять сохранений подряд дают одну задачу, и она выгружает финальное состояние сделки, а не десять промежуточных. А повтор после ошибки никогда не отправит устаревшие данные.
В каждый момент очередь обрабатывает один процесс. Если прогон ещё не закончился, следующий просто пропустит ход. Гонок и двойных заказов из-за параллельной работы не бывает.
Мгновенный фоновый запуск работает, пока обмена ждут не больше десяти записей. При массовом обновлении сделок или шторме вебхуков он отключается, и очередь разбирает агент — порциями по расписанию. Ничего не теряется: фоновый запуск — ускоритель, а не единственный путь.
Ритм и лимиты
| Параметр | Значение | Что это значит |
|---|---|---|
| Фоновый запуск | сразу | Задача стартует, не дожидаясь агента |
| Проход агента | примерно раз в минуту | Максимальная задержка, если фоновый запуск не сработал |
| Задач за проход | 10 | Остальные ждут следующего прохода |
| Попыток на задачу | 3 | После третьей неудачи — «Ошибка» |
| Пауза между попытками | без нарастания | Повтор — на ближайшем проходе агента, три попытки укладываются в пару минут |
| Порог ошибок | 100 за час | Агент останавливается целиком |
| Хранение истории | 72 часа | Завершённые задачи удаляются автоматически |
Эти значения встроены в модуль и в интерфейсе не настраиваются.
Состояния задачи
Эти подписи вы увидите в колонке «Состояние задачи» на странице Очередь обмена.
| Состояние | Что значит | Нужно ли вмешательство |
|---|---|---|
| В очереди | Задача создана и ждёт запуска. Попыток ещё не было | Нет |
| Выполняется | Задачу прямо сейчас обрабатывает агент. Кнопки действий заблокированы | Нет |
| Повтор после ошибки | Попытка закончилась ошибкой, задача вернулась в очередь и будет повторена | Посмотреть, если повторяется долго |
| Отложена | Задача в очереди, но её запуск назначен на будущее время | Нет |
| Выполнена | Задача завершена успешно. Хранится в истории 72 часа | Нет |
| Ошибка | Все попытки исчерпаны, задача больше не повторяется. Причина — в «Последней ошибке» | Да |
| Отменена | Задача снята с обработки и не будет выполнена | Да |
Состояние описывает судьбу задачи, а не результат обмена. Если модуль решил, что запись обменивать нельзя — не настроен тип документа, сделка не прошла фильтр, обмен этим документом выключен, — задача честно отработает и станет «Выполнена», но в МойСклад ничего не появится. Когда данных нет, а ошибок в очереди тоже нет, причину ищите в Логах (Диагностика → Логи).
Как пользоваться самой страницей — фильтрами, вкладками Активные и Завершённые, карточкой задачи — описано в разделе Очередь обмена.
Агент очереди
Агент — это фоновый обработчик Битрикс24, который по расписанию разбирает очередь. Модуль устанавливает его сам при первой же задаче.
Если агенты портала работают «на хитах», очередь будет двигаться только при заходах пользователей на сайт, а задачи, пропущенные фоновым запуском, могут ждать часами. Переведите агенты на cron — см. Настройка агентов на cron.
Когда очередь останавливается сама
- Нет доступа к МойСклад. Если не заданы данные подключения или МойСклад их не принимает, агент не берёт задачи в работу и не тратит их попытки. На портале появляется уведомление. Как только подключение восстановлено, очередь продолжает работу сама.
- Серия ошибок. Сто задач в «Ошибке» за час — и агент выключается. Обычно это значит, что сломалось что-то общее: истёк токен, недоступен МойСклад, разъехалась настройка. Повторять бессмысленно, поэтому модуль перестаёт нагружать МойСклад. Устраните причину, разберите ошибочные задачи на странице Очередь обмена и включите агент на Дашборде.
- Зависшая задача. Если обработка оборвалась на середине (например, сервер перезапустился), агент на следующем проходе вернёт задачу в оборот — навсегда в «Выполняется» она не останется.
Ручные действия
| Действие | Где | Что делает |
|---|---|---|
| Вызвать агент очереди | Над таблицей очереди | Выполняет проход прямо сейчас, не дожидаясь минуты. Удобно при настройке |
| Выполнить принудительно | В строке задачи | Прогоняет задачу немедленно, в обход очереди |
| Удалить | В строке задачи | Убирает задачу; обмен по ней не состоится |
Задача выполняется в обход очереди. Если обмен прошёл, задача убирается из очереди; если упал — остаётся в очереди и дальше повторяется по обычным правилам. Без устранения причины вы просто получите тот же сбой ещё раз — сначала исправьте настройку, потом запускайте.
Куда смотреть, если…
| Симптом | Где смотреть | Обычная причина |
|---|---|---|
| Задач нет вообще, хотя сделку меняли | Диагностика → События модуля | Отключено событие CRM — изменение не создаёт задачу |
| Задачи копятся и не выполняются | Дашборд, карточка агентов очереди | Агент неактивен — скорее всего, остановлен порогом ошибок |
| Задача «Выполнена», а в МойСклад пусто | Диагностика → Логи | Не хватает настройки или запись не прошла фильтр |
| Из МойСклад ничего не приходит | Общие параметры → Вебхуки МойСклад | Вебхуки не установлены или «покраснели» |