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

Міграція даних зі сторонньої CRM у Бітрікс24

Перехід із Salesforce, HubSpot, Pipedrive або самописної CRM у Бітрікс24 — це не просто експорт CSV та імпорт. Кожна CRM має власну модель даних, логіку зв'язків і специфіку полів. Бітрікс24 — теж. Головне завдання міграції: не втратити зв'язки між сутностями та зберегти історичну цінність даних.

Структура даних Бітрікс24

Перш ніж мігрувати, потрібно розуміти, куди потрапляють дані. Ключові сутності Бітрікс24:

Зв'язки: контакт прив'язаний до компанії через b_crm_company_contact, угода — до контакту через b_crm_deal_contact.

Інструменти міграції

REST API Бітрікс24 — офіційний і найнадійніший метод. Підтримує пакетні запити (batch), що критично при перенесенні тисяч записів:

$batchCalls = [];
foreach ($contacts as $contact) {
    $batchCalls['create_contact_' . $contact['id']] = [
        'method' => 'crm.contact.add',
        'params' => [
            'fields' => [
                'NAME'       => $contact['first_name'],
                'LAST_NAME'  => $contact['last_name'],
                'EMAIL'      => [['VALUE' => $contact['email'], 'VALUE_TYPE' => 'WORK']],
                'PHONE'      => [['VALUE' => $contact['phone'], 'VALUE_TYPE' => 'WORK']],
                'COMPANY_ID' => $companyMapping[$contact['company_id']] ?? null,
                'UF_CRM_SOURCE_ID' => $contact['id'], // Зберігаємо ID джерела
            ],
        ],
    ];
}

// Надсилаємо пакет (до 50 запитів за раз)
$result = $b24->callBatch(array_slice($batchCalls, 0, 50));

Пряме записування в БД — для хмарного Бітрікс24 недоступне. Для коробкової версії — прискорює масовий імпорт, але потребує ручного перебудування індексів і обережності з тригерами.

Маппінг полів: найбільш трудомістка частина

Кожне поле джерела потрібно зіставити з полем Бітрікс24. Приклад маппінгу з HubSpot:

Нестандартні поля HubSpot переносяться в користувацькі поля Бітрікс24 (UF-поля). Їх потрібно створити заздалегідь через crm.contact.userfield.add.

Порядок створення сутностей

Порядок важливий через референсну цілісність:

1. Компанії (у контактів і угод немає залежностей вище)
2. Контакти (прив'язка до компаній)
3. Угоди (прив'язка до контактів і компаній)
4. Активності — дзвінки, листи, завдання (прив'язка до угод/контактів)
5. Коментарі та історія — через crm.timeline.comment.add

Після створення кожної сутності зберігаємо маппінг: source_id → b24_id. Це потрібно для прив'язки залежних об'єктів.

$mappingFile = 'migration_map.json';
$mapping = json_decode(file_get_contents($mappingFile), true) ?: [];
$mapping['contacts'][$sourceContact['id']] = $b24ContactId;
file_put_contents($mappingFile, json_encode($mapping));

Обробка дублікатів

Сторонні CRM часто містять дублікати контактів (одна людина під різними email). Перед міграцією — дедублікація в джерелі. Стратегії:

• Жорстка: один унікальний email = один контакт. Дублікати об'єднуються.
• М'яка: переносимо всі записи, потім використовуємо вбудований інструмент дедублікації Бітрікс24 (Контакти → Дублікати).

Рекомендується м'яка стратегія — зберігає всі дані, дедублікацію менеджери роблять у процесі роботи.

Історія активностей: дзвінки та листи

Перенесення історії комунікацій — опційна, але цінна частина. Дзвінки з джерела → crm.activity.add з типом CALL:

$b24->call('crm.activity.add', [
    'fields' => [
        'OWNER_TYPE_ID' => 3, // 3 = контакт, 2 = угода
        'OWNER_ID'      => $mapping['contacts'][$call['contact_id']],
        'TYPE_ID'       => 2, // Дзвінок
        'SUBJECT'       => 'Дзвінок від ' . date('d.m.Y', strtotime($call['created_at'])),
        'DESCRIPTION'   => $call['notes'],
        'START_TIME'    => $call['created_at'],
        'END_TIME'      => $call['ended_at'],
        'DIRECTION'     => $call['direction'] === 'inbound' ? 1 : 2,
        'COMPLETED'     => 'Y',
    ],
]);

Контроль якості міграції

Після перенесення — обов'язкове звірення:

# Джерело
SELECT COUNT(*) FROM hubspot_contacts WHERE is_deleted = 0;
# → 12 847

# Бітрікс24
SELECT COUNT(*) FROM b_crm_contact WHERE DELETED = 'N';
# → 12 839  ← 8 записів втрачено — розслідуємо

Розбіжності логуються та аналізуються: зазвичай це дублікати або записи з невалідними даними (порожній email, некоректний телефон).

Терміни виконання

Успішна міграція — це коли менеджери в Бітрікс24 наступного дня бачать повну історію відносин з клієнтами, наче завжди працювали тут.