Інтеграція кешбек-системи з 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. Кожна транзакція обробляється незалежно; у відповіді — масив з результатом для кожної (успіх/помилка/дубль).

Конфлікт: користувач онлайн списав 500 гривень, поки каса працювала офлайн. Офлайн-каса намагалася списати ще 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С з нуля. Вартість розраховується індивідуально — зв'яжіться з нами для аудиту вашої системи. Отримайте консультацію інженера. Оцінимо проєкт за один день.