rustams/develop-b24-python

Develop Битрикс24 Python Backend

Quick Start

The Python backend is built with Django and uses b24pysdk for Битрикс24 interaction.

Key Directories

• backends/python/api/main/views.py: API endpoints.
• backends/python/api/main/models.py: Database models (Bitrix24Account).
• backends/python/api/main/utils/: Decorators and helpers.

Creating API Endpoints

Use the @auth_required decorator to handle authentication (JWT or OAuth).

from django.http import JsonResponse
from django.views.decorators.http import require_GET
from django.views.decorators.clickjacking import xframe_options_exempt
from .utils.decorators import auth_required, log_errors
from .utils import AuthorizedRequest

@xframe_options_exempt
@require_GET
@log_errors("my_endpoint")
@auth_required
def my_endpoint(request: AuthorizedRequest):
    # Access Битрикс24 account
    b24_account = request.bitrix24_account
    
    # Use the client to call Битрикс24 API
    client = b24_account.client
    deals = client.call("crm.deal.list", {"select": ["ID", "TITLE"]})
    
    return JsonResponse({"data": deals})

Битрикс24 Interaction (b24pysdk)

The request.bitrix24_account.client provides a wrapper around b24pysdk.

Common Operations

# Call a single method
result = client.call("crm.deal.get", {"id": 123})

# Batch request (if supported by SDK wrapper, otherwise use call_batch)
# Check b24pysdk documentation for specific batch syntax

Authentication Flow

1. Installation: /api/install receives OAuth data, creates Bitrix24Account.
2. Token Issue: /api/getToken issues a JWT for the frontend.
3. Requests: Frontend sends JWT in Authorization header. @auth_required validates it and populates request.bitrix24_account.

Database

• Models: Defined in main/models.py.
• Migrations: Run automatically in Docker, or manually via python manage.py makemigrations / migrate.
• Bitrix24Account: Stores tokens and portal info.

Best Practices

1. Decorators: Always use @xframe_options_exempt, @log_errors, and @auth_required for API views.
2. Typing: Use AuthorizedRequest for type hinting.
3. Error Handling: log_errors catches exceptions, but handle specific logic errors within the view.
4. Async: Django views are synchronous by default. For long operations, use Celery (see instructions/queues/python.md).

CRM smart-process stages (media template installer)

When applying a captured media template to a new smart process (strict_full), custom intermediate stages (e.g. MEDIA_EXPIRING) may fail on the first run with Bitrix errors such as (RU) «Нельзя создать промежуточную стадию после успешной» — API rejects crm.status.add.

Cause: Bitrix compares SORT of the new stage to existing terminal stages (SUCCESS / FAIL). The snapshot may carry high SORT values from the reference process while the target portal already has SUCCESS at a lower SORT. An intermediate with SORT ≥ that terminal is treated as “after success” and is rejected, even if application order neutralizes terminals (SEMANTICS P) first.

Implementation in this repo: main/services/media_template_apply.py — _apply_stages computes the minimum SORT among target rows whose suffix matches template terminals (S/F semantics), then clamps SORT on new intermediate crm.status.add calls so they sit strictly below that floor. Related helpers: neutralize S/F → P, _delete_uc_placeholder_intermediates, _wait_for_category_stages_ready before stage sync. Unit tests: main/tests/test_media_template_stage_sync.py (including sort-clamp case).

Do not assume the snapshot is empty on first apply if stages are missing — confirm with API warnings / logs. A misleading theory is “card_views-only snapshot with empty stages_by_category”; runtime evidence may show a full crm_template_snapshot and a SORT rejection instead.

Debugging installer code in Docker

The api container usually mounts only backends/python/api. Paths like repo .cursor/debug-*.log are not visible inside the container, so file-based debug logs there fail silently unless you also log to stdout. Prefer django.conf.settings.BASE_DIR for writable NDJSON under the mounted tree, and/or logger.info(...) so docker compose logs api shows lines during reproduction.