Интеграция кэшбэк-системы с 1С и 1С-Битрикс

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

Типичные проблемы: дублирующиеся начисления, потерянные операции при обрыве связи, рассинхронизация балансов. Без надёжной интеграции программа лояльности становится источником ошибок, а не способом удержания клиентов. Мы предлагаем архитектуру двусторонней синхронизации кэшбэка под ключ — от проектирования до мониторинга. За годы работы мы реализовали более 30 интеграций кэшбэка для розничных сетей. В этой статье разберём технические детали: как выбрать мастер-систему, организовать идемпотентность транзакций и обработать офлайн-операции. Также рассмотрим API-контракты, поиск пользователей и мониторинг синхронизации.

Как выбрать мастер-систему для синхронизации кэшбэка?

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

API на стороне Битрикс

Создаём REST-endpoint в Битрикс для получения и отправки операций из 1С:

// /local/api/cashback/v1/ // Маршрутизация через urlrewrite.php или отдельный файл class CashbackApiController { /** * GET /local/api/cashback/v1/balance?user_phone=79001234567 * Используется 1С для проверки баланса на кассе */ public function getBalance(): void { $this->requireApiKey(); $phone = $_GET['user_phone'] ?? ''; $userId = $this->getUserIdByPhone($phone); if (!$userId) { $this->respond(['error' => 'user_not_found'], 404); return; } $balance = CashbackBalanceTable::getBalance($userId); $this->respond([ 'user_id' => $userId, 'balance' => $balance, 'updated_at' => CashbackBalanceTable::getLastUpdated($userId), ]); } /** * POST /local/api/cashback/v1/transactions * 1С отправляет операции (начисление/списание при офлайн-покупке) */ public function addTransaction(): void { $this->requireApiKey(); $body = json_decode(file_get_contents('php://input'), true); $this->validateTransaction($body); // type, amount, external_id, user_phone // Идемпотентность: external_id уникален на стороне 1С if (CashbackTransactionTable::existsByExternalId($body['external_id'])) { $this->respond(['status' => 'already_exists', 'idempotent' => true]); return; } $userId = $this->getUserIdByPhone($body['user_phone']); \Bitrix\Main\Application::getConnection()->startTransaction(); try { CashbackTransactionTable::add([ 'USER_ID' => $userId, 'TYPE' => $body['type'], // accrual|debit 'AMOUNT' => $body['amount'], 'DESCRIPTION' => $body['description'] ?? '', 'EXTERNAL_ID' => $body['external_id'], // ID документа в 1С 'SOURCE' => '1c_retail', 'CREATED_AT' => new \Bitrix\Main\Type\DateTime($body['created_at']), ]); if ($body['type'] === 'accrual') { CashbackBalanceTable::credit($userId, $body['amount']); } else { CashbackBalanceTable::debit($userId, $body['amount']); } \Bitrix\Main\Application::getConnection()->commitTransaction(); $this->respond(['status' => 'ok']); } catch (\Exception $e) { \Bitrix\Main\Application::getConnection()->rollbackTransaction(); $this->respond(['error' => $e->getMessage()], 500); } } } 

Почему идемпотентность критична?

Поле EXTERNAL_ID в таблице транзакций — уникальный идентификатор документа в 1С. 1С формирует его как {ТипОперации}_{НомерДокумента}_{Дата}. При повторной отправке одного и того же документа (сетевой сбой, повтор запроса) Битрикс отвечает already_exists без повторного зачисления — это защищает от дублей баланса. Это свойство критично для корректной работы программы лояльности. Как рекомендует документация 1С-Битрикс, идемпотентность должна быть реализована на уровне бизнес-логики обработки транзакций.

Как проходит внедрение?

1. Анализируем текущую архитектуру: определяем мастер-систему, каналы обмена, типы операций.
2. Проектируем REST API на стороне Битрикс: endpoints, контракты, идемпотентность.
3. Разрабатываем внешнюю обработку 1С: формирование запросов, обработка ответов.
4. Тестируем в изолированной среде: имитируем офлайн-режим, проверяем конфликты.
5. Разворачиваем в продуктив: настраиваем мониторинг, логирование, оповещения.

Далее — гарантийная поддержка после запуска.

Обработчик на стороне 1С

В 1С:Розница или 1С:Управление торговлей создаётся внешняя обработка или расширение, которое:

1. При проведении чека начисления — отправляет POST на Битрикс API
2. При списании кэшбэка на кассе — предварительно запрашивает баланс (GET /balance), затем POST с операцией debit
3. При отмене чека — отправляет операцию release (отмена списания) или отрицательное начисление

Пример HTTP-запроса из 1С (встроенный HTTP-клиент):

Запрос = Новый HTTPЗапрос("/local/api/cashback/v1/transactions"); Запрос.Заголовки.Вставить("Content-Type", "application/json"); Запрос.Заголовки.Вставить("X-API-Key", Константы.КешбекAPIКлюч.Получить()); Запрос.УстановитьТелоИзСтроки(ЗаписатьJSON(ТелоЗапроса)); Ответ = Соединение.ОтправитьДляОбработки(Запрос); 

Синхронизация при офлайн-работе кассы

Касса может работать без сети. В этом случае операции накапливаются в локальной базе 1С и отправляются пакетом при восстановлении соединения. Битрикс API принимает массив транзакций через POST /transactions/batch. Каждая транзакция обрабатывается независимо; в ответе — массив с результатом для каждой (успех/ошибка/дубль).

Конфликт: пользователь онлайн списал $4–6, пока касса работала офлайн. Офлайн-касса пыталась списать ещё 300, но баланс был 500. При синхронизации Битрикс обнаружит, что после первого списания остаток = 0, и отклонит офлайн-операцию с insufficient_balance. 1С должна обработать этот случай: аннулировать скидку или запросить доплату.

Поиск пользователя

Идентификация покупателя в офлайн — по номеру телефона. Поиск в Битрикс:

private function getUserIdByPhone(string $phone): ?int { $phone = preg_replace('/\D/', '', $phone); $result = \Bitrix\Main\UserTable::getList([ 'filter' => ['PERSONAL_PHONE' => $phone], 'select' => ['ID'], 'limit' => 1, ]); if ($row = $result->fetch()) { return (int)$row['ID']; } // Поиск по дополнительным полям UF_PHONE_VERIFIED $result = \Bitrix\Main\UserTable::getList([ 'filter' => ['UF_PHONE_VERIFIED' => $phone], 'select' => ['ID'], 'limit' => 1, ]); return ($row = $result->fetch()) ? (int)$row['ID'] : null; } 

Телефоны хранятся в разных форматах — нормализация до 11 цифр (без +, ведущая 7 или 8) обязательна на входе.

Отображение офлайн-операций в личном кабинете

Транзакции с SOURCE = '1c_retail' отображаются в истории с меткой «Покупка в магазине» вместо ссылки на онлайн-заказ. В DESCRIPTION 1С передаёт адрес магазина или номер кассы — это показывается пользователю.

Мониторинг синхронизации

Таблица local_cashback_sync_log фиксирует все входящие запросы от 1С: время, external_id, статус ответа. Если в течение N часов не было операций от конкретного магазина — триггер уведомляет администратора (возможно, сбой в обработке на стороне 1С).

Что входит в работу

• REST API на стороне Битрикс: balance, transactions, batch
• Таблицы транзакций с EXTERNAL_ID и SOURCE
• Логика идемпотентности, обработка конфликтов при недостаточном балансе
• Нормализация телефонов, поиск пользователей
• Внешняя обработка 1С (согласовывается с программистом 1С)
• Мониторинг синхронизации, оповещения при сбоях
• Техническая документация и обучение вашего персонала
• Гарантийная поддержка после запуска

Сроки: 4–6 недель при наличии программиста 1С на проекте. 6–10 недель если требуется разработка обработчика 1С с нуля. Стоимость рассчитывается индивидуально — свяжитесь с нами для аудита вашей системы. Получите консультацию инженера. Оценим проект за один день.