Интеграция с банком (выписки): Точка, Модульбанк

Загрузка банковской выписки по API — самый надёжный способ автоматически подтверждать безналичные оплаты B2B-заказов. Точка и Модульбанк дают открытые REST-интерфейсы, и связать их с 1С-Битрикс можно без посредников в виде 1С или клиент-банка.

Зачем сайту на Битрикс банковская выписка

В B2B-продажах значительная часть заказов оплачивается по счёту на расчётный счёт. Пока платёж не подтверждён, заказ висит в статусе «ожидает оплаты», менеджер вручную сверяет банк и меняет статус, а клиент не понимает, приняли деньги или нет. Автоматическая загрузка выписки закрывает этот разрыв: система сама видит поступление и переводит заказ в оплаченный статус.

Интеграция с банком по API решает несколько задач одновременно:

• Автоподтверждение оплаты — приход по счёту закрывает соответствующий заказ без участия человека;
• Сверка и антидубли — каждая проводка обрабатывается один раз, повторная загрузка не создаёт лишних записей;
• Актуальный остаток — баланс счёта можно показывать в админке или использовать в бизнес-логике;
• История платежей контрагента — привязка проводок к профилю компании в CRM.

API Точки и Модульбанка: что доступно

Оба банка предоставляют REST API поверх HTTPS с авторизацией по токену. Механики отличаются в деталях, но набор операций для задачи «получить выписку» схожий.

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

Архитектура интеграции в 1С-Битрикс

Правильное место для такой логики — отдельный модуль (например /local/modules/vendor.bankstatement/), а не код в шаблоне или в обработчике страницы. Модуль инкапсулирует работу с API, хранение настроек и обработчики событий.

Загрузку выписки удобно вешать на агент Битрикса или на cron с блокировкой от параллельного запуска:

1. Агент раз в 5–15 минут запрашивает операции за период с момента последней успешной синхронизации;
2. Каждая проводка проверяется на дубль по идентификатору операции банка;
3. Новые приходные операции ставятся в очередь на сопоставление с заказами;
4. Исходящие и служебные операции просто логируются.

Настройки (токены, номер счёта, интервал) храните в опциях модуля через Bitrix\Main\Config\Option, а сами проводки — в собственной таблице ORM или Highload-блоке, чтобы иметь индекс по идентификатору операции и дате.

Минимальный вызов API выглядит так:

$http = new Bitrix\Main\Web\HttpClient();
$http->setHeader('Authorization', 'Bearer '.$token);
$json = $http->get($apiUrl.'?from='.$dateFrom.'&to='.$dateTo);
$data = Bitrix\Main\Web\Json::decode($json);

Сопоставление платежей с заказами

Самая содержательная часть — понять, к какому заказу относится поступившая сумма. В B2B назначение платежа обычно содержит номер счёта или заказа, но менеджеры банка клиента могут его исказить. Поэтому нужна многоступенчатая логика:

• По номеру счёта/заказа — регулярным выражением вытаскиваем номер из поля назначения платежа и ищем заказ;
• По ИНН плательщика — сопоставляем с контрагентом в CRM, сужаем круг неоплаченных заказов этой компании;
• По сумме — если у контрагента один неоплаченный заказ на точную сумму, привязываем автоматически;
• Ручная привязка — спорные проводки уходят в интерфейс оператора, где он подтверждает соответствие в один клик.

После однозначного сопоставления модуль регистрирует оплату штатными средствами Битрикса. В коммерческом ядре D7 это $payment->setPaid('Y') у объекта оплаты заказа с последующим $order->save() — так корректно отработают статусы, события и уведомления.

Отдельно обрабатывайте частичную и переплату: приход меньше суммы заказа фиксируйте как частичную оплату, излишек — выносите в задачу для бухгалтера, а не гасите заказ автоматически.

Безопасность токенов и приём вебхуков

Токен доступа к расчётному счёту — критичный секрет. Его компрометация даёт доступ к финансовым данным, поэтому к хранению и передаче предъявляются жёсткие требования.

• Не храните токен в коде и в репозитории — только в настройках модуля или в переменных окружения вне публичной директории;
• Все запросы к API — строго по HTTPS с проверкой сертификата, без отключения верификации;
• Для вебхуков заведите отдельный URL со сложным непредсказуемым сегментом и проверяйте подпись/секрет из заголовка;
• Ограничьте права токена в кабинете банка до чтения выписки, если платёжные операции через API вам не нужны;
• Ведите журнал обращений к API и алертинг на всплеск ошибок авторизации.

Точка при истечении JWT требует его перевыпуска — предусмотрите обновление токена и понятное сообщение в админке, когда срок вышел. Модульбанк использует долгоживущий токен, но его тоже стоит периодически ротировать вручную.

Типичные ошибки и мониторинг

За годы внедрений набор проблем повторяется. Их проще предотвратить на этапе проектирования, чем ловить в продакшене.

Обязательно логируйте каждый цикл синхронизации: сколько операций получено, сколько привязано автоматически, сколько ушло на ручной разбор. Для мониторинга удобно завести отдельный лог через Bitrix\Main\Diag\FileLogger и настроить уведомление, если очередь непривязанных проводок растёт.

Итог

Прямое подключение сайта на 1С-Битрикс к API Точки и Модульбанка автоматизирует подтверждение безналичных оплат: система сама загружает выписку, сопоставляет проводки с заказами по номеру счёта и ИНН и переводит их в оплаченный статус. Ключевые условия надёжности — защита от дублей по идентификатору операции, комбинация вебхуков с фоновой сверкой и аккуратное хранение токенов.

Мы проектируем такие интеграции как отдельный модуль с очередью, логированием и интерфейсом ручного разбора спорных платежей, а при необходимости связываем контур сайт—банк—1С в единую цепочку. Если нужно автоматизировать приём оплат по счетам без ручной сверки, поможем спроектировать и внедрить решение под вашу учётную схему.