Как я писал микро-сервис для назначения партнёров турам в Битрикс24: разбор реального кода и боль работы со списками (Enum)

Шаг 3: Двухэтапный мэтчинг партнёра

Когда товар найден, мне нужно сопоставить присланного партнёра со справочником Битрикса. Я делаю это в два этапа для оптимизации:

// Шаг 1: Прямое совпадение по ID (Быстро и точно)
foreach ($partnerIds as $pId) {
    if (isset($enumMap[$pId])) {
        $matchedEnum = $pId;
        $matchedName = $enumMap[$pId];
        $matchMethod = 'by_id';
        break;
    }
}

// Шаг 2: Если ID не совпали — ищем по имени (Медленно, но надежно)
if ($matchedEnum === null) {
    foreach ($partnerNames as $partnerName) {
        foreach ($enumMap as $id => $name) {
            $matchResult = $this->matchStrings($name, $partnerName);
            if ($matchResult) {
                $matchedEnum = $id;
                $matchedName = $name;
                $matchMethod = 'by_name';
                break 2; // Выходим из обоих циклов
            }
        }
    }
}

Самая тонкая часть: Как правильно обновить свойство и как его ОЧИСТИТЬ

Когда мы нашли нужный enum ID, мы должны обновить товар. И тут скрывается самая неочевидная засада Битрикс24 API, на которой я потерял полчаса дебаггинга.

По ТЗ заказчика, если менеджер передал пустой список партнёров, это значит, что партнера у тура больше нет, и свойство нужно очистить (снять галочку).

Как вы думаете, как правильно отправить пустое значение в REST API Битрикс24?

• Отправить null? Нет, Битрикс ругнется на формат.
• Отправить пустую строку ""? Нет, Битрикс проигнорирует.
• Отправить false? Тоже мимо.

Огромная засада Битрикс24 API: Чтобы очистить свойство типа «Список», вы обязаны отправить пустой массив [].

Посмотрите, как изящно и безопасно это решено в моем методе setProductProperty:

private function setProductProperty(int $productId, string $value): array
{
    // Если значение пустое, формируем пустой массив!
    $propValue = ($value === '') ? [] : [$value];

    $result = $this->call('crm.product.update', [
        'id'     => $productId,
        'fields' => ['PROPERTY_133' => $propValue],
    ]);

    if (!$result['success']) {
        return $this->error('Ошибка обновления товара: ' . $result['error']);
    }

    // Перечитываем товар для проверки
    $check = $this->call('crm.product.get', ['id' => $productId]);
    $realValue = ($check['success']) ? ($check['data']['PROPERTY_133'] ?? '') : '';

    return ['success' => true, 'real_property_133' => $realValue];
}

Тернарный оператор $propValue = ($value === '') ? [] : [$value]; — это щит от кривых данных. Если пришел ID партнера, он оборачивается в массив (как требует Битрикс). Если пришла пустота — отправляется пустой массив, и Битрикс честно очищает поле в базе.

Обратите внимание еще на одну деталь в этом методе. После обновления я делаю лишний запрос: $this->call('crm.product.get', ['id' => $productId]). Зачем? Помните, я говорил, что Битрикс часто врет? Он может вернуть success: true на update, но по какой-то внутренней причине не обновить поле (например, если у пользователя нет прав на изменение именно этого свойства, хотя права на сам товар есть). Перечитывая товар сразу после обновления, я возвращаю в фронтенд реальное значение поля real_property_133. Фронтенд может сравнить то, что просил, с тем, что реально стало, и показать алерт менеджеру, если что-то пошло не так.

Паранойя разработчика: Как и зачем я логирую каждый шаг

В предыдущих статьях я говорил, что сложные интеграции нужно делать асинхронно через RabbitMQ. Но этот скрипт — микро-сервис для внутренних нужд, им пользуются 3 менеджера. Я сделал его синхронно, но компенсировал это сумасшедшим логированием.

Знаете, какая самая частая проблема при работе с crm.product.update? Ответ Битрикса: {"result": true}. Он возвращает HTTP 200 OK и true даже тогда, когда вы передали ему откровенную дичь в полях (если это не вызвало фатальную ошибку валидации на уровне ядра, а просто игнорировалось логикой свойств). Вы будете смотреть в карточку товара в браузере, видеть, что ничего не изменилось, и не понимать, где баг — в вашем коде или в Битриксе.

Поэтому в моем методе processTour() разбросаны десятки вызовов $this->writeLog(). Я логирую вообще всё:

1. Какой тур пришел в исходном виде.
2. Какие сырые данные прислал фронтенд.
3. Какую карту enum выдал Битрикс на этот момент.
4. Какие ID нашел фильтр по подстроке в товарах.
5. Какое старое значение было у PROPERTY_133.
6. Какой новый enum ID я вычислил через stripos.

 $this->writeLog($logFile, "Текущее значение PROPERTY_133:");
 $this->writeLog($logFile, "  - raw: " . $prop133Debug);
 $this->writeLog($logFile, "  - normalized IDs: " . json_encode($currentIds));

Почему FILE_APPEND | LOCK_EX — это критично?

В функции writeLog я использую стандартный file_put_contents. Но заметьте флаги в конце: FILE_APPEND | LOCK_EX.

Представьте ситуацию: менеджер случайно нажал кнопку "Сохранить" в админке два раза быстро (или браузер затупил и отправил дабл-пост). В PHP запустятся два параллельных процесса (если используется php-fpm). Оба процесса одновременно попытаются открыть текстовый файл лога и записать туда строку.

Без флага LOCK_EX (эксклюзивной блокировки файла) строки лога перемешаются в кашу: половина строки от первого запроса впишется, потом впишется целиком строка от второго запроса, и потом допишется первая. Вы получите невалидный JSON или сломанный текст в логе, который невозможно прочитать.

LOCK_EX говорит операционной системе: "Пока один скрипт дописывает строку, поставь второй скрипт на паузу и не давай ему писать". Мелочь, которая экономит часы при отладке сложных интеграций.

Построение микро-роутера на голом PHP

В самом низу моего файла лежит роутинг. Многие сейчас подумают: "Артём, ты что, в 2024 году не использовал ни Laravel, ни Symfony, ни хотя бы Slim Framework?".

Для микро-сервиса, который делает ровно 3 действия, разворачивать целый фреймворк — это убить муху молотком. Цель этого скрипта — быть закинутым по FTP в любую папку на любом самом дешевом shared-хостинге и начать работать мгновенно. Никаких композеров, никаких зависимостей, один файл.

header('Content-Type: application/json; charset=utf-8');
 $b24 = new B24PartnerManager();

try {
    $action = $_GET['action'] ?? $_POST['action'] ?? '';

    // Умный дефолт: если нет action, но есть tour — значит это process
    if ($action === '' && isset($_POST['tour'])) {
        $action = 'process';
    }
    if ($action === '' && (isset($_POST['product_id']) || isset($_GET['product_id']))) {
        $action = 'update_partner';
    }

    switch ($action) {
        case 'list_partners':
            // Отдаем справочник для выпадающего списка на фронтенде
            echo json_encode([
                'success'  => true,
                'count'    => count($b24->getEnumMap()),
                'partners' => $b24->getEnumMap(),
            ], JSON_UNESCAPED_UNICODE | JSON_PRETTY_PRINT);
            break;

        case 'process':
            // ... вызов processTour()
            break;

        case 'update_partner':
            // ... прямое обновление
            break;

        default:
            http_response_code(400);
            echo json_encode($b24->error('Неизвестное действие'), JSON_UNESCAPED_UNICODE);
    }

} catch (Throwable $e) {
    http_response_code(500);
    echo json_encode([
        'success' => false,
        'error'   => 'Exception: ' . $e->getMessage(),
        'file'    => $e->getFile(),
        'line'    => $e->getLine(),
    ], JSON_UNESCAPED_UNICODE);
}

Обратите внимание на блок try...catch (Throwable $e) в самом конце. Это абсолютный мастхэв для любого публичного API. Если где-то в curl_init произойдет фатальная ошибка PHP (например, упадет память, или хостинг заблокирует исходящие соединения), скрипт не выплюнет пользователю белый экран с голым текстом Fatal error: ... in /var/www/assets/partners/b24.php on line 42. Это не только выглядит ужасно, но и является дырой в безопасности (слив путей на сервере).

Мой скрипт перехватит любую ошибку (включая Error и Exception через Throwable), аккуратно вернет клиенту JSON с success: false и текстом ошибки, а реальный stack trace запишется в лог-файл, который видите только я.

Рефакторинг: Что бы я улучшил сейчас

Код рабочий, он лежит на проде, крутится и приносит заказчику пользу. Менеджеры довольны. Но я всегда анализирую свой старый код, и если бы мне сейчас поставили задачу переписать этот сервис, я бы внес два изменения.

1. Кеширование getEnumMap() Сейчас при каждом клике менеджера "Сохранить" скрипт делает 3-4 запроса к API Битрикса. Один из них — выкачивание всего списка значений свойства 133. Справочник партнеров меняется редко (раз в месяц добавляется новый гид). Делать запрос в Битрикс за этим справочником при каждом сохранении — это неоправданная нагрузка на API (особенно на тарифах с лимитами в 2 запроса в секунду).

Я бы добавил простейшее файловое кеширование:

 $cacheFile = __DIR__ . '/cache_enum_133.json';
if (file_exists($cacheFile) && (time() - filemtime($cacheFile)) < 3600) {
    return json_decode(file_get_contents($cacheFile), true);
}
// ... иначе дергаем API, сохраняем результат в $cacheFile и возвращаем

Это снизило бы время ответа скрипта и нагрузку на Битрикс в 2 раза.

2. CURLOPT_SSL_VERIFYPEER = false В моем базовом методе call() вы увидите эту строку. Я выключил проверку SSL сертификатов целенаправленно, потому что знал, что скрипт будет лежать на дешевом хостинге заказчика, где часто криво настроены корневые сертификаты, и curl отказывался ходить в Битрикс.

Но в Enterprise-решениях никогда так не делайте. Это открывает возможность для Man-In-The-Middle (MITM) атак. Кто-то на узле связи может подменить сертификат Битрикса и перехватить ваш webhook или токен авторизации. В идеале нужно правильно настроить CA bundle на сервере и оставить CURLOPT_SSL_VERIFYPEER = true.

Итоги

Интеграция со справочниками (enum-свойствами) в Битрикс24 через REST API — это всегда боль. Вы не можете работать с ними по человечески (через текст), вы обязаны переводить текст во внутренние числовые ID.

Мой опыт показывает: не пытайтесь заставить фронтенд всегда присылать вам правильные ID. Пишите бэкенд-трансформаторы. Выкачивайте карту enum, делайте локальный нечеткий поиск (хоть тем же stripos), нормализуйте любые форматы входящих данных в единный массив, и, самое главное, пишите подробные логи каждого шага с блокировками файлов, потому что API Битрикс24 иногда молчит об ошибках валидации.

Надеюсь, этот разбор моего боевого кода сэкономит вам пару бутылок валерьянки при следующей интеграции. Если у вас есть свои грабли, на которые вы наступили при работе со свойствами товаров — делитесь в комментариях, обсудим!