Розробка модуля імпорту даних 1С-Бітрікс

Розробка модуля імпорту даних для 1С-Бітрікс

Імпорт у 1С-Бітрікс — це не просто «завантажити CSV». Це трансформація даних з чужого формату в структури Бітрікс з урахуванням інфоблоків, торгового каталогу, CRM, користувачів. Вбудований імпорт існує лише для каталогу через CommerceML та YML; для всього іншого розробляють окремий модуль.

Що надає стандарт і де він закінчується

Стандартний модуль catalog підтримує імпорт через CSaleImport та клас CDataExchangeXML для CommerceML 2.x. Працює прийнятно для простого каталогу. Проблеми починаються з:

• довільних форматів (Excel, JSON, XML з нестандартною схемою)
• імпорту до кількох інфоблоків одночасно
• оновлення існуючих записів з логікою слияння полів
• імпорту користувачів, замовлень, CRM-сутностей
• великих файлів (10 000+ рядків) без таймаутів

Архітектура модуля

Модуль vendor.importer побудований навколо трьох абстракцій: Reader (читає джерело), Transformer (трансформує дані), Writer (записує в Бітрікс).

SourceFile → Reader → RawRow[] → Transformer → MappedRow[] → Writer → Bitrix entities

ReaderInterface:

interface ReaderInterface
{
    public function open(string $filePath): void;
    public function readNext(): ?array;    // null = кінець файлу
    public function getHeaders(): array;
    public function close(): void;
}

Реалізації: CsvReader, XlsxReader (через PhpSpreadsheet), XmlReader (через XMLReader для потокового читання великих файлів), JsonReader.

Маппінг полів

Конфігурація маппінгу зберігається в b_vendor_importer_mapping:

{
  "source": "csv",
  "target": "catalog_product",
  "iblock_id": 5,
  "fields": {
    "article": "PROPERTY_ARTICLE",
    "name": "NAME",
    "price": "CATALOG_PRICE_1",
    "stock": "CATALOG_STORE_PRODUCT_AMOUNT"
  },
  "key_field": "article",
  "update_strategy": "merge"
}

key_field визначає поле для ідентифікації існуючого запису (артикул, зовнішній ID, email). update_strategy:

• merge — оновлює лише поля з маппінгу, інші не змінює
• replace — повна заміна запису
• skip — пропуск існуючих, тільки нові

Потокова обробка великих файлів

Не можна обробити 50 000 рядків за одне HTTP-запитання. Використовуємо сесійний підхід з агентом:

// Крок 1: завантаження файлу, створення завдання
$job = ImportJobTable::add([
    'FILE_PATH'  => $uploadedPath,
    'MAPPING_ID' => $mappingId,
    'STATUS'     => 'pending',
    'TOTAL'      => 0,
    'PROCESSED'  => 0,
]);

// Крок 2: агент читає порціями
public static function processChunk(int $jobId, int $offset, int $limit = 100): string
{
    $job = ImportJobTable::getById($jobId)->fetch();
    $reader = ReaderFactory::create($job['FILE_PATH']);
    $reader->open($job['FILE_PATH']);
    // пропускаємо offset рядків, читаємо limit рядків
    // ...обробляємо, оновлюємо PROCESSED
}

Агент викликається щохвилини, обробляє наступну порцію, оновлює лічильник. Прогрес видимий в адміністративному інтерфейсі в реальному часі.

Writer: запис в інфоблок

class IblockElementWriter implements WriterInterface
{
    public function write(MappedRow $row): WriteResult
    {
        $existing = $this->findByKey($row->getKeyValue());

        if ($existing) {
            $result = \CIBlockElement::Update($existing['ID'], $row->toIblockArray());
        } else {
            $element = new \CIBlockElement();
            $result = $element->Add($row->toIblockArray());
        }

        return new WriteResult($result !== false, $existing ? 'updated' : 'created');
    }
}

Подібні Writer-класи: CrmLeadWriter (через \Bitrix\Crm\LeadTable), SaleOrderWriter (через \Bitrix\Sale\Order::create()), UserWriter (через \CUser::Add/Update).

Валідація даних

Перед записом кожен рядок проходить валідацію. Правила описуються декларативно:

$rules = [
    'EMAIL'  => ['required', 'email'],
    'PRICE'  => ['required', 'numeric', 'min:0'],
    'NAME'   => ['required', 'max:255'],
    'STATUS' => ['in:active,inactive,pending'],
];

Рядки з помилками не записуються, фіксуються в b_vendor_importer_error з указанням номера рядка, поля та причини. Після імпорту доступний звіт про помилки з можливістю завантажити CSV «проблемних рядків».

Сповіщення та логування

По завершенні імпорту модуль відправляє email-сповіщення ініціатору через \Bitrix\Main\Mail\Event::send(). У сповіщенні: загальна кількість рядків, створено/оновлено/помилок, посилання на журнал.

Журнал зберігається в b_vendor_importer_log: job_id, line_number, action (created/updated/skipped/error), entity_id, message, created_at.

Терміни розробки

Усього: 13 робочих днів. Нестандартні формати джерела або складна логіка трансформації (дедублікація, збагачення даних з зовнішніх API) оцінюються додатково.