Інтеграція 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 — тайлові карти для власного рендерингу

Для інтеграції з 1С-Бітрікс найчастіше використовується Maps API для виведення карти на сторінці та Geocoder API для автоматичного визначення координат при додаванні адрес в адміністративній частині.

Підключення MapGL на сторінках 1С-Бітрікс

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

// 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 1С-Бітрікс
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 при оновленні елементів інфоблоку.

Синхронізація даних: 1С-Бітрікс ↔ 2ГІС Business API

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

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

1С-Бітрікс (інфоблок «Філії») → Агент → 2ГІС Business API → картки організацій

Агент 1С-Бітрікс раз на добу перевіряє зміни в інфоблоці (за полем 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 без ключа з обмеженнями за кількістю запитів. Комерційне використання — за договором, вартість залежить від кількості завантажень карти на місяць.

Терміни