Integrating Bitrix24 with electronic signature services

Integrating Bitrix24 with Electronic Signature Services

Installing CryptoPro CSP on every laptop, distributing tokens, and hunting for Browser plug-in bugs after each Chrome update—this is not the only path. Cloud electronic signature services eliminate the workstation binding and allow you to build signing routes with multiple participants, including external contractors.

Which Service for Which Task

For exchanging formalized documents (UPD, invoices) with Russian contractors—use Diadoc or SBIS. For internal signing without tokens—CryptoPro DSS. For international contracts—DocuSign.

Integration Architecture: How It Works Under the Hood

The general scheme is the same for all services, with only the API varying:

1. Document is created in Bitrix24 via the document generator (crm.documentgenerator)
2. A handler retrieves the file through Bitrix24's REST API and passes it to the signature service
3. The service launches a signing route—notifies signers
4. Signers work in the signature service interface (or mobile app)
5. A webhook from the service signals completion
6. The signed document + signature file are uploaded back to Bitrix24

The connecting element is the server-side handler (webhook receiver). In simple cases, a PHP script on hosting. For reliable operation under high load—a task queue via Redis or RabbitMQ with guaranteed delivery and retries on errors.

Integration with Kontur.Diadoc: Full Cycle

Diadoc is Russia's largest EDI operator, and it's most commonly linked with Bitrix24. The REST API is available at https://api.kontur.ru/diadoc/v1/. Let's break down the implementation in detail.

Authentication. Two-stage: first POST /Authenticate with login/password or certificate, then the obtained token is passed in the Authorization: DiadocAuth ddauth_api_client_id={client_id}, ddauth_token={token} header. The token lives for 1 hour. In the middleware, we cache it and update it automatically 5 minutes before expiration—otherwise requests will fail with 401 mid-workday.

Sending a document for signature:

1. Get the file from Bitrix24: crm.documentgenerator.document.get
2. Determine the organization's box: GET /GetMyOrganizations
3. Find the counterparty in Diadoc: GET /GetCounteragent?myOrgId={id}&counteragentOrgId={id}
4. For formalized documents (UPD, act, invoice) — POST /GenerateTitleXml, Diadoc requires XML in FNS format
5. Send: POST /PostMessage with the embedded document and type

For unformalized documents (contracts, amendments) XML is not needed—the file is transmitted as-is.

Tracking status. Diadoc supports two mechanisms:

• Polling — GET /GetDocflowEvents?afterEventId={id} — retrieve events after the specified ID
• Webhook subscriptions — notifications on status change via partner access

In practice, Diadoc webhooks can be delayed by minutes during peak loads. A reliable scheme: webhook as a trigger for immediate status check, polling every 5 minutes as a safety net. This way events are not lost and the API is not burdened with unnecessary requests.

Getting the signed document:

GET /GetMessage?boxId={boxId}&messageId={msgId}&entityId={entityId}

The response includes all document versions, signatures from each party, time stamps. We extract the signed version and signature file (.sig), upload to Bitrix24 via disk.file.upload, bind to the deal.

Signature refusal. The counterparty may request clarification or reject the document. Diadoc sends an event with a comment. The handler creates a task for the manager in Bitrix24 (tasks.task.add) with the refusal text and returns the deal to the revision stage via crm.deal.update.

Multi-Party Signing Routes

Real document flow is not a single signature. Typical scenarios:

Sequential signing: a contract is signed first by your side, then by the counterparty. The order is strictly fixed.

Parallel signing: a reconciliation act is signed by both parties independently.

Signing with internal approval: before the executive's signature, the document is reviewed by the legal team and CFO. Review—UNEP, final signature—QES.

In the API of signature services, the route is described as a set of steps with participants, action type, and order:

{
  "document_id": "doc-456",
  "workflow": [
    {"step": 1, "action": "approve", "participants": ["[email protected]"], "type": "sequential"},
    {"step": 2, "action": "sign", "participants": ["[email protected]"], "type": "sequential"},
    {"step": 3, "action": "sign", "participants": ["[email protected]"], "type": "sequential"}
  ]
}

What Is Stored in Bitrix24 After Signing

After the cycle is complete, the CRM should contain:

• Original document (PDF)
• Detached signature file (.sig) — CAdES or XAdES
• Signing report — who, when, with which certificate

Files are uploaded to Bitrix24.Disk in the structure Signed Documents / [Year] / [Month] / [Deal ID]. In the deal's custom fields, the signing date, document number in the EDI system, and status are recorded.

Notifications and Sales Pipeline Automation

Each status change of a document in the EDI service is mirrored in Bitrix24:

• Chat notification (im.notify.system.add) — to the responsible manager
• Move the deal stage (crm.deal.update) — automatically when both parties have signed
• Timeline comment (crm.timeline.comment.add) — a record with event details
• Task on refusal (tasks.task.add) — to the manager for document revision

The manager doesn't track statuses manually—the system itself notifies and moves the deal through the funnel.

Implementation Stages

Cloud electronic signatures through an external service remove dependency on a specific computer. The manager sends a document from the deal card, the counterparty signs in the EDI operator's interface, the signed version automatically returns to the CRM. No tokens on every workstation, no scanner, no waiting for a courier.