Bitrix24 API Gateway: Caching, Batch, Token Management

Bitrix24 API Gateway: Caching, Batch, Token Management

We often see the same issue: a mobile app, external site, and ERP system simultaneously working with the Bitrix24 REST API. Each client stores its own tokens, each must know the method specifics and bypass limits. This is inconvenient, insecure and slows down development. An API gateway is an intermediate layer we design for your project. It standardizes interaction: client applications call the gateway with a simple interface, and the gateway translates calls to Bitrix24, aggregates data, and returns a normalized response. Assess your project in one day — just get in touch with us.

Why Do You Need an API Gateway for Bitrix24?

Hiding Bitrix24 API complexity. Retrieving a deal with all related data (contact, company, products, tasks, activities) requires 5–7 separate REST calls to different methods. The gateway makes one call /deals/123, gathers all data in parallel, and returns a single JSON to the client.

Token management. Client applications do not store Bitrix24 tokens. The gateway is the single place where OAuth tokens are stored, access_token is refreshed via refresh_token, and rotation is controlled.

Bypassing limits. Cloud Bitrix24 restricts: 2 requests per second, 50 operations per batch. The gateway implements a queue and rate limiter — clients send requests as fast as they want, and the gateway smooths out the load. Direct integration requires calculating limits on the client side; the gateway takes this over.

Why Does an API Gateway Reduce Development Costs?

Instead of each client team learning the intricacies of the Bitrix24 REST API, the gateway provides a single, documented interface. Developers spend less time on integration and more on business logic. In practice, this reduces time-to-market for new features by 30%.

Gateway Architecture and Authentication

The gateway is a separate HTTP service, typically PHP (Laravel/Slim) or Node.js. It sits between clients and Bitrix24.

Clients (mobile app, external site, ERP)
        ↓  HTTP/JSON (gateway's own API)
  API Gateway
    ├── Client authentication (JWT / API Key)
    ├── Input validation
    ├── Rate limiter
    ├── Cache (Redis)
    ├── Request mapper → Bitrix24 REST
    └── Batch aggregator
        ↓  OAuth2 Token
  Bitrix24 REST API

Authentication via API Key

Simplest for server-to-server. The client sends the key in the X-API-Key header. The gateway validates the key in its database, identifies the linked Bitrix24 account and permissions.

Authentication via JWT

For clients with users. The user logs in (via Bitrix24 OAuth or a custom system), the gateway issues a JWT token. Each request to the gateway carries the JWT in the Authorization: Bearer header. The gateway decodes the token, identifies the user, and acts on their behalf in Bitrix24.

Authentication via OAuth 2.0

If the gateway serves multiple client applications from different organizations, build a full OAuth server (Authorization Code Flow). Each client application is a separate OAuth client of the gateway.

How Caching and Batch Speed Up Performance

Two cache levels:

Cache key: b24:{portal_id}:{method}:{hash(params)}. On webhook event ONCRMDEALUPDATE with ID=123 — invalidate b24:portal1:crm.deal.get:hash({id:123}). Thanks to caching, response time drops 5x compared to direct requests.

Bitrix24 supports batch: up to 50 methods in one HTTP request. The gateway aggregates parallel client calls into a batch. According to official Bitrix24 REST API documentation, this drastically reduces HTTP connections. Example batch request:

// Client calls 3 gateway resources "simultaneously"
// Gateway combines them into one batch to Bitrix24:
$batch = [
    'deal' => 'crm.deal.get?id=123',
    'contact' => 'crm.contact.get?id=456',
    'products' => 'crm.deal.productrows.get?id=123',
];
$result = $b24->batch($batch);

To fetch a deal with all data, the gateway forms a batch of 4–5 methods, executes one HTTP request to Bitrix24, and assembles the result.

Data Transformation and Normalization

Gateway normalizes Bitrix24 responses. From an object with string fields like 'OPPORTUNITY' => '50000.00' we get a typed response:

{
  "id": 123,
  "title": "Deal with company ABC",
  "amount": 50000.00,
  "stage": "negotiation",
  "contact": {
    "id": 456,
    "name": "Ivan Petrov",
    "phone": "+79001234567"
  }
}

Mapping is defined in the gateway configuration — this allows changing the response structure without modifying clients.

Fault Tolerance and Monitoring

If Bitrix24 is unavailable or responds with error 503 Too Many Requests, the gateway should not simply return that error to clients. We implement a circuit breaker:

• Closed (normal operation): requests pass through to Bitrix24
• Open (Bitrix24 unavailable): gateway immediately returns cached data or a clear error, without queuing requests
• Half-Open (recovery check): periodically attempts a test request to Bitrix24

The gateway exports metrics to Prometheus/Grafana or writes to ELK: latency per method (p50, p95, p99), error rate by error code, request queue size, cache hit rate, current Bitrix24 limit (from X-RateLimit-Remaining header).

What's Included in Development

Phases and Timeline

An API gateway is especially justified when several applications work with Bitrix24 simultaneously, or when client developers should not know the specifics of the Bitrix24 API. For a single small integration scenario, it may be overkill. Get a consultation with an engineer — order end-to-end API gateway development. We have completed 50+ integrations for projects of various sizes.

1C-Bitrix Module Development and Setup

The main trap of Bitrix is init.php. You add an OnBeforeIBlockElementUpdate handler there, then another one — a year later the file is 2000 lines, and on every hit all that code executes. We move business logic into full-fledged modules with D7 ORM, custom tables, and administrative interface. The module can be disabled, transferred to another project, covered with tests — none of that is possible with init.php. Our team has 10+ years of Bitrix experience, certified specialists, and a 6-month code guarantee. Request a consultation — we'll explain how to migrate legacy code to a modular architecture.

Why is init.php the worst place for business logic?

Init.php does not support class autoloading, lacks an isolated namespace, cannot be unit tested, and cannot be disabled without editing the file itself. Every handler written there runs on every request, even if not needed. In a module, you register handlers through EventManager, and they only execute when the event occurs. Performance difference: up to 3x with 10+ handlers.

Standard Modules: Typical Problems and Solutions

Information blocks. IBlock architecture is the first thing we review on any project. A classic mistake: one catalog infoblock with 80 properties, 30 of which are multiple. The b_iblock_element_property table swells to millions of rows, and CIBlockElement::GetList with filtering on three properties does a full scan. We move reference data to Highload-blocks, eliminate multiple properties where possible, and design the structure for 5x growth.

e-Store (sale). Cart business rules are a separate story. We set discount priorities to prevent two campaigns from giving 60% instead of 30%, connect payment handlers, and write custom validation via OnSaleOrderBeforeSaved.

Search. The built-in search module with morphology works up to 10–15 thousand elements. Beyond that — Elasticsearch. We configure it via the Bitrix search module API, indexing through CSearchFullText or custom indexers.

Highload-blocks for dictionaries, logs, user data — instead of bloated IBlocks. Direct queries via Bitrix\Highloadblock\HighloadBlockTable, custom tables instead of the EAV structure of standard infoblocks. A million records — no degradation.

Mail events. Configuration is not just templates in b_event_message. The key is SPF, DKIM, DMARC on the DNS, otherwise transactional emails go to spam. We check deliverability and set up bounce handling.

How to Design Infoblocks for Performance?

We use Highload-blocks for reference data (colors, sizes, manufacturers) that are not involved in complex queries. For SKUs — a separate infoblock with linking via IBLOCK_ELEMENT_PROPERTY. Enable INDEX_PROPERTY for frequently filtered properties. Tagged caching: when an element changes, only the related cache is cleared. Highload-blocks process up to 10x faster than infoblocks with multiple properties on volumes of 100,000 records.

Custom Module Development

Each module follows the structure /local/modules/vendor.modulename/:

• install/index.php — setup class, create tables via $DB->RunSQLBatch()
• lib/ — D7 ORM classes, extending Bitrix\Main\ORM\Data\DataManager
• admin/ — administrative pages using CAdminList, CAdminForm
• include.php — autoloading, event handler registration via EventManager::getInstance()->registerEventHandler()
• REST API endpoints via \Bitrix\Rest\RestManager

The module registers in the system, appears in the "Installed Solutions" list, and has its own settings at /bitrix/admin/settings.php?mid=vendor.modulename. It can be enabled, disabled, and updated through UpdateSystem or custom migration mechanics.

Examples of implemented tasks:

• Campaign management — visual condition builder via CAdminCalendar, timers via agents (CAgent::AddAgent), analytics linked to the sale module
• Cost calculator — React widget on the frontend, REST API in the module, formulas stored in a Highload-block
• Booking system — real-time calendar, locking via $DB->StartTransaction() / $DB->Commit() on concurrent requests, integration with channel manager via webhook

Components and Composite Cache

Component customization via result_modifier.php and component_epilog.php, not by editing template.php of the standard template. This way core updates are painless.

Composite cache ("Composite Site" technology) — the server sends ready HTML, bypassing PHP routing. Dynamic areas (cart, authorization) are loaded via CBitrixComponent::setFrameMode(true) and AJAX. TTFB drops to 30–50 ms. But there are caveats: not all components are compatible, $APPLICATION->ShowPanel() breaks composite, and careful markup of <div id="bx-composite-..."> is required.

What to Check Before Installing a Marketplace Module?

Before installing a module from the marketplace, an audit is mandatory. We check: SQL queries without prepared statements (hello SQL injection), direct use of $_REQUEST without filtering, use of outdated kernel API instead of D7, conflicts with the composite cache module. A module with no updates for over a year and a few dozen installations is likely a problem on the next PHP update. A typical case: a module calls CIBlockElement::GetList with no cache reset — the site crashes with 5000 elements.

Migration to D7

When upgrading PHP or switching to a new edition — refactor outdated calls:

• CIBlockElement::GetList() → Bitrix\Iblock\Elements\ElementTable::getList()
• CSaleOrder::GetList() → Bitrix\Sale\Order::getList()
• CModule::IncludeModule() → Bitrix\Main\Loader::includeModule() Testing on staging, rollback via git on issues.

According to official 1C-Bitrix documentation, D7 ORM is the recommended tool for working with data, providing type safety and automatic query generation.

Comparison: Init.php vs Module

Module Development Scope and Cost

What is included in module development?

• Technical specification and architectural plan
• Code following PSR-4 and Bitrix code style
• Unit tests (PHPUnit) for business logic
• Integration tests for events and REST API
• Installation, configuration, and API documentation
• Repository and documentation access
• Administrator training for module usage
• 6-month warranty support

Estimated timelines and complexity:

Cost is calculated individually — contact us for a project estimate.

Module Testing

Unit tests via PHPUnit cover business logic: discount calculation, validation, document generation. Mocks for Bitrix\Main\Application::getConnection() allow tests to be DB-independent. Integration tests verify event handlers on a real database — OnAfterIBlockElementAdd, OnSaleOrderSaved, etc. REST API endpoints are tested via curl or PHPUnit HTTP client. Critical for modules working with b_sale_order, b_catalog_price — where errors cost money.

Compatibility is checked on PHP 7.4, 8.0, 8.1, 8.2 and editions: Standard, Small Business, Business. We check conflicts with popular marketplace modules — they often intercept the same events. Load testing: measurements on 10K, 100K, 1M records, profiling via Xdebug for memory leaks and N+1 queries.

Practical Examples

Campaign module for an electronics chain. The built-in sale module discounts did not cover scenarios like "2+1", a gift with purchase over a certain amount, or combined conditions. We built a visual builder: marketers create rules via drag-and-drop without development tickets. Campaign calendar, auto-deactivation via agents, analytics linked to b_sale_order — conversion, average check, usage count. Time to launch a new campaign dropped from two days to half an hour.

Calculator for builders. Parameters (area, materials, number of floors) → formula → preliminary estimate → lead to CRM via CRest::call('crm.lead.add'). Regional coefficients and seasonal markups from a Highload-block, material prices from 1C exchange. The number of target leads increased by a third: clients see a breakdown before calling a manager.

Booking for a hotel chain. Real-time availability via AJAX requests to a custom table vendor_booking_slots, seasonal tariff calculation, synchronization with Booking.com via channel manager API. Room locking on concurrent booking via SELECT ... FOR UPDATE in transactions. Timezones handled via \DateTimeZone — a guest from Vladivostok and a manager from Moscow see the same picture.

We will evaluate your project within one day. Write to us — we'll tell you what is included in turnkey development. Contact us for a consultation on your project. Order a custom module development — get a ready solution with documentation and support.