Надёжные интеграции на 1С-Битрикс: очереди, идемпотентность и повторы

Интеграция, которая «работает на демонстрации», и интеграция, которая надёжно работает под нагрузкой год за годом, — это два разных инженерных изделия. Первая просто дёргает внешний API и радуется ответу 200. Вторая исходит из того, что сеть моргает, чужие сервисы падают, ответы теряются, а сообщения приходят по два раза — и всё равно не теряет ни одного заказа и не плодит дублей. Эта статья — о том, как сделать вторую: про очереди, идемпотентность и повторы, то есть про инженерную основу надёжных интеграций Битрикс.

Материал — практическая выжимка из наших проектов по интеграции 1С-Битрикс с внешними системами и разработке REST API для 1С-Битрикс. Без академизма: разберём, почему прямые синхронные вызовы опасны, как устроены очереди задач, что такое идемпотентность, как правильно делать ретраи с backoff и зачем нужно логирование интеграций и мониторинг. Примеры кода — иллюстративные, на псевдокоде и D7, чтобы показать структуру, а не готовую библиотеку.

Почему синхронные вызовы внешних API опасны

Самая распространённая архитектурная ошибка в интеграциях выглядит невинно: покупатель нажимает «Оформить заказ», и прямо в обработчике этого действия код синхронно вызывает внешний API — например, создаёт сделку в CRM или резервирует товар на складе. На тесте, когда внешний сервис отвечает мгновенно, всё выглядит идеально. Проблемы начинаются в бою, потому что вы связали успех своей операции с доступностью чужой системы, которой вы не управляете.

Представьте, что в момент оформления внешний сервис недоступен: идут работы, кончилась квота, оборвалась сеть, база на его стороне под блокировкой. Синхронный вызов повисает и ждёт таймаута. Пока он ждёт, покупатель смотрит на «крутилку», а ваш веб-сервер держит занятым процесс и соединение. Дальше возможны два одинаково плохих исхода. Либо вы обернули вызов так, что ошибка внешнего API валит всё оформление — и покупатель не может купить из-за того, что упала чужая CRM. Либо заказ у вас создаётся, но отправка во внешнюю систему падает, и данные просто теряются: заказ есть на сайте, но его нет в CRM, и никто об этом не узнает, пока не хватятся.

Есть и более коварный сценарий — «неопределённость доставки». Вы отправили запрос, внешняя система его приняла и создала сущность, но ответ до вас не дошёл: сеть оборвалась в самый неподходящий момент. Ваш код видит ошибку, считает, что не получилось, и при повторной попытке создаёт вторую сущность. Так рождаются задвоенные заказы и сделки — классический симптом синхронной интеграции без защиты.

Отсюда главный принцип надёжных интеграций: приём данных и их доставку во внешнюю систему нужно разделять во времени. Пользовательское действие должно завершаться быстро и только на вашей стороне — вы приняли заказ, записали его к себе, поставили в очередь задание «отправить в CRM» и отпустили покупателя. А сам обмен выполняется потом, фоново, с повторами и журналом. Всё остальное в этой статье — детали того, как правильно устроить это «потом».

Что значит «надёжная интеграция»

Прежде чем строить, договоримся о критериях. Надёжная интеграция — это не «та, что не падает» (падают все), а та, что не теряет данные и не создаёт дублей несмотря на сбои. Из этого вырастают несколько конкретных свойств, к которым мы будем возвращаться на протяжении всей статьи.

• Гарантия доставки. Если данные приняты вашей системой, они рано или поздно дойдут до приёмника — даже если тот сейчас лежит. Обычно это модель «хотя бы один раз» (at-least-once): лучше доставить дважды и отсеять дубль, чем потерять.
• Идемпотентность. Повторная доставка одного и того же сообщения не меняет итог. Это плата за модель at-least-once и обязательное условие безопасных повторов.
• Устойчивость к сбоям приёмника. Недоступность внешней системы не ломает ваши операции и не теряет очередь — задания ждут и уходят позже.
• Ограниченность повторов. Повторы не бесконечны и не мгновенны: backoff и лимит попыток, а безнадёжное уходит в dead-letter, а не крутится вечно.
• Наблюдаемость. По журналу и метрикам всегда видно, что ушло, что упало, сколько было попыток и где сейчас затор. Без этого надёжность недоказуема.
• Согласованность. Данные на обеих сторонах в итоге сходятся (eventual consistency), а порядок обрабатывается предсказуемо там, где он важен.

Обратите внимание: почти все эти свойства недостижимы при синхронной модели «вызвал и забыл». Они требуют промежуточного звена, которое хранит задания, управляет повторами и ведёт журнал. Этим звеном и является очередь.

Синхронно против очереди: сравнение

Сведём разницу между двумя подходами в таблицу — она хорошо показывает, почему очередь почти всегда выигрывает за пределами простейших случаев.

Единственная честная область применения синхронного вызова — операции, где нужен немедленный ответ пользователю и где сбой не приводит к потере (например, проверка промокода или запрос цены доставки в реальном времени). Но и там вызов нужно обкладывать таймаутом и запасным поведением. Всё, что связано с записью бизнес-данных — заказы, оплаты, остатки, статусы, — идёт через очередь.

Очереди задач: где хранить обмен

Очередь задач — это буфер между «событием у вас» и «отправкой наружу». Событие произошло — вы кладёте в очередь задание с описанием, что и куда отправить. Отдельный фоновый процесс достаёт задания и выполняет обмен, отмечая успех или планируя повтор. Такое разделение и даёт все перечисленные выше свойства надёжности. Вопрос лишь в том, где физически хранить очередь.

Очередь в базе данных

Для подавляющего большинства магазинов на 1С-Битрикс правильный ответ — таблица в БД, реализованная как ORM-сущность D7. Плюсы: данные переживают перезапуск и деплой, доступны транзакции, легко посмотреть и отредактировать задание руками, не нужна новая инфраструктура. Минусы — ограниченная пропускная способность по сравнению со специализированными брокерами, но для десятков тысяч обменов в сутки этого с запасом хватает.

Файловая очередь

Складывать задания в файлы — соблазнительно просто, но плохо: тяжело обеспечить атомарность и защиту от гонок при нескольких обработчиках, легко получить повреждённые или потерянные файлы. Файловую очередь стоит рассматривать разве что как временный костыль, а не как основу.

Брокеры сообщений

RabbitMQ, Kafka, Redis-очереди и облачные аналоги — это специализированные системы, заточенные под высокую пропускную способность, доставку с гарантиями, маршрутизацию и несколько потребителей. Они мощны, но добавляют инфраструктуру, которую нужно поднимать, мониторить и обслуживать. Это оправдано на больших объёмах и в сложных топологиях; подробнее — в разделе про брокеры ниже.

Очередь в таблице БД на D7

Покажем структуру очереди на собственной ORM-сущности D7. Это не готовый модуль, а скелет, который вы адаптируете под проект. Сначала — таблица заданий с ключевыми полями: тип обмена, полезная нагрузка, статус, число попыток, время следующей попытки и ключ идемпотентности.

// Поля таблицы очереди (ORM-сущность D7), условно:
// ID              — первичный ключ
// EVENT_TYPE      — тип обмена: 'order.export', 'stock.sync' и т.п.
// PAYLOAD         — сериализованные данные (JSON)
// IDEMPOTENCY_KEY — уникальный ключ идемпотентности (индекс UNIQUE)
// STATUS          — 'new' | 'processing' | 'done' | 'failed' | 'dead'
// ATTEMPTS        — сколько попыток уже сделано
// NEXT_RETRY_AT   — когда можно повторить (для backoff)
// LAST_ERROR      — текст последней ошибки
// CREATED_AT / UPDATED_AT — метки времени

// Постановка задания в очередь при событии:
function enqueue($type, array $data, $idempotencyKey) {
    // Если задание с таким ключом уже есть — не дублируем (дедупликация на входе)
    $exists = QueueTable::getRow([
        'filter' => ['=IDEMPOTENCY_KEY' => $idempotencyKey],
        'select' => ['ID'],
    ]);
    if ($exists) {
        return (int)$exists['ID'];
    }
    $res = QueueTable::add([
        'EVENT_TYPE'      => $type,
        'PAYLOAD'         => json_encode($data, JSON_UNESCAPED_UNICODE),
        'IDEMPOTENCY_KEY' => $idempotencyKey,
        'STATUS'          => 'new',
        'ATTEMPTS'        => 0,
        'NEXT_RETRY_AT'   => new \Bitrix\Main\Type\DateTime(),
        'CREATED_AT'      => new \Bitrix\Main\Type\DateTime(),
    ]);
    return $res->getId();
}

Обработчик очереди забирает пачку готовых к отправке заданий (тех, у кого статус new/failed и наступило NEXT_RETRY_AT), помечает их processing, чтобы их не подхватил параллельный обработчик, и выполняет обмен. Важна защита от одновременного захвата одной записи двумя процессами — её решают на уровне БД (например, обновлением статуса с проверкой прежнего значения).

function processBatch($limit = 50) {
    $now = new \Bitrix\Main\Type\DateTime();
    $rows = QueueTable::getList([
        'filter' => [
            '@STATUS'        => ['new', 'failed'],
            '<=NEXT_RETRY_AT' => $now,
        ],
        'order' => ['ID' => 'ASC'],
        'limit' => $limit,
    ])->fetchAll();

    foreach ($rows as $job) {
        // Атомарно «захватываем» задание: перевод new/failed -> processing.
        // Если апдейт не затронул строку — её уже взял другой процесс, пропускаем.
        if (!claimJob((int)$job['ID'])) {
            continue;
        }
        try {
            $result = sendToExternal($job['EVENT_TYPE'], json_decode($job['PAYLOAD'], true), $job['IDEMPOTENCY_KEY']);
            markDone((int)$job['ID'], $result);
        } catch (RetryableException $e) {
            scheduleRetry($job, $e);      // backoff + инкремент попыток
        } catch (\Throwable $e) {
            markFailedPermanent($job, $e); // не повторяем, готовим к dead-letter
        }
    }
}

Это ядро надёжной интеграции: постановка в очередь с дедупликацией на входе, атомарный захват задания, разделение ошибок на повторяемые и постоянные, планирование повтора. Дальше мы наполним каждый из этих механизмов деталями — как считать backoff, что писать в журнал, когда уводить в dead-letter.

Агенты, cron и фоновые процессы Битрикса

Кто-то должен регулярно запускать processBatch(). В 1С-Битрикс есть два штатных механизма фонового выполнения, и у каждого своя область.

Агенты

Агенты — встроенный планировщик Битрикса: функция или метод, который платформа вызывает по расписанию. Плюс — не нужен доступ к системному cron, всё настраивается внутри. Важный нюанс: по умолчанию агенты запускаются «на хите», то есть их выполнение привязано к посещениям сайта. Это делает их капризными на низком трафике (агент запустится, только когда кто-то зайдёт) и потенциально тяжёлыми для страницы, на хите которой они сработали. Для обмена агенты годятся, но лучше переводить их запуск на cron-режим.

Cron

Системный cron дёргает agent.php (или ваш отдельный скрипт) по стабильному расписанию, независимо от трафика. Это надёжнее для фоновой обработки очереди: обмен идёт по часам, а не по посещениям. Стандартная практика — перевести агенты Битрикса в режим запуска на cron и/или сделать отдельный cron-скрипт, который вызывает обработчик очереди раз в минуту.

Брокеры сообщений: обзор

Когда объёмы обмена перерастают возможности очереди в БД, в игру вступают брокеры сообщений. Это не «более правильный» способ, а инструмент под другие задачи — разберём обзорно, чтобы вы понимали, когда он нужен.

• RabbitMQ. Классический брокер очередей с гибкой маршрутизацией, подтверждениями доставки (ack), отложенными сообщениями и dead-letter «из коробки». Хорош, когда нужны надёжные очереди и несколько типов потребителей.
• Apache Kafka. Не столько очередь, сколько распределённый журнал событий с очень высокой пропускной способностью и хранением истории. Силён там, где событий много, нужен строгий порядок в рамках раздела (partition) и несколько независимых читателей одного потока.
• Redis-очереди. Лёгкий вариант на базе Redis: быстро, просто, но гарантии слабее, чем у полноценных брокеров, и нужно аккуратно продумывать надёжность.

Общая мысль: брокер снимает с вас реализацию доставки, повторов и маршрутизации, но добавляет инфраструктуру, которую нужно разворачивать, мониторить и обслуживать. Для магазина на Битриксе это оправдано, когда обмен становится по-настоящему интенсивным или топология сложной (много систем, много типов событий, требования к порядку и масштабированию). До этого порога очередь в БД проще, дешевле и понятнее в отладке. Ключевые принципы надёжности — идемпотентность, backoff, dead-letter, журнал — одинаковы и там, и там; меняется лишь транспорт.

Идемпотентность и ключ идемпотентности

Идемпотентность — центральное понятие надёжного обмена. Операция идемпотентна, если её повторное выполнение даёт тот же результат, что и однократное. В интеграциях это означает: сколько бы раз ни пришло сообщение «создать заказ №10245», в приёмнике должен появиться ровно один заказ.

Зачем это нужно? Потому что при модели доставки «хотя бы один раз» (а это самая практичная модель) повторы неизбежны, а значит, неизбежны и повторные доставки. Вы отправили запрос, приёмник его выполнил, но ответ потерялся — и повтор доставит то же сообщение снова. Без защиты появится дубль. Идемпотентность — это то, что делает повторы безопасными.

Ключ идемпотентности

Практический механизм — ключ идемпотентности: стабильный уникальный идентификатор, который вы присваиваете обмену один раз и передаёте при каждой попытке. Ключом может быть номер заказа, UUID события, хеш от бизнес-содержимого. Приёмник запоминает обработанные ключи. Приходит сообщение с уже известным ключом — приёмник не выполняет операцию повторно, а возвращает результат прежней. Приходит новый ключ — выполняет и запоминает.

// На стороне приёмника (псевдокод):
function handle($idempotencyKey, $payload) {
    $seen = IdempotencyStore::get($idempotencyKey);
    if ($seen !== null) {
        // Уже обрабатывали — возвращаем прежний результат, ничего не создаём
        return $seen['result'];
    }
    $result = doBusinessOperation($payload); // например, создать заказ
    IdempotencyStore::save($idempotencyKey, $result);
    return $result;
}

Upsert по внешнему ключу

Если вы владеете логикой приёмника, ещё надёжнее — upsert по внешнему ключу: передавайте свой стабильный идентификатор (номер заказа с сайта) и на приёмнике делайте «если сущность с таким ключом есть — обновить, иначе создать». Тогда повтор не создаёт дубль, а просто перезаписывает то же самое теми же данными. Это защищает даже в условиях гонок надёжнее, чем «проверить-потом-создать».

Дедупликация сообщений

Идемпотентность защищает результат операции, а дедупликация работает раньше — на уровне самих сообщений. Это фильтр, который отсекает повторные сообщения до того, как они вообще дойдут до бизнес-логики. Оба механизма дополняют друг друга: дедупликация снимает лишнюю работу, идемпотентность страхует, если дубликат всё же просочился.

Дедуплицировать можно на двух концах. На входе в очередь — как в примере с enqueue() выше: перед добавлением задания проверяем, нет ли уже задания с таким ключом идемпотентности; уникальный индекс в БД гарантирует, что двух одинаковых не появится даже при гонке. На стороне приёмника — храним обработанные ключи и отбрасываем повторы.

Практические тонкости, о которых легко забыть:

• Окно дедупликации. Хранить обработанные ключи вечно нельзя — таблица разрастётся. Обычно хранят за разумный период (дни-недели), которого заведомо хватает, чтобы все возможные повторы уже пришли. Период выбирают исходя из максимально возможной задержки повтора.
• Стабильность ключа. Ключ должен зависеть только от бизнес-смысла, а не от времени или случайности при каждой попытке. Если вы генерируете новый ключ на каждый повтор — дедупликация бесполезна.
• Уникальный индекс как гарант. Проверка «есть ли уже такой» в коде уязвима к гонкам; надёжнее опереться на UNIQUE-индекс в БД и корректно обработать ошибку нарушения уникальности как «уже есть».

Ретраи с экспоненциальной задержкой

Повторы — механизм, который превращает временный сбой в незаметную задержку. Но повторять нужно правильно. Наивный подход «повторять сразу и в цикле» вредит: если приёмник перегружен, шквал мгновенных повторов только добивает его, забивает пул соединений и вызывает блокировки по лимитам. Правильная стратегия — экспоненциальная задержка (backoff).

Идея проста: с каждой неудачной попыткой пауза перед следующей растёт. Например, 1, 2, 4, 8, 16, 32 секунды — и так до верхнего предела. Это даёт приёмнику время восстановиться и распределяет нагрузку во времени. К backoff почти всегда добавляют jitter — случайный разброс паузы, чтобы множество клиентов, упавших одновременно, не ударили повторно синхронно (эффект «громового стада»).

// Вычисление задержки перед следующей попыткой:
function nextDelaySeconds($attempt) {
    $base = 1;            // базовая пауза, сек
    $cap  = 600;          // потолок паузы, сек (10 минут)
    $exp  = $base * (2 ** $attempt);        // 1,2,4,8,16,...
    $exp  = min($exp, $cap);                // не растём бесконечно
    $jitter = mt_rand(0, (int)($exp * 250)) / 1000; // случайный разброс до 25%
    return $exp + $jitter;
}

function scheduleRetry($job, $error) {
    $attempt = (int)$job['ATTEMPTS'] + 1;
    if ($attempt > MAX_ATTEMPTS) {          // например, 8
        moveToDeadLetter($job, $error);     // безнадёжное — в мёртвую очередь
        return;
    }
    $delay = nextDelaySeconds($attempt);
    QueueTable::update((int)$job['ID'], [
        'STATUS'        => 'failed',
        'ATTEMPTS'      => $attempt,
        'NEXT_RETRY_AT' => addSeconds(new \Bitrix\Main\Type\DateTime(), $delay),
        'LAST_ERROR'    => mb_substr((string)$error, 0, 1000),
    ]);
}

Не менее важно, что именно повторять. Повторять имеет смысл только временные (retryable) ошибки. Постоянные ошибки повтором не исправить — их нужно логировать и разбирать.

Таймауты: не ждать вечно

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

Таймаутов на самом деле два, и путать их нельзя:

• Таймаут соединения (connect timeout) — сколько ждём установления TCP-соединения. Если приёмник недоступен, это выясняется быстро; держать его большим смысла нет (единицы секунд).
• Таймаут ответа (read/response timeout) — сколько ждём ответ после отправки запроса. Его выбирают исходя из реальной скорости приёмника, но всегда конечным: лучше получить таймаут и повторить позже, чем висеть минутами.

Практика: ставьте таймауты осознанно, а не «по умолчанию из библиотеки» (там они часто огромны или отсутствуют). Таймаут по ответу — это повторяемая ошибка: вызов не удался, задание уходит на backoff и повторяется. Важный нюанс идемпотентности: по таймауту вы не знаете, выполнил ли приёмник операцию (запрос мог дойти, а ответ — нет), поэтому повтор обязан быть безопасным. Именно здесь ключ идемпотентности окупается на сто процентов.

Circuit breaker: предохранитель

Когда внешний сервис не просто моргнул, а лежит основательно, продолжать долбить его повторами — расточительно: вы тратите ресурсы обработчика на заведомо провальные вызовы и мешаете сервису подняться. Здесь помогает шаблон circuit breaker («предохранитель»), заимствованный из электротехники: если направление стабильно «искрит» ошибками, цепь размыкается и вызовы временно прекращаются.

Предохранитель обычно имеет три состояния:

• Закрыт (closed) — нормальный режим, вызовы идут. Ошибки считаются; пока их немного, всё работает.
• Разомкнут (open) — доля ошибок за окно превысила порог, и вызовы к этому сервису на время прекращаются. Задания либо ждут, либо сразу помечаются на повтор позже, не тратя сеть.
• Полуоткрыт (half-open) — по истечении паузы пропускается пробный вызов. Успех — цепь замыкается обратно; неудача — снова размыкается на паузу.

Для небольшого магазина с редким обменом полноценный circuit breaker часто избыточен — хватает таймаутов и backoff. Но когда внешних систем несколько и обмен интенсивный, предохранитель окупается: он предотвращает «эффект домино», когда одна упавшая система через общий пул ресурсов тормозит обмены со всеми остальными. Упрощённую версию легко встроить в обработчик очереди: если по конкретному направлению за короткое окно накопилось много ошибок — приостановить его отправку на несколько минут, продолжая обрабатывать остальные направления. Это уже даёт большую часть пользы без сложной машины состояний.

Dead-letter: что делать с неотправленным

Даже при идеальных повторах часть сообщений доставить не удастся: приёмник лежит слишком долго, данные оказались невалидными, событие «ядовитое» и ломает обработчик снова и снова. Такие сообщения нельзя терять молча и нельзя оставлять в основной очереди — иначе они будут бесконечно крутиться и мешать остальным. Для них существует dead-letter («мёртвая очередь»).

Dead-letter — это отдельный статус или отдельная таблица, куда переезжают задания, исчерпавшие лимит повторов, и заведомо необрабатываемые сообщения. Смысл — сохранить данные и сделать проблему видимой, а не потерять её. Работают с dead-letter так:

1. Фиксируйте причину. Вместе с сообщением сохраняйте последнюю ошибку, число попыток и время — чтобы инженер понял, что случилось, не гадая.
2. Шлите алерт. Попадание в dead-letter — событие, требующее внимания. Без уведомления «мёртвая очередь» превращается в тихую свалку потерянных данных.
3. Разбирайте и чините. Инженер устраняет причину: ждёт восстановления внешней системы, правит данные, исправляет баг обработчика.
4. Переотправляйте (replay). После починки верните сообщение в основную очередь. Именно здесь снова спасает идемпотентность: повторная обработка не создаст дубля.
5. Анализируйте закономерности. Если в dead-letter регулярно падает один и тот же тип сообщений — это не разовый сбой, а дефект интеграции, который нужно устранять в коде.

Важно отделять «ядовитые» сообщения от временных сбоев. Если сообщение падает из-за невалидных данных, оно будет падать при любом числе повторов — его нужно уводить в dead-letter сразу, не тратя попытки. А вот сообщение, упавшее из-за недоступности приёмника, заслуживает всех повторов и попадёт в dead-letter только после их исчерпания.

Логирование каждого обмена

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

Что стоит писать по каждому обмену:

• Идентификатор и ключ идемпотентности — чтобы связать все попытки одного обмена в одну историю.
• Направление и тип — куда и что отправляли (например, order.export → CRM).
• Запрос и ответ — тело (с маскированием секретов и персональных данных), код ответа, длительность.
• Статус и попытки — успех/ошибка, номер попытки, текст ошибки, время следующего повтора.
• Метки времени — когда поставлено в очередь, когда отправлено, когда завершено.

function logExchange(array $entry) {
    ExchangeLogTable::add([
        'IDEMPOTENCY_KEY' => $entry['key'],
        'DIRECTION'       => $entry['direction'],   // 'out' | 'in'
        'EVENT_TYPE'      => $entry['type'],
        'REQUEST'         => maskSecrets($entry['request']),
        'RESPONSE'        => maskSecrets($entry['response']),
        'HTTP_CODE'       => $entry['code'],
        'ATTEMPT'         => $entry['attempt'],
        'STATUS'          => $entry['status'],       // 'ok' | 'retry' | 'fail'
        'DURATION_MS'     => $entry['duration'],
        'CREATED_AT'      => new \Bitrix\Main\Type\DateTime(),
    ]);
}

Пара практических правил. Во-первых, маскируйте секреты и персональные данные в журнале: токены, пароли, полные номера карт там храниться не должны. Во-вторых, не давайте журналу расти бесконечно — настройте ротацию и удаление старых записей, иначе таблица логов однажды станет тяжелее самих данных. Оптимально хранить подробный журнал за недавний период и агрегаты (счётчики успехов/ошибок) — за длинный.

Мониторинг и алерты

Журнал отвечает на вопрос «что случилось с конкретным обменом», а мониторинг — на вопрос «здорова ли интеграция в целом прямо сейчас». Без мониторинга проблемы всплывают самым дорогим способом — от клиента, который заметил, что заказы не доходят. Цель — узнавать о сбое раньше, чем о нём узнает бизнес.

Метрики, за которыми стоит следить:

• Глубина очереди. Сколько заданий ждёт отправки. Резкий рост — сигнал, что обработчик не справляется или приёмник лёг.
• Возраст старейшего задания. Если самое старое задание в очереди «застряло» надолго — обмен встал, даже если новые проходят.
• Доля ошибок и повторов. Всплеск ошибок по направлению — приёмник деградирует.
• Размер dead-letter. Любой рост требует внимания: это уже потерянные (пока) данные.
• Задержка доставки. Сколько в среднем проходит от постановки в очередь до успешной отправки.

На критичные пороги вешают алерты в каналы, которые реально читают: мессенджер дежурной команды, почта, система инцидентов. Ключевой принцип — алерт должен быть действием, а не шумом. Если уведомления приходят по любому чиху, их перестают читать, и настоящий сбой теряется в потоке. Алертите на то, что действительно требует вмешательства: непустой dead-letter, застрявшая очередь, длительный всплеск ошибок.

Порядок событий и согласованность

Как только обмен становится асинхронным, всплывает вопрос порядка: события могут прийти к приёмнику не в той последовательности, в какой произошли. «Изменение заказа» способно обогнать «создание заказа», а старое обновление статуса — прийти после нового. Если обработчик наивно применяет всё подряд, данные на сторонах разъезжаются.

Абсолютный глобальный порядок в распределённой системе дорог и почти никогда не нужен. На практике применяют три приёма, которых хватает подавляющему большинству магазинов.

• Устойчивость к перестановкам. Проектируйте обработчик так, чтобы он корректно реагировал на «раннее» событие: либо создавал недостающую сущность, либо откладывал обработку до появления предшественника.
• Версионирование. К каждому событию прикрепляйте номер версии или метку времени. Приёмник игнорирует обновление, если у него уже есть более свежее — так старое событие не затирает новое.
• Порядок в рамках ключа. Там, где последовательность важна (все события одного заказа), гарантируйте порядок только внутри ключа: события одного заказа обрабатываются строго по очереди, а разные заказы — параллельно. Это даёт согласованность без единой очереди-«бутылочного горлышка».

Отдельно держите в голове модель итоговой согласованности (eventual consistency): в асинхронном обмене стороны на короткое время расходятся и сходятся чуть позже, когда все сообщения доставлены. Это нормально и правильно — важно лишь, чтобы расхождение было временным и ограниченным, а бизнес-логика была к нему готова (например, не считала заказ «пропавшим» в первые секунды после оформления). О том, как это стыкуется с событийной моделью Битрикса, — в статье про события и обработчики в Битрикс.

Вебхуки: подтверждение и повторная доставка

Отдельного разговора заслуживают входящие вебхуки — когда уже вы выступаете приёмником и внешняя система (или сам Битрикс) шлёт вам события. Здесь надёжность требует правильного поведения обработчика, иначе события теряются или дублируются на ровном месте.

Быстрое подтверждение

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

Повторная доставка и её последствия

Почти все системы, шлющие вебхуки, работают по модели «хотя бы один раз»: не получив вовремя успешный ответ, они повторяют доставку. Значит, одно и то же событие придёт к вам несколько раз — это норма, а не аномалия. Отсюда обязательное требование: обработчик вебхука должен быть идемпотентным. Используйте идентификатор события от отправителя как ключ идемпотентности и отбрасывайте повторы.

И зеркальное правило для случая, когда вебхуки шлёте вы: закладывайте на своей стороне повторную доставку с backoff и подтверждением. Считайте доставленным только то событие, на которое приёмник ответил успехом; остальное — повторяйте, а безнадёжное уводите в dead-letter, как и любой другой обмен.

Тестирование интеграций: моки и песочница

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

Моки и стабы

В автотестах реальный HTTP-клиент подменяется заглушкой, которая возвращает заранее заданные ответы. Это позволяет проверить вашу логику — очередь, ретраи, идемпотентность, dead-letter — детерминированно и без сети. Обязательные сценарии для моков:

• приёмник отвечает ошибкой 5xx → задание уходит на backoff и повторяется;
• приёмник не отвечает (таймаут) → повтор, при этом дубль не создаётся;
• один и тот же ответ приходит дважды (повторная доставка) → обрабатывается один раз;
• приёмник отвечает постоянной ошибкой (невалидные данные) → без повторов, сразу в разбор;
• исчерпан лимит попыток → задание в dead-letter, поднят алерт.

Песочница и тестовый контур

Многие сервисы предоставляют песочницу (sandbox) — тестовый экземпляр API на данных, которые не жалко. Там прогоняют end-to-end сценарий целиком: от события в магазине до появления сущности во внешней системе. Если песочницы нет, поднимают отдельный тестовый контур или используют выделенный тестовый аккаунт. Главное правило — тесты не должны ходить в боевой сервис и создавать там мусорные данные.

Безопасность: подпись и секреты

Надёжность и безопасность в интеграциях идут рука об руку: канал, по которому ходят заказы и оплаты, — лакомая цель. Базовые меры недороги, но пренебрежение любой из них открывает дыру.

• Подпись запросов. И для своих эндпоинтов, и для обработчиков входящих вебхуков проверяйте подпись или токен, чтобы отличить настоящий запрос от подделки. Обработчик, принимающий что угодно, — открытая дверь: злоумышленник сможет присылать фальшивые события.
• Секреты — на сервере. Токены, ключи, вебхук-коды не должны попадать в клиентский код, публичные репозитории, письма и журналы в открытом виде. Храните их в защищённом конфиге или хранилище секретов, маскируйте в логах.
• Только HTTPS. Весь обмен — по шифрованному каналу. По открытому HTTP токены и данные перехватываются.
• Минимальные права. Давайте интеграции ровно тот доступ, что нужен сценарию. Читаете каталог — не запрашивайте прав на изменение заказов и данные пользователей.
• Ротация и отзыв. Предусмотрите процедуру смены ключей и отзыва токенов заранее — на случай утечки её нельзя изобретать в момент инцидента.
• Валидация входных данных. Не доверяйте тому, что пришло снаружи: проверяйте типы, диапазоны и права на конкретную сущность, чтобы чужой запрос не прочитал чужой заказ по подставленному ID.

Отдельно про подпись повторов: если вы проверяете подпись с меткой времени для защиты от повторного воспроизведения (replay attack), не перепутайте её с легитимной повторной доставкой вебхука. Легитимный повтор несёт тот же идентификатор события — его отсекает идемпотентность; атака replay — это перехваченный старый запрос, и от неё защищает окно валидности подписи. Механизмы разные, и работать они должны параллельно.

Практика на 1С-Битрикс: события и таблицы D7

Соберём всё в конкретный контур на 1С-Битрикс. Он состоит из трёх штатных кирпичей: события платформы как источник, таблицы D7 как очередь и журнал, агент/cron как фоновый обработчик.

Событие как источник обмена

Не вызывайте внешний API прямо в обработчике события. Обработчик события должен делать одну быструю вещь — поставить задание в очередь и завершиться. Например, на событие сохранения заказа вы кладёте в таблицу очереди задание order.export с номером заказа в качестве ключа идемпотентности. Подробно про механику событий — в отдельном разборе событий и обработчиков Битрикс.

use Bitrix\Main\EventManager;

// Регистрация обработчика (например, в init.php модуля)
EventManager::getInstance()->addEventHandler(
    'sale', 'OnSaleOrderSaved',
    ['\Vendor\Shop\Integration\OrderHandler', 'onOrderSaved']
);

class OrderHandler
{
    public static function onOrderSaved(\Bitrix\Main\Event $event)
    {
        /** @var \Bitrix\Sale\Order $order */
        $order = $event->getParameter('ENTITY');
        $orderId = $order->getId();

        // Обработчик НИЧЕГО не шлёт наружу — только ставит задание в очередь.
        // Ключ идемпотентности = стабильный номер заказа.
        enqueue('order.export', ['orderId' => $orderId], 'order-export-' . $orderId);
        // Быстро возвращаемся: пользователь не ждёт внешний API.
    }
}

Таблицы D7: очередь, журнал, идемпотентность

Три ORM-сущности закрывают всю механику: таблица очереди (QueueTable из примеров выше), таблица журнала обмена (ExchangeLogTable) и, при необходимости, таблица обработанных ключей на стороне приёмника. Всё это — обычные сущности D7 с индексами; ключевой — UNIQUE-индекс по ключу идемпотентности, который на уровне БД гарантирует отсутствие дублей заданий.

Агент или cron как обработчик

Раз в минуту cron (или агент в cron-режиме) вызывает processBatch(), который забирает готовые задания, отправляет их, пишет в журнал, планирует повторы и уводит безнадёжное в dead-letter. Обмен полностью отвязан от действий пользователя: заказ оформляется мгновенно, а его отправка в CRM происходит в фоне и переживает любую недоступность приёмника. Если объёмы вырастут, этот же контур масштабируется — например, переносом транспорта на брокер, — но логика надёжности остаётся прежней. Такие интеграции мы проектируем в рамках разработки REST API для 1С-Битрикс, а базовые принципы REST-обмена разобраны в статье про REST API в 1С-Битрикс.

Внедрение по шагам

Сведём всё в практический маршрут — как превратить хрупкую синхронную интеграцию в надёжную. Порядок неслучаен: каждый шаг опирается на предыдущий.

1. Разорвите синхронность. Вынесите вызов внешнего API из обработчика пользовательского действия. На событие — только постановка задания в очередь и быстрый возврат.
2. Заведите очередь. Создайте таблицу очереди на D7 с полями статуса, попыток, времени следующей попытки и ключа идемпотентности (UNIQUE-индекс).
3. Определите ключ идемпотентности. Выберите стабильный бизнес-идентификатор (номер заказа) и передавайте его при каждой попытке; на приёмнике делайте upsert.
4. Добавьте фоновый обработчик. Cron или агент в cron-режиме раз в минуту забирает пачку заданий и выполняет обмен, атомарно захватывая записи.
5. Настройте таймауты. Задайте connect- и read-таймауты для каждого клиента; их превышение — обычная повторяемая ошибка.
6. Реализуйте ретраи с backoff. Экспоненциальная задержка с jitter и лимитом попыток; различайте временные и постоянные ошибки.
7. Заведите dead-letter. Исчерпавшие лимит и «ядовитые» сообщения уводите в мёртвую очередь с сохранением причины.
8. Включите журнал обмена. Логируйте запрос, ответ, попытки и статусы, маскируя секреты; настройте ротацию.
9. Повесьте мониторинг и алерты. Следите за глубиной очереди, возрастом старейшего задания и размером dead-letter; алертьте на действия, а не на шум.
10. Протестируйте сбои. Проверьте на моках и в песочнице недоступность приёмника, повторную доставку, истёкший токен, лимит и обрыв после записи.

Частые ошибки

Грабли, на которые чаще всего наступают при построении интеграций на Битриксе:

• Синхронный вызов в момент действия. Обмен идёт прямо при оформлении заказа; приёмник лёг — сломалось оформление или потерялись данные.
• Повторы без идемпотентности. Ретраи есть, а защиты от дублей нет — появляются задвоенные заказы и сделки.
• Мгновенные повторы «в лоб». При сбое повторяют сразу и в цикле, добивая перегруженный сервис вместо паузы.
• Нет таймаутов. Зависший вызов держит обработчик и подвешивает всю очередь.
• Данные теряются молча. Нет очереди и dead-letter — упавший обмен исчезает бесследно, узнают от клиента.
• Тяжёлая обработка в обработчике вебхука. Синхронно долго обрабатывают событие → таймаут отправителя и повторные доставки.
• Нет журнала обмена. На бою нечем понять, что ушло, что упало и сколько было попыток.
• Агенты «на хите» на низком трафике. Очередь не разбирается, потому что никто не заходит на сайт; обмен встаёт.
• Нестабильный ключ идемпотентности. Ключ меняется на каждой попытке — дедупликация не работает, дубли проходят.
• Секреты в коде и логах. Токены попадают в репозиторий или в журнал в открытом виде — утечка доступа.
• Нет мониторинга. Растущая очередь и непустой dead-letter остаются незамеченными до жалобы бизнеса.
• Тестируют только «счастливый путь». Сбойные сценарии не проверены — именно они и подводят в бою.

Чек-лист надёжной интеграции

Короткий список для приёмки интеграции перед запуском:

• Вызовы внешних API вынесены из пользовательских действий: событие → очередь → фон.
• Очередь хранится в БД (таблица D7) и переживает перезапуск и деплой.
• У каждого обмена есть стабильный ключ идемпотентности с UNIQUE-индексом.
• Приёмник делает upsert по внешнему ключу либо хранит обработанные ключи.
• Фоновый обработчик запускается по cron стабильно, независимо от трафика.
• Параллельные обработчики не берут одно задание дважды (атомарный захват или блокировка).
• У всех сетевых вызовов заданы connect- и read-таймауты.
• Реализованы ретраи с экспоненциальной задержкой, jitter и лимитом попыток.
• Временные и постоянные ошибки различаются: постоянные не повторяются.
• Есть dead-letter с сохранением причины и алертом на попадание.
• Ведётся журнал обмена (запрос, ответ, попытки, статус) с маскированием секретов и ротацией.
• Настроен мониторинг: глубина очереди, возраст старейшего задания, размер dead-letter.
• Обработчики вебхуков быстро подтверждают приём и идемпотентны.
• Порядок и согласованность продуманы: версионирование или порядок в рамках ключа.
• Обмен идёт по HTTPS с проверкой подписи; секреты хранятся на сервере.
• Сбойные сценарии протестированы на моках и в песочнице, не в бою.

Вывод

Надёжная интеграция отличается от хрупкой не тем, что она «не падает», а тем, что она не теряет данные и не плодит дубли, когда падает что-то вокруг. Вся эта надёжность вырастает из одного архитектурного решения — разорвать синхронную связь между действием пользователя и обменом с внешней системой. Приняли данные у себя мгновенно, поставили задание в очередь, отправили фоново с повторами и журналом. Дальше — набор проверенных механизмов: идемпотентность против дублей, backoff против перегруза, таймауты против зависаний, dead-letter против тихой потери, логирование и мониторинг ради прозрачности.

На 1С-Битрикс всё это собирается из штатных кирпичей: события как источник, таблицы D7 как очередь и журнал, агенты и cron как фоновый обработчик. Не нужна экзотическая инфраструктура, чтобы обмен перестал терять заказы, — нужна дисциплина: не вызывать наружу синхронно, всегда думать «а если сообщение придёт дважды» и всегда видеть, что происходит с обменом. Сделайте это системно — и интеграция станет той частью проекта, о которой вспоминают реже всего, потому что она просто работает. А если нужна помощь с проектированием такого обмена, это наша услуга по интеграциям 1С-Битрикс; смежные материалы — в статьях об интеграции магазина с 1С и в рубрике интеграции.