Development of Bitrix24 integration with an electronic document management system

Development of Bitrix24 Integration with an Electronic Document Management System

When a company operates in Bitrix24 as a CRM and simultaneously uses an EDMS for internal document workflow, a gap emerges: a contract is formed in the CRM while approval happens in another system. A manager copies a file, sends it for approval, waits for a response, and manually updates the deal status. Integration eliminates this gap — documents synchronize automatically, approvals are initiated from the CRM, and statuses update in both directions.

EDMS Landscape: What We're Integrating With

Several document management systems dominate the Russian market:

From the Bitrix24 side, integration is built on REST API — the only official way to interact with the cloud version. For self-hosted versions, module events and direct database access are also available, but REST remains the preferred option for solution portability.

Integration Points in Bitrix24

Document Generation — crm.documentgenerator.*

Bitrix24 REST API provides methods for working with the document generator:

• crm.documentgenerator.document.add — create document from template
• crm.documentgenerator.document.get — get document with its properties
• crm.documentgenerator.document.list — list documents of an entity
• crm.documentgenerator.template.list — available templates

A document is generated from a template (docx with placeholders) using data from a CRM entity (deal, contact, company). The result is a ready file that needs to be sent to the EDMS for approval.

File Storage — Bitrix24.Drive

All documents are stored on Bitrix24.Drive. REST methods:

• disk.folder.getchildren — folder contents
• disk.file.upload — upload file
• disk.file.get — get file
• disk.attachedobject.get — files attached to entities

Via Drive, you can organize versioning: each approval iteration is a new file version with a comment about changes made.

Bitrix24 Business Processes

Built-in business processes (BP) are triggered on deals, leads, and list items. BP actions:

• Employee notification
• Approval / rejection
• Entity field changes
• Webhook / REST request call

The last point is key to integration. From a business process, you can send an HTTP request to the EDMS, passing document data and initiating the approval process.

Integration Architecture

A typical interaction scheme:

Bitrix24                    Middleware                    EDMS
    │                            │                          │
    ├── Create document ─────────┤                          │
    │                            ├── Send for              │
    │                            │   approval ──────────────┤
    │                            │                          │
    │                            │◄── Webhook:              │
    │                            │    status changed ───────┤
    ├── Update deal ◄────────────┤                          │
    │   status                   │                          │
    │                            │◄── File: signed ────────┤
    ├── Upload file ◄────────────┤    version              │
    │   to Drive                 │                          │

Middleware is an intermediate service (Laravel, Node.js, Python) that performs several functions:

• Transforms data formats between the APIs of the two systems
• Processes queues (EDMS may not respond immediately)
• Logs all operations for audit
• Handles errors and retries

It's possible to skip middleware if the integration is simple (one EDMS, linear process). In this case, Bitrix24 communicates with the EDMS directly via webhook handlers.

Deep-dive: Approval Routes and Status Synchronization

Document approval is the central process of integration and simultaneously the most complex. Let's break it down in detail.

Types of Approval Routes:

• Sequential — document passes through a chain: legal → finance director → general director. Each next participant receives the document only after approval from the previous one.
• Parallel — document is sent to multiple approvers simultaneously. Approval from all (or majority, depending on settings) is sufficient.
• Conditional — route depends on document parameters. A contract under 100,000 rubles is approved by department head; above — by commercial director.

Status Mapping. EDMS and Bitrix24 use different status models. A mapping table is needed:

Real-Time Synchronization. The optimal approach is webhook notifications from the EDMS on each status change. If the EDMS doesn't support webhooks (e.g., older 1C:Dokumentooborot versions), use polling — periodic API queries with 1-5 minute intervals.

Webhook handler on the middleware side:

POST /api/sed-webhook
{
    "document_id": "DOC-2024-1234",
    "new_status": "approved",
    "approved_by": "[email protected]",
    "timestamp": "2024-03-15T14:30:00+03:00",
    "comments": "",
    "signed_file_url": "https://sed.company.ru/files/DOC-2024-1234-signed.pdf"
}

Middleware finds the associated deal in Bitrix24 by document_id (mapping is stored in the database), updates the stage via crm.deal.update, uploads the signed file via disk.file.upload, adds a comment to the deal timeline via crm.timeline.comment.add.

Conflict Handling. Scenario: a manager changes a document in Bitrix24 while it's under approval in the EDMS. Strategies:

• Blocking — while the document is under approval, editing in B24 is forbidden (via access rights or validation in event handler)
• Versioning — each change creates a new version; approval restarts
• Notification — manager gets a warning; decision is made manually

In practice, blocking is most often used — it's simpler to implement and clearer to users.

Notifications and Process Transparency

It's critical that process participants see current status without switching between systems. Realized through:

• Bitrix24 notifications (im.notify.system.add) — on each EDMS status change
• Deal custom field — "Approval Status" with change history
• Timeline comments — automatic record "Document approved by Ivanov I.I. 15.03.2024 14:30"
• Deal card widget (embedding via placement) — displays current route with visual progress indicator

Implementation Stages

CRM and EDMS integration removes manual labor at the interface between two systems. A manager works in Bitrix24, approvers work in the familiar EDMS, and the document passes through the route automatically.