rapid-bitrix24-connector

Python library for expedient interaction with the Bitrix24 platform via its exposed REST API.

• Core Capabilities
• Getting Started
• Usage Examples
• Operational Mechanics
• Tips and Troubleshooting
• Author Contact
• Detailed API Reference

Core Capabilities

Superior Data Throughput

• Achieves throughput rates reaching thousands of records per second when handling extensive entity lists.
• Automatic request aggregation into batches minimizes the total number of server calls, dramatically improving efficiency.
• Batched requests are dispatched concurrently rather than sequentially.
• Advanced pagination strategies provide significant speedups for bulk data extraction (refer to performance benchmarks).

Server Load Mitigation

• Strict adherence to all documented Bitrix rate-limiting guidelines (Official Bitrix24 Request Velocity Policy).
• Intelligent autothrottling: Request velocity automatically decelerates upon detection of server error responses.
• For particularly taxing operations, manual speed reduction can be enforced using a single configuration line.

Development Convenience

• High-level abstraction methods reduce boilerplate code; most common operations require only a single line. Concurrency management, request bundling, and other complexities are handled internally.
• Allows specification of API parameters exactly as defined in the Bitrix24 REST API documentation. Parameters undergo validation to aid in debugging.
• Request execution is visually tracked using a tqdm progress bar, showing processed items, elapsed time, and estimated remaining time.
• [OAuth Authorization]: For application integrations, the client monitors token expiry and automatically refreshes it using a user-supplied callback function.

Synchronous and Asynchronous Clients

• Availability of an asynchronous client enables seamless integration into event-driven architectures (e.g., Telegram bots).

Adoption Highlights

• Used by Yandex

Getting Started

Install the module using pip: shell pip install fast-bitrix24

Then, in your Python environment:

python from fast_bitrix24 import Bitrix

Substitute with your actual Bitrix24 REST Webhook URL

webhook = "https://your_domain.bitrix24.ru/rest/1/your_code/" bx = Bitrix(webhook)

Subsequent interactions with the Bitrix24 server are executed via methods on the instantiated bx object.

Usage Examples

get_all()

To fetch the complete collection of entities, utilize the get_all() method:

python

Retrieve all leads

leads = bx.get_all('crm.lead.list')

The get_all() function returns a list where each element is a dictionary representing a single entity from the requested collection.

You can customize the query using the params argument:

python

Get active deals, including custom fields

deals = bx.get_all( 'crm.deal.list', params={ 'select': ['', 'UF_'], 'filter': {'CLOSED': 'N'} })

get_by_ID()

If you possess a collection of entity IDs, their properties can be retrieved using get_by_ID() by invoking methods structured like *.get:

python ''' Fetch all contacts linked to deals, structured as: { Deal_ID_1: [contact_1, contact_2, ...], Deal_ID_2: [contact_1, contact_2, ...], ... } '''

contacts = bx.get_by_ID( 'crm.deal.contact.items.get', [d['ID'] for d in deals])

The get_by_ID() method yields a dictionary mapping ID: result, where result is the server's response pertaining to that specific ID.

call()

For operations involving the creation, modification, or deletion of multiple entities, use the call() method:

python

Prepend the ID to the title of all deals

tasks_payload = [ { 'ID': d['ID'], 'fields': { 'TITLE': f'{d["ID"]} - {d["TITLE"]}' } } for d in deals ]

bx.call('crm.deal.update', tasks_payload)

The call() method returns a list containing the server responses corresponding to each item in the input payload.

call(raw=True)

Invoking call with raw=True forwards the supplied arguments directly to the server without any internal batching optimization, returning the raw server response unmodified.

This mode is useful for debugging, or critically, for requests that: - Contain None in parameters (as None is used to erase field values, which batching interferes with), - Utilize legacy Bitrix24 methods expecting a list as input (see #157).

python

Erase the DESCRIPTION field for lead 123

params = {"ID": 123, "fields": {"DESCRIPTION": None}} bx.call('crm.lead.update', params, raw=True)

Add a comment to a task

bx.call( 'task.commentitem.add', [123, {"POST_MESSAGE": "Task update comment"}], raw=True )

call_batch()

To invoke a native batch method, use call_batch():

python results = bx.call_batch ({ 'halt': 0, 'cmd': { 'deals': 'crm.deal.list', # Fetch deal list # Fetch activities related to the first deal retrieved 'activities': 'crm.activity.list?filter[ENTITY_TYPE]=3&filter[ENTITY_ID]=$result[deals][0][ID]' } })

Asynchronous Invocations

If library usage demands an asynchronous context (e.g., within Jupyter notebooks), instantiate the BitrixAsync client instead of Bitrix: python from fast_bitrix24 import BitrixAsync bx = BitrixAsync(webhook)

All methods on this client mirror their synchronous counterparts but are awaitable: python leads = await bx.get_all('crm.lead.list')

OAuth Authorization

For OAuth workflows, initialize the Bitrix() client by supplying the application endpoint URL to the webhook argument, and pass a reference to an asynchronous function that handles token retrieval to the token_func parameter: python from fast_bitrix24 import Bitrix import requests

async def get_new_token() -> str: oauth_url = 'https://oauth.bitrix.info/oauth/token/' params={ 'grant_type': 'refresh_token', 'client_id': ..., 'client_secret': ..., 'refresh_token': ... } result = requests.get(oauth_url, timeout=10, params=params) return result.json()["access_token"]

Note: webhook here is the authorization endpoint URL

bx = Bitrix(webhook=ENDPOINT_ADDRESS, token_func=get_new_token) ...

token_func will be executed whenever an initial token fetch or a refresh operation is necessary.

Operational Mechanics

1. Before any server communication within Bitrix class methods, input parameters are validated. TypeError or ValueError exceptions are raised for invalid inputs.
2. Requests are formulated to retrieve all items belonging to the specified list endpoint.
3. These formulated requests are bundled into batches, capped at 50 requests per batch.
4. The resulting batches are dispatched to the server concurrently, with request pacing dynamically managed (see section below on velocity control).
5. Server responses (specifically the content of the result field) are aggregated into a single, flattened list returned to the user.
   • Exceptions of type aiohttp.ClientError are raised if the Bitrix server returns an HTTP error code. A RuntimeError is raised if the HTTP status is 200 but an error object is present within the response body.
   • Result ordering is maintained (except for get_all())—the order of elements in the final result list matches the order of their corresponding requests.

For the get_all() method, step 2 is slightly more intricate: - get_all() initiates the first API call with the specified method and parameters. - The server returns the first page (up to 50 records) alongside a total field indicating the overall count of matching records. - Based on the total count, subsequent requests are generated for every remaining page (approximately total // 50 - 1 additional requests) required to fetch the entire dataset.

Because fetching large datasets with get_all() can be lengthy, if new entities are added during the process, the final count may diverge from the initial total. In such cases, a standard Python warning will be issued.

How rapid-bitrix24-connector Manages Request Velocity

The library respects Bitrix24's official limits (Official Bitrix24 Request Velocity Policy). Furthermore, it implements adaptive slowdowns (autothrottling) when the server signals errors. This dual approach significantly enhances data retrieval performance (see velocity tests).

Official Bitrix24 Request Velocity Policy

Two constraints operate concurrently: 1. Leaky Bucket Algorithm enforcement: https://dev.1c-bitrix.ru/learning/course/index.php?COURSE_ID=93&LESSON_ID=7885 2. Sliding Window enforcement, applied per distinct API method: https://helpdesk.bitrix24.ru/open/15959788

The library ensures compliance with both policies.

Tips and Troubleshooting

'Does your library support...?'

Consult the API Reference. If your question remains unanswered, contact the developer.

How do I configure a Webhook?

Refer to the official REST API documentation 1. Navigate to the Incoming Webhook section and follow the steps:
Create an incoming webhook under Developers (Applications > Developers, 'Ready Scenarios' tab > Other > Incoming Webhook). 2. Assign a descriptive name to the webhook. 3. The generated URL string, containing the token, is your webhook address. 4. Crucially, configure the necessary permissions (failure to specify rights will result in authorization failure).

• The Request Generator block is a utility for testing API methods and inspecting sample responses; it does not affect webhook setup.
• General setup information is also available in the help article.

How should I format a request to Bitrix for a specific action?

1. First, search the official REST API documentation.
2. If the documentation doesn't resolve your issue, try asking in the Bitrix24 Developer Community "Partner REST API" group.
3. Ask in the Bitrix24 Developers Telegram group.
4. Ask in the rapid-bitrix24-connector Telegram user group.
5. Inquire on Russian StackOverflow.

How can I see the exact payload sent and the server's response?

Enable request and response logging: python import logging

logging.getLogger('fast_bitrix24').addHandler(logging.StreamHandler())

I encounter server errors when placing heavy load. What can I do?

Method 1

Wrap your Bitrix interactions within the slow context manager:

python with bx.slow(): results = bx.call('crm.lead.add', tasks)

See [API.md#контекстный-менеджер-slowmaxconcurrentrequests-int--1) for details on the slow context manager.

Method 2

When initializing the client, adjust the parameters governing server load:

python bx = Bitrix( webhook, request_pool_size = 20, # Default is 50 requests_per_second = 1.0, # Default is 2.0 batch_size = 20, # Default is 50 operating_time_limit = 100, # Default is 480 )

I only need to execute call() once, not for a list of items.

Pass the request parameters directly to call(); it accommodates both single requests and list-based operations:

python method = 'crm.lead.add' params = {'fields': {'TITLE': 'Quick Test'}} bx.call(method, params)

The return value will be the server's response for that single operation.

However, if multiple such single calls are frequent, it is more efficient to compile them into a list and execute them via one batch call to call().

How are results sorted when using get_all()?

Currently, they are not sorted intrinsically.

All server communication occurs asynchronously, meaning the returned list is ordered based on when the server finished processing and returning each chunk. If explicit ordering is needed, you must implement it yourself, for example:

python deals = bx.get_all('crm.deal.list') deals.sort(key = lambda d: int(d['ID']))

Fetching all fields for all list items via get_all() is excessively slow. How to speed this up?

When constrained by Bitrix's rate limits, the primary optimization involves minimizing the data volume transferred and maintaining compliant download speeds. This can be achieved through intelligent caching and reducing the number of fields requested.

Violating the velocity policy results in penalties, so we advise adhering to it (parameter respect_velocity_policy=True).

I am receiving an SSL certificate error. What is the solution?

If you encounter SSLCertVerificationError / CERTIFICATE_VERIFY_FAILED, try disabling the SSL certificate verification: python bx = BitrixAsync(webhook, ssl=False)

I am running this code in notebooks or Spyder and experiencing errors.

Your execution environment likely manages the asyncio event loop internally (more details).

Utilize the asynchronous client. Replace this code block:

python from fast_bitrix24 import Bitrix bx = Bitrix(webhook) leads = bx.get_all('crm.lead.list')

With this:

python from fast_bitrix24 import BitrixAsync bx = BitrixAsync(webhook) leads = await bx.get_all('crm.lead.list')

I am using an Enterprise installation. How do I configure higher request throughput?

In the client constructor, specify request_pool_size=250 and requests_per_second=5:

python from fast_bitrix24 import Bitrix bx = Bitrix(webhook, request_pool_size=250, requests_per_second=5)

Author Contact

• Telegram: https://t.me/fast_bitrix24
• Open a new GitHub issue: https://github.com/leshchenko1979/fast_bitrix24/issues/new