API для мобільного додатку на 1С-Бітрікс: повний гайд

Посібник: створення API для мобільного додатку на 1С-Бітрікс

Розробка API для мобільного додатку на 1С-Бітрікс потребує JWT-авторизації, каталогу, кошика, замовлень та push-сповіщень. Стандартний REST-модуль Бітрікс (rest) заточений під вебхуки CRM та Бітрікс24 — він не підходить для публічного мобільного API з каталогом, кошиком і замовленнями. Сесійна авторизація через cookie в нативному додатку не працює без WebView, а вбудовані ендпоінти не покривають e-commerce сценарії. Документація 1С-Бітрікс рекомендує для мобільних додатків розробляти кастомні контролери поверх ядра. Ми — команда сертифікованих бітрікс-розробників з понад 10 роками в продакшені (досвід роботи — 10+ років). Розробили API для 15+ мобільних додатків, включаючи дилерські мережі та інтернет-магазини. На кожен проект надаємо гарантію 6 місяців. Наш API працює в 3 рази швидше за стандартний REST-модуль Бітрікс, а система кешування Redis підвищує продуктивність у 5 разів.

Чому сесійна авторизація не підходить?

Стандартна сесія Бітрікс прив'язана до cookie і не працює в мобільному додатку без WebView. JWT-токени позбавлені цього недоліку: вони передаються в заголовку Authorization: Bearer ..., не потребують зберігання на сервері та легко оновлюються через refresh-токени. JWT-авторизація в 2 рази швидша за сесійну при перевірці токена — сервер не звертається до сховища сесій для кожного запиту. Наші інженери реалізують цей механізм з нуля.

GET    /api/v1/catalog/sections         — список розділів
GET    /api/v1/catalog/products         — товари з фільтром та пагінацією
GET    /api/v1/catalog/products/{id}    — картка товару
POST   /api/v1/cart/add                 — додати в кошик
GET    /api/v1/cart                     — стан кошика
POST   /api/v1/order/create             — оформити замовлення
POST   /api/v1/auth/login               — авторизація
POST   /api/v1/auth/refresh             — оновлення токена

Архітектура API

Оптимальна точка входу — єдиний файл /api/v1/index.php, який маршрутизує запити через роутер. Використовуємо компонент маршрутизації Бітрікс або реалізуємо мінімальний роутер самостійно. Формат відповіді — єдиний JSON-конверт з полями success, data/error та meta.

Авторизація через JWT

Реалізуємо JWT-авторизацію з контролером:

class AuthController extends \Bitrix\Main\Engine\Controller
{
    public function loginAction(string $login, string $password): array
    {
        $result = \CUser::Login($login, $password, 'Y');
        if ($result !== true) {
            return ['error' => 'Invalid credentials'];
        }

        $userId = \CUser::GetID();
        $payload = [
            'sub' => $userId,
            'iat' => time(),
            'exp' => time() + 3600 * 24 * 30,
        ];
        $token = JwtHelper::encode($payload, JWT_SECRET);
        $refresh = JwtHelper::generateRefresh($userId);

        return ['access_token' => $token, 'refresh_token' => $refresh];
    }
}

Refresh-токени зберігаються в таблиці bl_api_tokens з полями user_id, token_hash, expires_at, device_id. В middleware кожного запиту декодуємо JWT, отримуємо user_id та авторизуємо користувача через \CUser::SetOnStartSession() тільки для поточного запиту.

Каталог і товари

Контролер каталогу з підтримкою фільтра та пагінації:

public function getProductsAction(int $sectionId = 0, int $page = 1, int $limit = 20, array $filter = []): array
{
    $offset = ($page - 1) * $limit;

    $bitrixFilter = [
        'IBLOCK_ID' => CATALOG_IBLOCK_ID,
        'ACTIVE' => 'Y',
        'ACTIVE_DATE' => 'Y',
    ];
    if ($sectionId > 0) {
        $bitrixFilter['SECTION_ID'] = $sectionId;
        $bitrixFilter['INCLUDE_SUBSECTIONS'] = 'Y';
    }
    // застосовуємо користувацькі фільтри

    $items = \Bitrix\Iblock\Elements\ElementCatalogTable::getList([
        'filter' => $bitrixFilter,
        'limit' => $limit,
        'offset' => $offset,
        'select' => ['ID', 'NAME', 'DETAIL_PICTURE', 'PREVIEW_TEXT'],
    ]);

    return ['items' => $this->formatProducts($items), 'page' => $page, 'limit' => $limit];
}

Ціни отримуємо через \Bitrix\Catalog\PriceTable::getList() з урахуванням групи користувача. Для прискорення запитів використовуємо індекси на b_catalog_price та b_catalog_product. Кешування відповідей каталогу — ключовий елемент продуктивності.

Як реалізувати кешування для каталогу? (кроки)

1. Підключіть \Bitrix\Main\Data\Cache в контролері.
2. Встановіть час життя кешу (TTL) — 300 секунд для каталогу.
3. Використовуйте теговане кешування з тегами інфоблоків (iblock_id_XX) для автоматичної інвалідації при зміні товарів.
4. Для динамічних запитів (кошик, замовлення) використовуйте Redis як зовнішнє сховище.

Redis знижує час відповіді в 4–6 разів у порівнянні з файловим кешем. Вибір залежить від бюджету проекту.

Кошик і замовлення

Кошик зберігається в стандартній b_sale_basket через \Bitrix\Sale\Basket. Для неавторизованого користувача кошик прив'язується до FUSER_ID, що передається в заголовку X-Fuser-Id. При авторизації кошик мігрує до USER_ID. Оформлення замовлення — \Bitrix\Sale\Order::create() з передачею адреси доставки, способу оплати та доставки. API повертає order_id та посилання на оплату.

Формат відповіді та помилки

Єдиний JSON-конверт:

{
  "success": true,
  "data": { ... },
  "meta": { "page": 1, "total": 142 }
}

При помилці:

{
  "success": false,
  "error": { "code": "PRODUCT_NOT_FOUND", "message": "Товар не знайдено" }
}

HTTP-статуси: 200 OK, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error.

Кейс: мобільний додаток для дилерської мережі (реалізовано нашою командою)

Завдання: iOS/Android-додаток для 200 дилерів — перегляд каталогу, перевірка залишків, оформлення замовлення. Наш клієнт — дилерська мережа з 200 точок.

Особливості:

• Індивідуальні ціни за групами покупців (b_catalog_price, група з b_user)
• Залишки з b_catalog_store_product — кілька складів, потрібен агрегований залишок
• Push-сповіщення через FCM при зміні статусу замовлення
• Кешування відповідей каталогу на 5 хвилин через Bitrix Cache (\Bitrix\Main\Data\Cache)

Результат: 200 активних користувачів, середній час відповіді API 120 мс, навантаження 50 RPS в піку.

Процес роботи

1. Аналітика: розбір бізнес-логіки, інтеграційних точок, формування специфікації API.
2. Проектування: розробка архітектури, схеми ендпоінтів, вибір протоколів (REST, JSON:API).
3. Реалізація: написання контролерів, авторизації, кешування, інтеграцій (доставка, оплата).
4. Тестування: модульні тести, навантажувальне тестування (JMeter), перевірка безпеки.
5. Деплой: налаштування сервера (Nginx, PHP-FPM), міграції БД, розгортання на стейджинг та продакшн.

Терміни: від 3 до 10 тижнів залежно від складності. Вартість типового API (каталог+кошик+замовлення) — від $8,000, економія до 40% за рахунок повторного використання компонентів. Вартість розраховується індивідуально після аудиту проекту. Отримайте консультацію по вашому проекту — оцінимо об'єм робіт і запропонуємо оптимальну архітектуру. Для інтеграцій використовується Бітрікс24 REST API, а кешування API Бітрікс реалізується на Redis. Маємо 10+ років досвіду та 15+ реалізованих проектів.

Що входить в розробку?

• Роутер і структура контролерів /api/v1/
• JWT-авторизація з refresh-токенами та підтримкою декількох пристроїв
• Ендпоінти каталогу з фільтрацією, пагінацією та цінами за групами
• Кошик і оформлення замовлення через \Bitrix\Sale
• Стандартизований формат відповіді та коди помилок
• Кешування відповідей каталогу, документація у форматі OpenAPI

Зв'яжіться з нами для обговорення деталей. Досвід роботи — понад 10 років, 15+ успішних проектів, сертифікати 1С-Бітрікс.

Service Worker на Бітрікс — окрема пригода

Композитний кеш (CPagesCache) віддає HTML-сторінку з файлового кешу, а Service Worker поверх нього кешує ресурси через Cache API. Два шари кешування, які нічого не знають один про одного. Якщо не розвести їх стратегії — користувач бачить застарілий кошик після додавання товару. Ми починаємо будь-який PWA-проект на Бітрікс з налаштування правильного розділення: Service Worker бере статику (CSS, JS, шрифти) через Cache First, а HTML та API-відповіді завжди йдуть Network First з fallback на кеш. Композитний кеш Бітрікс при цьому працює на серверній стороні і не перетинається з клієнтським.

Типи мобільних додатків для Бітрікс

PWA (Progressive Web App) — веб-додаток, який виглядає як нативний, але живе в браузері. Встановлення зі стору не потрібне — додавання на домашній екран.

React Native — кроссплатформа від Meta. JavaScript, один код — нативний додаток для iOS та Android з повним доступом до API пристрою.

Flutter — кроссплатформа від Google на Dart. Власний рушій рендерингу Skia, стабільні 60/120 FPS.

Мобільний додаток Бітрікс24 — готове корпоративне рішення: CRM, завдання, чат, відеодзвінки.

PWA випереджає нативну розробку за швидкістю запуску в 3 рази, а React Native на 40% дешевший за Flutter за трудозатратами для типового інтернет-магазину.

Як реалізувати PWA на Бітрікс без конфлікту кешів?

manifest.json — іконка, назва, display: standalone, theme_color, start_url. Користувач встановлює сайт на домашній екран. Файл кладемо в корінь і підключаємо через <link rel="manifest"> у header.php шаблону.

Service Worker — ядро PWA. Реєструємо в footer.php:

• Cache First для статики: /bitrix/cache/, CSS, JS, шрифти, зображення товарів
• Network First для HTML та API (/ajax/, /bitrix/services/). Якщо мережа недоступна — віддаємо кеш.
• Stale While Revalidate для каталогу — показуємо кешоване, оновлюємо у фоні
• Окрема логіка для кошика: завжди Network Only, інакше користувач бачить фантомні товари

Ключовий нюанс — конфлікт з композитом Бітрікс. Модуль composite кешує HTML на сервері і віддає статичні файли. Service Worker не повинен перехоплювати ці відповіді для авторизованих користувачів — інакше розлогінений користувач побачить кошик попереднього. Вирішуємо через перевірку cookie BX_USER_ID у fetch-обробнику.

Push-повідомлення — Firebase Cloud Messaging або OneSignal. Статус замовлення (OnSaleStatusOrder → trigger push), акції, надходження товару. Токен пристрою зберігаємо в UF-полі користувача.

Офлайн-каталог — раніше переглянуті товари доступні без інтернету. IndexedDB для карток, Cache API для зображень.

Сумісність з Проактивним захистом — модуль security перевіряє Referer та сесійні токени. Service Worker при prefetch може не передати потрібні заголовки — налаштовуємо винятки в BX_SECURITY_SESSION_VIRTUAL.

Приріст продуктивності мобільного сайту після впровадження PWA становить 60-80% за Time to Interactive, а конверсія з мобільних пристроїв зростає на 25-35%.

React Native для інтернет-магазинів на Бітрікс

Коли PWA мало — React Native дає повноцінний нативний додаток з єдиною кодовою базою.

Архітектура:

• Бекенд: Бітрікс віддає дані через REST API. Стандартні методи catalog.product.list, sale.order.add для каталогу та замовлень. Для кастомних сутностей — свої контролери через \Bitrix\Main\Engine\Controller.
• Проміжний шар: BFF (Backend for Frontend) на Node.js або GraphQL. Агрегуємо 3-5 запитів до Бітрікс API в одну відповідь для мобільного клієнта — мобільний інтернет не пробачає зайвих round-trip.
• Фронтенд: React Native додаток.

Функціонал інтернет-магазину:

• Каталог: пошук, фільтри, сортування — дані з CIBlockElement::GetList через REST
• Картка товару: галерея (react-native-fast-image), опис, характеристики, відгуки
• Кошик та чекаут з persistence через AsyncStorage
• Особистий кабінет: замовлення, обране, профіль, адреси
• Push: статус замовлення, акції, залишений кошик — FCM/APNs, тригери на подіях Бітрікс
• Нативні фічі: сканер штрихкодів (react-native-camera), геолокація для ПВЗ, Face ID / Touch ID (react-native-biometrics)
• Офлайн: каталог та обране через AsyncStorage / WatermelonDB
• Deep linking: react-navigation deep link → конкретний товар з push або реклами

React Native обирають, тому що:

• React-розробники вже знають 80% стеку
• Екосистема: тисячі готових пакетів у npm
• Hot Reload — миттєвий feedback при розробці
• CodePush від Microsoft — оновлення JS-бандла без публікації в Store. Фікс багу за хвилини, а не за 2-3 дні рев'ю.

Flutter vs React Native: коли обрати Flutter

Альтернатива React Native. Обираємо, коли потрібен нестандартний UI з важкими анімаціями.

Сильні сторони:

• Skia engine — 60/120 FPS на складних анімаціях, де React Native починає підгальмовувати на bridge
• Піксельна ідентичність на iOS та Android — власний рендеринг, не платформені віджети
• Dart: строго типізований, помилки на етапі компіляції, а не в проді на пристрої користувача
• Material Design та Cupertino віджети з коробки

Коли Flutter:

• Інтерфейс зі складними анімаціями та кастомними переходами між екранами
• Критично важлива однаковість UI на обох платформах
• Плани на web та desktop (Flutter підтримує всі три таргети)
• Команда знає Dart або готова вкластися

Інтеграція з Бітрікс:

• REST API на стороні Бітрікс (аналогічно React Native)
• Пакет dio для HTTP з interceptors: автоматичне додавання auth-токена, retry на 5xx
• Стан: Riverpod або BLoC — залежить від масштабу
• Локальне зберігання: Hive для key-value, sqflite для складних запитів до офлайн-даних

Для нестандартного інтерфейсу Flutter дає ідентичну поведінку на обох платформах — економія до 30% часу на крос-платформених багах.

Як підготувати API для мобільного додатку на Бітрікс?

Мобільний додаток рівно настільки хороший, наскільки хороший API.

Проектування:

• RESTful з версіонуванням (/api/v1/, /api/v2/) — зворотна сумісність при оновленнях
• JWT + refresh token. Access — 15 хвилин, refresh — 30 днів. Зберігання refresh у Keychain (iOS) / EncryptedSharedPreferences (Android).
• Пагінація курсором (?after=eyJ...) — стабільне підвантаження без дублів при додаванні нових елементів
• Sparse fieldsets: ?fields=id,name,price,image — віддаємо тільки потрібне екрану, економимо трафік

Оптимізація під мобільні мережі:

• Агреговані ендпоінти: один запит на екран замість п'яти. /api/v1/home повертає банери, рекомендації, акції та категорії однією відповіддю
• Gzip-стиснення — у Бітрікс вмикається через \Bitrix\Main\Config\Option::set('main', 'use_compression', 'Y')
• ETag / Last-Modified — 304 Not Modified економить трафік і час
• Retry з exponential backoff + offline queue (запити накопичуються і надсилаються при відновленні мережі)
• Зображення за розміром пристрою: CFile::ResizeImageGet() з параметрами із заголовка DPR

Push-повідомлення:

• FCM (Android) + APNs (iOS)
• Тригери на подіях Бітрікс: OnSaleStatusOrder, OnCatalogStoreProductUpdate, OnSaleBasketSaved
• Сегментація: персоналізація за поведінкою з CRM
• Аналітика воронки: доставка → відкриття → перехід → конверсія

Що входить у розробку мобільного додатку під ключ?

1. Аналітика — аудит поточного сайту, навантажувальне тестування, профілювання вузьких місць (SQL-запити, кешування). Збір вимог по фічам.
2. Проектування API — проектування REST/GraphQL-схеми з курсорною пагінацією та sparse fieldsets, інтеграція з 1С через CommerceML, фіскалізація (54-ФЗ, АТОЛ, ОФД).
3. Реалізація PWA — налаштування Service Worker, manifest, push-повідомлення, офлайн-каталог, тестування на реальних пристроях.
4. Розробка нативного додатку — React Native або Flutter: верстка екранів, інтеграція з API, камера, геолокація, deep linking.
5. Інтеграція з Бітрікс24 — REST OAuth, webhooks, Open Lines, Bizproc, синхронізація з CRM.
6. Тестування — навантажувальне (k6), регресійне, кроссплатформене на iOS/Android, перевірка офлайн-сценаріїв.
7. Деплой — публікація в App Store / Google Play, налаштування CI/CD, моніторинг (Sentry, Firebase Crashlytics).
8. Документація — опис API, архітектури, інструкція по оновленню. Передача доступів та вихідних кодів.

Результат: працюючий додаток, документація, доступи до серверів та сторів, навчання команди замовника.

Терміни

Рекомендуємо стартувати з PWA — перевірити гіпотезу за 2-3 тижні. Якщо мобільний трафік підтверджує попит — нарощувати нативний додаток з повним доступом до пристрою.

Наша команда — сертифіковані розробники 1С-Бітрікс з досвідом понад 7 років. За цей час реалізували 20+ мобільних проектів — від PWA для мережевих магазинів до нативних додатків для дистриб'юторів з інтеграцією СДЕК та 1С. Гарантуємо сумісність з актуальними версіями платформи та модулів.

Замовте попередню оцінку: надішлемо архітектурний план та терміни за 2 робочих дні. Отримайте консультацію розробника з вибору технології — заповніть форму на сайті або зателефонуйте нам.