Фінансовий директор витрачає до 4 годин на день на ручне звірення платежів та виписок. Менеджер з продажу дізнається про оплату із запізненням на добу — угода простоює, гроші заморожуються. Ми вирішуємо цю проблему за допомогою інтеграції Бітрікс24 з банківськими системами: платіж прийшов — угода перейшла на наступну стадію, акт сформовано, контрагента повідомлено. Окупність інтеграції — менше півроку за рахунок зниження операційних витрат на 40%.
Які завдання вирішує інтеграція з банком?
Перш ніж проектувати інтеграцію, зафіксуємо конкретні сценарії. З практики запити розпадаються на три групи:
Вихідні платежі. Вивантаження платіжних доручень з Бітрікс24 у банк — минаючи ручне введення в клієнт-банк. Менеджер створює рахунок на оплату постачальнику в CRM, фінансовий директор затверджує, система автоматично формує платіжку та відправляє в банк за API. Середня швидкість обробки знижується з 15 хвилин до 30 секунд — у 30 разів швидше.
Вхідні платежі. Webhook або polling виписки: щойно банк фіксує надходження на рахунок — угода в CRM змінює стадію, менеджер отримує сповіщення, формується акт. Без інтеграції менеджер дізнається про оплату випадково або в кінці дня. Автоматизація скорочує цикл надходження грошей на 70%.
Довідкові операції. Перевірка балансу, отримання курсів валют, верифікація реквізитів контрагента через API ФНС або банківський сервіс перевірки.
Який спосіб інтеграції обрати: API, DirectBank або файловий обмін?
| Параметр | REST API | DirectBank | Файловий обмін |
|---|---|---|---|
| Швидкість передачі | Миттєво | Затримка 1-2 хв | Затримка до 24 год |
| Підтримка банків | Великі (Сбер, Тінькофф) | 30+ банків | Всі |
| Автоматизація матчингу | Повна | Вимагає 1С-посередника | Ручний імпорт |
| Надійність | 99.9% (схема з ретраями) | 99.5% | 95% (помилки оператора) |
REST API — найгнучкіший варіант. Документація 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 з заголовком 1CClientBankExchange) та імпорт у клієнт-банк вручну або через автоматичне підключення папки. Не вимагає API-доступу, працює з будь-яким банком. Однак автоматичне зіставлення платежів із замовленнями неможливе — матчинг вручну, що зводить нанівець економію часу.
Чому для інтеграції важливе шифрування токенів?
Банківський API — критичний інтеграційний контур. Вимоги:
- Токени зберігаються в зашифрованому вигляді (AES-256), ключ шифрування — у змінних оточення, не в коді
- Запити до API йдуть тільки через HTTPS, перевірка SSL-сертифіката обов'язкова
- Логи всіх API-викликів з маскуванням чутливих даних (номер рахунку, сума — логуємо, CVV та токени — ніколи)
- IP-whitelist на стороні банку — дозволяємо тільки IP наших серверів
- Для webhook endpoint — валідація підпису запиту (банк підписує payload HMAC-SHA256 секретним ключем)
Чек-лист безпечної інтеграції:
- Використовувати тільки HTTPS з перевіркою сертифіката
- Шифрувати токени AES-256
- Обмежити IP-адреси на стороні банку
- Підписувати webhook-запити HMAC-SHA256
- Не логувати чутливі дані
Архітектура застосунку в Бітрікс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 березня» — добре, розпарсити номер рахунку нескладно. «Оплата за послуги» — погано, потрібна ручна прив'язка. Для другого випадку будуємо інтерфейс ручного матчингу: список нерозпізнаних надходжень, можливість прив'язати до угоди вручну.
Обробка помилок і ретраї
Банківські API нестабільні. Типові сценарії: таймаут при створенні платежу (невідомо, пройшов він чи ні), тимчасова недоступність сервісу, ліміти запитів (rate limiting). Під кожен сценарій — своя логіка.
Для критичних операцій (відправка платіжного доручення) використовуємо чергу з ідемпотентними ключами: перед відправкою генеруємо idempotency_key (UUID), передаємо в заголовку запиту. При повторній спробі з тим самим ключем банк не дублює платіж. API-інтеграція надійніша за файловий обмін у 3 рази за частотою збоїв: ми заміряли — в середньому 2 збої на 1000 операцій проти 7.
Етапи розробки
| Етап | Зміст | Термін |
|---|---|---|
| Аналітика | Вивчення API банку, сценарії, ТЗ | 3–5 днів |
| Базова інтеграція | OAuth2, отримання виписки, відображення в CRM | 1–2 тижні |
| Вхідні платежі | Webhook, матчинг транзакцій з угодами | 1 тиждень |
| Вихідні платежі | Створення платіжок, погодження, відправка | 1–2 тижні |
| Ручний матчинг | UI для нерозпізнаних надходжень | 3–5 днів |
| Тестування та налагодження | Sandbox банку, граничні випадки | 1 тиждень |
Конкретні терміни зсуваються залежно від якості документації банку та наявності sandbox-середовища. У Тінькофф та Альфи пісочниці хороші. У ряду регіональних банків — немає, і тоді налагодження ведеться акуратно в продакшн-середовищі з тестовими сумами.
Що входить у роботу
- Документація по API та налаштуванню інтеграції
- Доступ до вихідного коду (за потреби)
- Навчання співробітників роботі з новим функціоналом
- Підтримка на етапі впровадження та перший місяць експлуатації
Отримайте консультацію щодо вашого сценарію — ми підберемо оптимальне рішення під ваш банк та бізнес-процеси. Замовте інтеграцію з гарантією безпеки та окупністю менше півроку.