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

Розробка інтеграції Bitrix24 з банківськими системами

Інтеграція CRM з банком — це не просто «переглядати виписку прямо в угоді». Це синхронізація платіжного статусу, автоматичне проведення рахунків, контроль дебіторки та тригери для воронки продажів. Реалізація залежить від конкретного банку та того, який API він надає. Розглянемо архітектуру від загального до часткового.

Що зазвичай потрібно бізнесу

Перш ніж проєктувати інтеграцію, важливо зафіксувати конкретні сценарії. З практики, запити розпадаються на три групи:

Вихідні платежі. Вивантаження платіжних доручень із Bitrix24 до банку — минаючи ручне введення у клієнт-банк. Менеджер створює рахунок на оплату постачальнику в CRM, фінансовий директор затверджує, система автоматично формує платіжку і відправляє до банку через API.

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

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

Технічні шляхи інтеграції

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

1C-інтерфейс (DirectBank). Ряд банків підтримує протокол DirectBank (прямий обмін без клієнт-банку). Технічно це XML-протокол поверх HTTPS, формат документів — сумісний з 1С. Якщо в компанії вже є 1С:Бухгалтерія з налаштованим DirectBank, інтеграцію Bitrix24 простіше будувати через 1С як посередник, а не безпосередньо з банком.

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

Архітектура застосунку в Bitrix24

Інтеграція реалізується як локальний застосунок або вбудований REST-обробник. Схема:

Bitrix24 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-середовища. У деяких банків пісочниці хороші. У ряду регіональних банків — немає, і тоді налагодження ведеться обережно в продакшн-середовищі з тестовими сумами.