Інтеграція кешбек-системи з 1С 1С-Бітрікс

Інтеграція кешбек-системи з 1С 1С-Бітрікс

Мережа магазинів працює у двох середовищах: офлайн-продажі через 1С:Роздріб та інтернет-магазин на 1С-Бітрікс. Клієнт здійснює покупку у фізичному магазині — нарахування кешбеку має з'явитися в особистому кабінеті на сайті протягом кількох хвилин. І навпаки: списання кешбеку онлайн має враховуватися при наступному візиті до магазину. Без синхронізації балансів між системами програма лояльності фактично працює роздільно для кожного каналу.

Архітектура двосторонньої синхронізації

Вибір мастер-системи — перше архітектурне питання. Варіанти:

Варіант А: 1С — мастер. 1С-Бітрікс зберігає лише кешований баланс, всі операції записуються в 1С, 1С-Бітрікс регулярно отримує актуальний баланс. Простіше підтримувати консистентність, але при недоступності 1С онлайн-списання неможливе.

Варіант Б: 1С-Бітрікс — мастер. 1С отримує баланс із 1С-Бітрікс через API. Операції з 1С надсилаються до черги 1С-Бітрікс. Вразливість — офлайн-каса не може списати кешбек при недоступності мережі.

Варіант В: синхронний обмін із чергою. Кожна система записує операції у свою чергу, фоновий агент синхронізує їх. Найнадійніший, але вимагає механізму розв'язання конфліктів при одночасних операціях.

Для більшості проектів підходить Варіант А з кешуванням балансу на стороні 1С-Бітрікс.

API на стороні 1С-Бітрікс

Створюємо REST-ендпоінт у 1С-Бітрікс для отримання та надсилання операцій із 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);
        }
    }
}

Зовнішній ID та ідемпотентність

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

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

У 1С:Роздріб або 1С:Управління торгівлею створюється зовнішня обробка або розширення, яке:

1. При проведенні чека нарахування — надсилає POST на API 1С-Бітрікс
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 1С-Бітрікс приймає масив транзакцій через POST /transactions/batch. Кожна транзакція обробляється незалежно; у відповіді — масив із результатом для кожної (успіх/помилка/дубль).

Конфлікт: користувач онлайн списав 500 гривень, поки каса працювала офлайн. Офлайн-каса намагалася списати ще 300, але баланс був 500. При синхронізації 1С-Бітрікс виявить, що після першого списання залишок = 0, і відхилить офлайн-операцію з insufficient_balance. 1С має обробити цей випадок: анулювати знижку або запросити доплату.

Пошук користувача

Ідентифікація покупця офлайн — за номером телефону. Пошук у 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 на стороні 1С-Бітрікс: balance, transactions, batch
• Таблиці транзакцій з EXTERNAL_ID і SOURCE
• Логіка ідемпотентності, обробка конфліктів при недостатньому балансі
• Нормалізація телефонів, пошук користувачів
• Зовнішня обробка 1С (узгоджується з програмістом 1С)
• Моніторинг синхронізації, сповіщення при збоях

Терміни: 4–6 тижнів за наявності програміста 1С на проекті. 6–10 тижнів якщо потрібна розробка обробника 1С з нуля.