Creating API for a Mobile App on Bitrix

The standard Bitrix REST module (rest) is tailored for CRM webhooks and Bitrix24 — it is not suitable for a public mobile API with catalog, cart, and orders. Session-based authorization via cookies does not work in a native app without WebView, and built-in endpoints do not cover e-commerce scenarios. Documentation recommends developing custom controllers on top of the kernel for mobile applications. We are a team of certified Bitrix developers with 10+ years in production. We have built APIs for 15+ mobile applications, including dealer networks and online stores.

Why Session Authorization Does Not Work?

Standard Bitrix session is bound to cookies and does not work in a mobile app without WebView. JWT tokens lack this drawback: they are passed in the Authorization: Bearer ... header, do not require server-side storage, and are easy to refresh via refresh tokens. JWT authorization is 2 times faster than session-based when checking the token — the server does not access the session store on every request. Our engineers implement this mechanism from scratch.

GET    /api/v1/catalog/sections         — list sections
GET    /api/v1/catalog/products         — products with filter and pagination
GET    /api/v1/catalog/products/{id}    — product card
POST   /api/v1/cart/add                 — add to cart
GET    /api/v1/cart                     — cart state
POST   /api/v1/order/create             — place order
POST   /api/v1/auth/login               — authorization
POST   /api/v1/auth/refresh             — token refresh

API Architecture

The optimal entry point is a single file /api/v1/index.php that routes requests via a router. We use Bitrix routing component or implement a minimal router ourselves. Response format — a uniform JSON envelope with fields success, data/error, and meta.

Authorization via JWT

We implement JWT authorization with a controller:

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 tokens are stored in table bl_api_tokens with columns user_id, token_hash, expires_at, device_id. In middleware of each request, we decode the JWT, get user_id, and authorize the user via \CUser::SetOnStartSession() only for the current request.

Catalog and Products

Catalog controller with filter and pagination support:

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';
    }
    // apply custom filters

    $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];
}

Prices are obtained via \Bitrix\Catalog\PriceTable::getList() with user group consideration. For query speed, we use indexes on b_catalog_price and b_catalog_product. Caching catalog responses is key for performance.

How to Implement Caching for Catalog? (Steps)

1. Include \Bitrix\Main\Data\Cache in the controller.
2. Set cache TTL – 300 seconds for catalog.
3. Use tagged caching with infoblock tags (iblock_id_XX) for automatic invalidation when products change.
4. For dynamic requests (cart, orders), use Redis as external storage.

Redis reduces response time by 4–6 times compared to file cache. Choice depends on project budget.

Cart and Orders

Cart is stored in standard b_sale_basket via \Bitrix\Sale\Basket. For unauthorized user, cart is bound to FUSER_ID transmitted in header X-Fuser-Id. Upon authorization, cart migrates to USER_ID. Order placement — \Bitrix\Sale\Order::create() with delivery address, payment method, and delivery method. API returns order_id and payment link.

Response Format and Errors

Uniform JSON envelope:

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

On error:

{
  "success": false,
  "error": { "code": "PRODUCT_NOT_FOUND", "message": "Product not found" }
}

HTTP statuses: 200 OK, 400 Bad Request, 401 Unauthorized, 404 Not Found, 500 Internal Server Error.

Case: Mobile App for a Dealer Network (from our practice)

Challenge: iOS/Android app for 200 dealers — catalog browsing, stock check, order placement.

Features:

• Individual prices by customer groups (b_catalog_price, group from b_user)
• Stock from b_catalog_store_product — multiple warehouses, need aggregated stock
• Push notifications via FCM on order status change
• Caching catalog responses for 5 minutes via Bitrix Cache (\Bitrix\Main\Data\Cache)

Result: 200 active users, average API response time 120 ms, peak load 50 RPS.

Process of Work

1. Analytics: analysis of business logic, integration points, forming API specification.
2. Design: architecture development, endpoint schema, protocol selection (REST, JSON:API).
3. Implementation: writing controllers, authorization, caching, integrations (delivery, payment).
4. Testing: unit tests, load testing (JMeter), security check.
5. Deployment: server setup (Nginx, PHP-FPM), DB migrations, staging and production deployment.

Timeline: from 3 to 10 weeks depending on complexity. Cost is calculated individually after project audit. Get a consultation on your project — we will estimate the scope and propose an optimal architecture.

What is Included in Development?

• Router and controller structure /api/v1/
• JWT authorization with refresh tokens and multi-device support
• Catalog endpoints with filtering, pagination, and group prices
• Cart and order placement via \Bitrix\Sale
• Standardized response format and error codes
• Catalog response caching, OpenAPI documentation

Contact us to discuss details. Experience — over 5 years, 15+ successful projects, 1C-Bitrix certificates.

How to choose the right mobile app technology for your Bitrix project?

Service Worker on Bitrix – a separate adventure. The composite cache (CPagesCache) serves an HTML page from the file cache, while the Service Worker caches resources via the Cache API. Two caching layers that know nothing about each other. If you don't separate their strategies, the user sees an outdated cart after adding an item. We start any PWA project on Bitrix by configuring proper separation: Service Worker handles static assets (CSS, JS, fonts) with Cache First, while HTML and API responses always use Network First with a cache fallback. The Bitrix composite cache operates server-side and does not intersect with the client side.

What mobile app types fit your Bitrix ecosystem?

PWA (Progressive Web App) – a web application that looks like a native app but lives in the browser. No store installation needed — add to home screen. React Native – cross-platform by Meta. JavaScript, one codebase — native iOS and Android app with full device API access. Flutter – cross-platform by Google on Dart. Own Skia rendering engine, stable 60/120 FPS. Bitrix24 mobile app – ready-made corporate solution: CRM, tasks, chat, video calls.

PWA beats native development in launch speed by 3 times, and React Native is 40% cheaper than Flutter in labor costs for a typical online store.

How to implement PWA on Bitrix without cache conflict?

manifest.json – icon, name, display: standalone, theme_color, start_url. The user installs the site on the home screen. Place the file in the root and include via <link rel="manifest"> in header.php of the template.

Service Worker – the core of PWA. Register in footer.php:

• Cache First for static: /bitrix/cache/, CSS, JS, fonts, product images
• Network First for HTML and API (/ajax/, /bitrix/services/). If network unavailable – serve cache
• Stale While Revalidate for catalog — show cached, update in background
• Separate logic for cart: always Network Only, otherwise the user sees phantom items

Key nuance – conflict with Bitrix composite. The composite module caches HTML on the server and serves static files. Service Worker should not intercept these responses for authorized users — otherwise a logged-out user will see the previous cart. Solve by checking the BX_USER_ID cookie in the fetch handler.

Push notifications – Firebase Cloud Messaging or OneSignal. Order status (OnSaleStatusOrder → trigger push), promotions, stock arrival. Save device token in user UF field.

Offline catalog – previously viewed items available without internet. IndexedDB for cards, Cache API for images.

Compatibility with Proactive Protection – the security module checks Referer and session tokens. Service Worker during prefetch may not send required headers — configure exceptions in BX_SECURITY_SESSION_VIRTUAL.

Performance improvement of mobile site after PWA implementation is 60-80% Time to Interactive, and mobile conversion rates increase by 25-35%.

According to Wikipedia, PWA combines the best of web and native apps, and with proper Service Worker strategy it works seamlessly on Bitrix CMS.

React Native for online stores on Bitrix

When PWA is not enough – React Native provides a full native app with a single codebase.

Architecture:

• Backend: Bitrix serves data via REST API. Standard methods catalog.product.list, sale.order.add for catalog and orders. For custom entities – custom controllers via \Bitrix\Main\Engine\Controller
• Intermediate layer: BFF (Backend for Frontend) on Node.js or GraphQL. Aggregate 3-5 requests to Bitrix API into one response for the mobile client – mobile internet doesn't tolerate extra round trips
• Frontend: React Native application

Online store functionality:

• Catalog: search, filters, sorting – data from CIBlockElement::GetList via REST
• Product page: gallery (react-native-fast-image), description, specs, reviews
• Cart and checkout with persistence via AsyncStorage
• Personal account: orders, favorites, profile, addresses
• Push: order status, promotions, abandoned cart – FCM/APNs, triggers on Bitrix events
• Native features: barcode scanner (react-native-camera), geolocation for pickup points, Face ID / Touch ID (react-native-biometrics)
• Offline: catalog and favorites via AsyncStorage / WatermelonDB
• Deep linking: react-navigation deep link → specific product from push or ad

React Native is chosen because:

• React developers already know 80% of the stack
• Ecosystem: thousands of ready packages in npm
• Hot Reload – instant feedback during development
• CodePush by Microsoft – update JS bundle without store publication. Fix a bug in minutes instead of 2-3 days of review

Flutter vs React Native: when to choose Flutter

Alternative to React Native. Choose when you need custom UI with heavy animations.

Strengths:

• Skia engine – 60/120 FPS on complex animations where React Native starts to lag due to bridge
• Pixel-perfect identity on iOS and Android – own rendering, not platform widgets
• Dart: strictly typed, errors at compile time, not in production on user's device
• Material Design and Cupertino widgets out of the box

When Flutter:

• Interface with complex animations and custom screen transitions
• Critical to have identical UI on both platforms
• Plans for web and desktop (Flutter supports all three targets)
• Team knows Dart or is ready to invest

Integration with Bitrix:

• REST API on Bitrix side (similar to React Native)
• dio package for HTTP with interceptors: automatic auth token addition, retry on 5xx
• State: Riverpod or BLoC – depends on scale
• Local storage: Hive for key-value, sqflite for complex offline queries

For non-standard interface, Flutter provides identical behavior on both platforms – saving up to 30% of time on cross-platform bugs.

How to prepare API for mobile app on Bitrix?

A mobile app is only as good as its API.

Design:

• RESTful with versioning (/api/v1/, /api/v2/) – backward compatibility during updates
• JWT + refresh token. Access – 15 minutes, refresh – 30 days. Store refresh in Keychain (iOS) / EncryptedSharedPreferences (Android)
• Cursor pagination (?after=eyJ...) – stable loading without duplicates when adding new items
• Sparse fieldsets: ?fields=id,name,price,image – return only what the screen needs, save traffic

Optimization for mobile networks:

• Aggregated endpoints: one request per screen instead of five. /api/v1/home returns banners, recommendations, promotions, and categories in one response
• Gzip compression – in Bitrix enabled via \Bitrix\Main\Config\Option::set('main', 'use_compression', 'Y')
• ETag / Last-Modified – 304 Not Modified saves traffic and time
• Retry with exponential backoff + offline queue (requests accumulate and send when network restores)
• Images by device size: CFile::ResizeImageGet() with parameters from DPR header

Push notifications:

• FCM (Android) + APNs (iOS)
• Triggers on Bitrix events: OnSaleStatusOrder, OnCatalogStoreProductUpdate, OnSaleBasketSaved
• Segmentation: personalization based on CRM behavior
• Funnel analytics: delivery → open → transition → conversion

What is included in turnkey mobile app development?

• Analysis – current site audit, load testing, bottleneck profiling (SQL queries, caching). Feature requirements gathering
• API design – REST/GraphQL schema design with cursor pagination and sparse fieldsets, integration with 1C via CommerceML, fiscalization (54-FZ, ATOL, OFD)
• PWA implementation – Service Worker setup, manifest, push notifications, offline catalog, testing on real devices
• Native app development – React Native or Flutter: screen layout, API integration, camera, geolocation, deep linking
• Bitrix24 integration – REST OAuth, webhooks, Open Lines, Bizproc, CRM synchronization
• Testing – load testing (k6), regression, cross-platform on iOS/Android, offline scenario testing
• Deployment – publication on App Store / Google Play, CI/CD setup, monitoring (Sentry, Firebase Crashlytics)
• Documentation – API description, architecture, update instructions. Handover of access and source code

Result: working application, documentation, server and store access, client team training.

Why is PWA recommended as the first step?

PWA validates your mobile hypothesis quickly. With 2-3 weeks of work you get a working prototype that users can install on their home screen. If mobile traffic and conversion data confirm demand, we scale up to a native app with full device access. This approach reduces upfront investment and provides real metrics before committing to a 4-6 month native development cycle.

Our team consists of certified 1C-Bitrix developers with over 7 years of experience. During this time, we have completed 20+ mobile projects – from PWA for retail chains to native apps for distributors with CDEK and 1C integration. We guarantee compatibility with current platform and module versions.

Order a preliminary assessment: we will send an architectural plan and timeline within 2 business days. Contact us for a developer consultation on technology choice – fill out the form on the website or call. Get your project started with a clear roadmap.