Интеграция 1С-Битрикс с 2ГИС

Интеграция 1С-Битрикс с 2ГИС

Яндекс.Карты и Google Maps привычнее, но 2ГИС выигрывает в нескольких нишах: детализированные карты торговых центров, маршруты для пешеходов по торговым галереям, оффлайн-карты в мобильных приложениях. Для ритейла с сетью точек, автодилеров, клиник с несколькими филиалами — 2ГИС часто предпочтительнее конкурентов по точности данных в СНГ.

Интеграция 1С-Битрикс с 2ГИС

API 2ГИС: что доступно

2ГИС предоставляет несколько API-продуктов:

• Maps API (MapGL) — JavaScript-библиотека для отображения карт, маркеров, маршрутов
• Places API — поиск организаций, получение информации о них
• Geocoder API — геокодирование адресов (адрес → координаты и обратно)
• Routing API — построение маршрутов
• Tiles API — тайловые карты для собственного рендеринга

Для интеграции с Битрикс чаще всего используется Maps API для вывода карты на странице и Geocoder API для автоматического определения координат при добавлении адресов в административной части.

Подключение MapGL на страницах Битрикс

Добавление карты в шаблон компонента:

// result_modifier.php или template.php
\Bitrix\Main\Page\Asset::getInstance()->addJs(
    'https://mapgl.2gis.com/api/js/v1'
);

// Передаём координаты из свойств инфоблока
$arResult['MAP_LAT'] = (float)$arResult['PROPERTIES']['LAT']['VALUE'];
$arResult['MAP_LNG'] = (float)$arResult['PROPERTIES']['LNG']['VALUE'];

// template.js
const map = new mapgl.Map('map-container', {
    center:  [<?= $arResult['MAP_LNG'] ?>, <?= $arResult['MAP_LAT'] ?>],
    zoom:    15,
    key:     '<?= DGIS_API_KEY ?>',
});

new mapgl.Marker(map, {
    coordinates: [<?= $arResult['MAP_LNG'] ?>, <?= $arResult['MAP_LAT'] ?>],
});

Ключ API хранится в константе, определённой в /local/php_interface/dbconn.php или через \Bitrix\Main\Config\Option.

Геокодирование при сохранении адресов

Типичная задача: менеджер вводит адрес филиала в административной части, координаты должны проставляться автоматически. Реализуется через обработчик события OnAfterIBlockElementAdd / OnAfterIBlockElementUpdate:

// /local/php_interface/init.php
\Bitrix\Main\EventManager::getInstance()->addEventHandler(
    'iblock',
    'OnAfterIBlockElementUpdate',
    'geocodeAddressOn2GIS'
);

function geocodeAddressOn2GIS(array &$arFields): void
{
    if ($arFields['IBLOCK_ID'] != BRANCHES_IBLOCK_ID) return;

    $address = $arFields['PROPERTY_VALUES'][BRANCH_ADDRESS_PROP_ID][0]['VALUE'] ?? '';
    if (!$address) return;

    $coords = Dgis\GeocoderClient::geocode($address);
    if (!$coords) return;

    \CIBlockElement::SetPropertyValuesEx($arFields['ID'], BRANCHES_IBLOCK_ID, [
        'LAT' => $coords['lat'],
        'LNG' => $coords['lng'],
    ]);
}

Класс Dgis\GeocoderClient:

namespace Dgis;

class GeocoderClient
{
    private const API_URL = 'https://catalog.api.2gis.com/3.0/items/geocode';

    public static function geocode(string $address): ?array
    {
        $response = \Bitrix\Main\Web\HttpClient::query(
            'GET',
            self::API_URL . '?' . http_build_query([
                'q'      => $address,
                'fields' => 'items.point',
                'key'    => \Bitrix\Main\Config\Option::get('mymodule', 'dgis_api_key'),
            ])
        );

        $data = json_decode($response->getContent(), true);
        $point = $data['result']['items'][0]['point'] ?? null;

        if (!$point) return null;

        return ['lat' => $point['lat'], 'lng' => $point['lon']];
    }
}

Карта сети филиалов: кластеризация маркеров

Для сетей с большим количеством точек (50+) одиночные маркеры на карте превращаются в нечитаемую кашу. MapGL поддерживает кластеризацию через mapgl.ClusterLayer:

// Загружаем все точки через AJAX из REST Битрикс
const response = await fetch('/local/ajax/branches.php');
const branches = await response.json();

const source = new mapgl.GeoJsonSource(map, {
    data: {
        type: 'FeatureCollection',
        features: branches.map(b => ({
            type: 'Feature',
            geometry: { type: 'Point', coordinates: [b.lng, b.lat] },
            properties: { name: b.name, address: b.address, id: b.id },
        })),
    },
    attributes: { cluster: true },
});

/local/ajax/branches.php возвращает JSON из кэшированного запроса к инфоблоку. Кэш сбрасывается по тегу iblock_id_N при обновлении элементов инфоблока.

Синхронизация данных: Битрикс ↔ 2ГИС Business API

2ГИС предоставляет Business API для управления собственными карточками организаций — обновление контактов, фото, часов работы напрямую через API без ручного входа в личный кабинет.

Схема синхронизации:

Битрикс (инфоблок «Филиалы») → Агент → 2ГИС Business API → карточки организаций

Агент Битрикс раз в сутки проверяет изменения в инфоблоке (по полю DATE_MODIFY) и отправляет обновления через API. Используется модуль main, агенты в таблице b_agent.

// Регистрация агента
\CAgent::AddAgent(
    'DgisSyncAgent::run();',
    'mymodule',
    'N',  // не разовый
    86400, // каждые 24 часа
);

Использование Places API для поиска организаций

Если на сайте есть поиск по базе партнёров, дилеров, точек выдачи — Places API позволяет получить официальные данные 2ГИС об организации по её ID в базе 2ГИС:

$client = new \Bitrix\Main\Web\HttpClient();
$client->query('GET',
    'https://catalog.api.2gis.com/3.0/items?id=' . $dgisOrgId .
    '&fields=items.contact_groups,items.schedule,items.rubrics' .
    '&key=' . DGIS_API_KEY
);
$orgData = json_decode($client->getResult(), true);

Данные сохраняются в свойства инфоблока и выводятся в карточке партнёра.

Работа с 2ГИС без серверного ключа

В режиме разработки или для некоммерческих проектов можно использовать MapGL без ключа с ограничениями по числу запросов. Коммерческое использование — по договору, стоимость зависит от количества загрузок карты в месяц.

Сроки