Ми часто стикаємося з ситуацією: мережа магазинів веде облік в 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С-Бітрікс, ідемпотентність має бути реалізована на рівні бізнес-логіки обробки транзакцій.
Приклад обробки конфлікту недостатнього балансу
При синхронізації офлайн-операцій Бітрікс повертає помилку з кодом insufficient_balance. 1С повинна обробити це: скасувати знижку або запросити доплату. В лозі фіксується подія.
Як проходить впровадження?
- Аналізуємо поточну архітектуру: визначаємо мастер-систему, канали обміну, типи операцій.
- Проєктуємо REST API на стороні Бітрікс: endpoints, контракти, ідемпотентність.
- Розробляємо зовнішню обробку 1С: формування запитів, обробка відповідей.
- Тестуємо в ізольованому середовищі: імітуємо офлайн-режим, перевіряємо конфлікти.
- Розгортаємо в продакшн: налаштовуємо моніторинг, логування, сповіщення.
Далі — гарантійна підтримка після запуску.
Обробник на стороні 1С
В 1С:Роздріб або 1С:Управління торгівлею створюється зовнішня обробка або розширення, яке:
- При проведенні чека нарахування — надсилає POST на Бітрікс API
- При списанні кешбеку на касі — попередньо запитує баланс (
GET /balance), потім POST з операцієюdebit - При скасуванні чека — надсилає операцію
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С).
| Показник | Орієнтир |
|---|---|
| Час потрапляння офлайн-операції в Бітрікс | < 5 хвилин при онлайн-роботі каси |
| Затримка при пакетній синхронізації після офлайн | < 10 хвилин від відновлення зв'язку |
| Дублювання транзакцій | 0 (ідемпотентність через external_id) |
Що входить в роботу
- REST API на стороні Бітрікс: balance, transactions, batch
- Таблиці транзакцій з
EXTERNAL_IDтаSOURCE - Логіка ідемпотентності, обробка конфліктів при недостатньому балансі
- Нормалізація телефонів, пошук користувачів
- Зовнішня обробка 1С (узгоджується з програмістом 1С)
- Моніторинг синхронізації, сповіщення при збоях
- Технічна документація та навчання вашого персоналу
- Гарантійна підтримка після запуску
Терміни: 4–6 тижнів за наявності програміста 1С на проєкті. 6–10 тижнів якщо потрібна розробка обробника 1С з нуля. Вартість розраховується індивідуально — зв'яжіться з нами для аудиту вашої системи. Отримайте консультацію інженера. Оцінимо проєкт за один день.