Міграція даних з HubSpot до Бітрікс24

Міграція даних з HubSpot у Бітрікс24

HubSpot — американська CRM-платформа з багатим API та детальною документацією. Це робить технічний бік експорту відносно прозорим. Складність міграції у Бітрікс24 — у концептуальних відмінностях між системами: HubSpot будується навколо «Контактів» та «Компаній» як центральних об'єктів, тоді як Бітрікс24 додає до цього поняття «Ліда» як первинної заявки.

HubSpot API: що доступно

HubSpot надає REST API v3 з повним доступом до всіх даних. Основні об'єкти:

• contacts — контакти (фізичні особи)
• companies — компанії
• deals — угоди з воронками та стадіями
• tickets — тикети підтримки
• engagements / activities — активності (листи, дзвінки, зустрічі, завдання)
• owners — власники (менеджери)
• properties — кастомні поля (schema)

Отримання даних через HubSpot API v3:

// Отримання контактів з пагінацією (cursor-based)
$after = null;
$contacts = [];
do {
    $params = ['limit' => 100, 'properties' => 'firstname,lastname,email,phone,company'];
    if ($after) $params['after'] = $after;
    $response = $hubspot->get('/crm/v3/objects/contacts', $params);
    $contacts = array_merge($contacts, $response['results']);
    $after = $response['paging']['next']['after'] ?? null;
} while ($after);

HubSpot використовує cursor-based пагінацію (через поле after), на відміну від offset-based у багатьох інших системах.

Маппінг об'єктів

Кастомні властивості HubSpot

HubSpot дозволяє створювати довільні властивості для кожного об'єкту. Схему властивостей отримуємо через /crm/v3/properties/contacts (і аналогічно для інших об'єктів). Для кожної кастомної властивості потрібно створити користувацьке поле в Бітрікс24 через crm.userfield.add.

Типи властивостей HubSpot та їх аналоги в Бітрікс24:

Асоціації між об'єктами

HubSpot зберігає зв'язки між об'єктами через API асоціацій (/crm/v3/associations). Контакт може бути пов'язаний з кількома компаніями, угода — з кількома контактами. У Бітрікс24 модель простіша: у контакту одна основна компанія (COMPANY_ID), а мультиприв'язки реалізуються через зв'язки CRM.

При міграції множинні асоціації потрібно пріоритизувати: обрати основну компанію для контакту та основний контакт для угоди.

Електронна пошта та історія комунікацій

Листи в HubSpot зберігаються як engagements типу EMAIL. Вони містять тему, тіло листа, дату, ID контакту. У Бітрікс24 це справи типу EMAIL через crm.activity.add:

$bitrix->call('crm.activity.add', [
    'fields' => [
        'TYPE_ID'       => 4, // EMAIL
        'SUBJECT'       => $engagement['metadata']['subject'],
        'DESCRIPTION'   => $engagement['metadata']['html'] ?? $engagement['metadata']['text'],
        'START_TIME'    => date('d.m.Y H:i:s', $engagement['createdAt'] / 1000),
        'BINDINGS'      => [['ENTITY_TYPE_ID' => 3, 'ENTITY_ID' => $contactId]],
        'DIRECTION'     => $engagement['metadata']['from'] ? 2 : 1, // вхідне/вихідне
    ],
]);

Типові терміни

HubSpot Marketing Hub (email-кампанії, landing pages) у Бітрікс24 не мігрує — це окремий клас інструментів без прямого аналогу.