Разработка интеграции Битрикс24 с банковскими системами

Разработка интеграции Битрикс24 с банковскими системами

Интеграция CRM с банком — это не просто «смотреть выписку прямо в сделке». Это синхронизация платёжного статуса, автоматическое проведение счетов, контроль дебиторки и триггеры для воронки продаж. Реализация зависит от конкретного банка и того, какой API он предоставляет. Разберём архитектуру от общего к частному.

Что обычно нужно бизнесу

Прежде чем проектировать интеграцию, важно зафиксировать конкретные сценарии. Из практики, запросы распадаются на три группы:

Исходящие платежи. Выгрузка платёжных поручений из Битрикс24 в банк — минуя ручной ввод в клиент-банк. Менеджер создаёт счёт на оплату поставщику в CRM, финансовый директор утверждает, система автоматически формирует платёжку и отправляет в банк по API.

Входящие платежи. Webhook или polling выписки: как только банк фиксирует поступление на счёт — сделка в CRM меняет стадию, менеджер получает уведомление, формируется акт. Без интеграции менеджер узнаёт об оплате случайно или в конце дня.

Справочные операции. Проверка баланса, получение курсов валют, верификация реквизитов контрагента (через API ФНС или непосредственно через банковский сервис проверки).

Технические пути интеграции

OpenAPI банка. Большинство крупных банков РФ (Сбер, Тинькофф, Альфа, ВТБ) предоставляют REST API для бизнеса. Аутентификация — OAuth 2.0 с Client Credentials flow. Банк выдаёт client_id и client_secret, в обмен получаем access_token с ограниченным временем жизни (обычно 30 минут). Токен обновляется через refresh_token или повторной аутентификацией. Хранить токены нужно в защищённом хранилище — шифруем в базе или используем переменные окружения.

1С-интерфейс (directbank). Ряд банков поддерживает протокол DirectBank (прямой обмен без клиент-банка). Технически это XML-протокол поверх HTTPS, формат документов — совместимый с 1С. Если в компании уже есть 1С:Бухгалтерия с настроенным DirectBank, интеграцию Битрикс24 проще строить через 1С как посредник, а не напрямую с банком.

Файловый обмен. Классический вариант — выгрузка в формате 1C:Enterprise (.txt c заголовком 1CClientBankExchange) и импорт в клиент-банк вручную или через автоматическое подключение папки. Не требует API-доступа, работает с любым банком.

Архитектура приложения в Битрикс24

Интеграция реализуется как локальное приложение или встроенный REST-обработчик. Схема:

Битрикс24 CRM
   ↓ Webhook / Robot
Обработчик (PHP, собственный сервер или серверная часть приложения)
   ↓ OAuth2 token
Банковский API
   ↓ Response
Обновление сущностей CRM через crm.deal.update / crm.invoice.update

Для входящих платежей — обратная схема: банк отправляет webhook на наш endpoint, который через crm.deal.update или crm.timeline.comment.add обновляет состояние сделки.

Хранение состояния платежей: заводим UF_BANK_PAYMENT_ID (пользовательское поле) на сделке и счёте — внешний идентификатор платежа в банке. Это позволяет идемпотентно обрабатывать повторные webhook-уведомления и проверять статус конкретного платежа.

Работа с выпиской

Банковская выписка приходит в формате JSON (через API) или SWIFT MT940/camt.053 (для международных банков). Парсим транзакции: сумма, дата, назначение платежа, ИНН плательщика. По ИНН или номеру счёта ищем контрагента в CRM через crm.company.list с фильтром по реквизитам. Если контрагент найден — ищем открытый счёт на соответствующую сумму.

Сложность — назначение платежа. «Оплата по счёту № 145 от 12.03.2025» — хорошо, распарсить номер счёта несложно. «Оплата за услуги» — плохо, нужна ручная привязка. Для второго случая строим интерфейс ручного мэтчинга: список нераспознанных поступлений, возможность привязать к сделке вручную.

Безопасность и хранение ключей

Банковский API — критичный интеграционный контур. Требования:

• Токены хранятся в зашифрованном виде (AES-256), ключ шифрования — в переменных окружения, не в коде
• Запросы к API идут только через HTTPS, проверка SSL-сертификата обязательна
• Логи всех API-вызовов с маскированием чувствительных данных (номер счёта, сумма — логируем, CVV и токены — никогда)
• IP-whitelist на стороне банка — разрешаем только IP наших серверов
• Для webhook endpoint — валидация подписи запроса (банк подписывает payload HMAC-SHA256 секретным ключом)

Обработка ошибок и ретраи

Банковские API нестабильны. Типичные сценарии: таймаут при создании платежа (неизвестно, прошёл он или нет), временная недоступность сервиса, лимиты запросов (rate limiting). Под каждый сценарий — своя логика.

Для критичных операций (отправка платёжного поручения) используем очередь с идемпотентными ключами: перед отправкой генерируем idempotency_key (UUID), передаём в заголовке запроса. При повторной попытке с тем же ключом банк не дублирует платёж.

Этапы разработки

Конкретные сроки сдвигаются в зависимости от качества документации банка и наличия sandbox-среды. У Тинькофф и Альфы песочницы хорошие. У ряда региональных банков — нет, и тогда отладка ведётся аккуратно в продакшн-среде с тестовыми суммами.