Інтеграція 1С-Бітрікс з Mindbox (персоналізація)

Інтеграція 1С-Бітрікс із Mindbox (персоналізація)

Mindbox — платформа автоматизації маркетингу: єдиний профіль клієнта, сегментація, триґерні розсилки, програми лояльності, персоналізовані промокоди. Інтеграція з Бітріксом охоплює кілька напрямків: передача даних про клієнтів та замовлення, отримання персоналізованих пропозицій для конкретного користувача та управління бонусною програмою.

Архітектура інтеграції

Mindbox працює через REST API з двома режимами:

• Синхронний — запит → відповідь у реальному часі. Використовується при реєстрації/авторизації (отримати профіль клієнта, почислити бонуси) та при оформленні замовлення (застосувати знижку за промокодом, дізнатись баланс бонусів).
• Асинхронний — дії ставляться в чергу та обробляються Mindbox у фоні. Використовується для передачі даних про перегляди, додавання в кошик, історію замовлень.

Бітрікс → Mindbox API (events):   реєстрація, замовлення, перегляд
Mindbox → Бітрікс (callback):     бонусний баланс, статус промокода
Mindbox → Email/SMS:               розсилки, триґери (Mindbox усередині)

Аутентифікація в Mindbox API

Mindbox використовує авторизацію за секретом у заголовку:

Authorization: Mindbox secretKey="YOUR_SECRET_KEY"
Content-Type: application/json

Базовий URL: https://api.mindbox.ru/v3/operations/async (асинхронний) та /v3/operations/sync (синхронний).

Передача події реєстрації

При реєстрації користувача в Бітріксі — подія в Mindbox для створення/оновлення профілю клієнта:

AddEventHandler('main', 'OnAfterUserRegister', function(&$arUser) {
    sendMindboxEvent('Website.RegisterCustomer', [
        'customer' => [
            'email'       => $arUser['EMAIL'],
            'mobilePhone' => $arUser['PERSONAL_PHONE'] ?? '',
            'firstName'   => $arUser['NAME'] ?? '',
            'lastName'    => $arUser['LAST_NAME'] ?? '',
            'customFields'=> [
                'bitrixUserId' => $arUser['USER_ID'],
            ],
        ],
        'executionDateTimeUtc' => gmdate('Y-m-d\TH:i:s\Z'),
    ]);
});

function sendMindboxEvent(string $operation, array $data, bool $sync = false): ?array
{
    $endpoint = $sync
        ? 'https://api.mindbox.ru/v3/operations/sync'
        : 'https://api.mindbox.ru/v3/operations/async';

    $http = new \Bitrix\Main\Web\HttpClient();
    $http->setHeader('Authorization', 'Mindbox secretKey="' . MINDBOX_SECRET . '"');
    $http->setHeader('Content-Type', 'application/json');

    $payload = array_merge(['deviceUUID' => getMindboxDeviceUUID()], $data);

    $response = $http->post(
        $endpoint . '?endpointId=' . MINDBOX_ENDPOINT_ID
               . '&operation=' . urlencode($operation),
        json_encode($payload)
    );

    return $sync ? json_decode($response, true) : null;
}

Передача замовлення

При створенні замовлення в Бітріксі відправляємо повні дані:

AddEventHandler('sale', 'OnSaleOrderSaved', function(\Bitrix\Main\Event $event) {
    $order = $event->getParameter('ENTITY');
    $isNew = $event->getParameter('IS_NEW');
    if (!$isNew) return;

    $basket = $order->getBasket();
    $lines  = [];

    foreach ($basket->getOrderableItems() as $item) {
        $lines[] = [
            'product' => [
                'ids' => ['bitrix' => $item->getProductId()],
            ],
            'count'     => $item->getQuantity(),
            'price'     => $item->getPrice(),
            'basePricePerItem' => $item->getBasePrice(),
        ];
    }

    sendMindboxEvent('Website.CreateOrder', [
        'order' => [
            'ids'               => ['bitrix' => $order->getId()],
            'totalPrice'        => $order->getPrice(),
            'discountedPrice'   => $order->getPrice(),
            'lines'             => $lines,
        ],
        'customer' => [
            'email'      => $order->getUserEmail(),
            'ids'        => ['bitrixId' => $order->getUserId()],
        ],
    ]);
});

Бонусна програма: перевірка та списання

Синхронний запит при оформленні замовлення — отримати баланс бонусів та застосувати:

function getMindboxBonusBalance(int $userId): float
{
    $user   = CUser::GetByID($userId)->Fetch();
    $result = sendMindboxEvent('Website.GetCustomerBalance', [
        'customer' => ['email' => $user['EMAIL']],
    ], true);

    return (float)($result['customer']['bonusPointsBalance']['available'] ?? 0);
}

function applyMindboxBonuses(int $orderId, int $userId, float $bonusAmount): bool
{
    $user   = CUser::GetByID($userId)->Fetch();
    $result = sendMindboxEvent('Website.ConfirmOrderBonusPoints', [
        'order'    => ['ids' => ['bitrix' => $orderId]],
        'customer' => ['email' => $user['EMAIL']],
        'payment'  => ['bonusPoints' => $bonusAmount],
    ], true);

    return ($result['status'] ?? '') === 'Success';
}

На сторінці оформлення замовлення баланс бонусів запитується через AJAX та показується користувачу з можливістю застосувати частину або все.

Персоналізовані промокоди

Mindbox генерує персональні промокоди для кожного сегмента. При оформленні замовлення перевіряємо промокод:

function validateMindboxPromocode(string $code, int $userId): ?array
{
    $user   = CUser::GetByID($userId)->Fetch();
    $result = sendMindboxEvent('Website.CheckPromocode', [
        'order'    => ['promocode' => $code],
        'customer' => ['email'     => $user['EMAIL']],
    ], true);

    if (($result['status'] ?? '') !== 'Success') {
        return null;
    }

    return [
        'discount_type'   => $result['order']['discountType'] ?? 'percent',
        'discount_value'  => $result['order']['discountValue'] ?? 0,
    ];
}

Повернений тип та розмір знижки використовуються при перерахунку кошика через механізм знижок Бітрікс або прямо через $item->setField('DISCOUNT_PRICE', ...).

DeviceUUID

Mindbox зв'язує анонімні дії та авторизованого користувача через UUID пристрою:

function getMindboxDeviceUUID(): string
{
    if (!isset($_COOKIE['mindboxDeviceUUID'])) {
        $uuid = sprintf('%04x%04x-%04x-%04x-%04x-%04x%04x%04x',
            mt_rand(0, 0xffff), mt_rand(0, 0xffff),
            mt_rand(0, 0xffff),
            mt_rand(0, 0x0fff) | 0x4000,
            mt_rand(0, 0x3fff) | 0x8000,
            mt_rand(0, 0xffff), mt_rand(0, 0xffff), mt_rand(0, 0xffff)
        );
        setcookie('mindboxDeviceUUID', $uuid, time() + 86400 * 365, '/');
        return $uuid;
    }
    return $_COOKIE['mindboxDeviceUUID'];
}

JavaScript-трекер Mindbox також читає цей UUID та автоматично привязує поведінку на сайті.

Підключення JS-трекера

<!-- У footer.php або через addExternalJs -->
<script>
var mindbox = window.mindbox || [];
mindbox.push = mindbox.push || function(e) { mindbox.queue.push(e); };
mindbox.queue = mindbox.queue || [];

mindbox('create', {
    endpointId: '<?= MINDBOX_ENDPOINT_ID ?>'
});
</script>
<script src="https://api.mindbox.ru/scripts/v1/tracker.js" async></script>

Тривалість реалізації