Розробка серверних застосунків Бітрікс24

Розробка серверних застосунків Бітрікс24

Наша команда — 5+ років досвіду в інтеграціях з Бітрікс24, виконала 50+ успішних проєктів. Уявіть: інтернет-магазин на Magento, 5000+ замовлень на день. Кожне потрібно перетворити на угоду Бітрікс24, призначити відповідального, надіслати сповіщення в Telegram. Без серверного застосунку — ручна робота або вебхуки з обмеженнями: прив'язані до сесії, не масштабуються. Серверний застосунок вирішує це повністю автоматично: працює у фоні, використовує OAuth 2.0, підписується на події. Ми реалізували 50+ таких інтеграцій для рітейлу, логістики та фінтеху. За понад 5 років виробили архітектуру, що витримує мільйони запитів на добу. Але є нюанси: токени можуть закінчуватися, події можуть приходити шквалом, а батч-запити потребують грамотної паузи. Розберемо ключові моменти, які перетворюють просту інтеграцію на відмовостійкий production.

Чим серверний застосунок відрізняється від вебхука?

Вебхуки в Бітрікс24 — вхідні URL, куди Бітрікс24 шле події. Вони зручні для простих сценаріїв, але мають обмеження: прив'язані до конкретного користувача, не підтримують OAuth, не можуть бути тиражними. Серверний застосунок (тип server) — повноцінний OAuth-клієнт:

• Авторизується від імені користувача, що встановив, зі збереженням токенів.
• Працює у фоні (демон, черга завдань, cron).
• Підтримує багатопортальність (один застосунок — багато клієнтів).
• Має власний обробник подій через event.bind.

Серверний застосунок у 10 разів ефективніший за вебхуки в обробці великих обсягів даних. Для складних сценаріїв — єдиний робочий варіант.

Як працює OAuth у серверному застосунку?

Бітрікс24 використовує Authorization Code Flow. Застосунок перенаправляє користувача на сторінку авторизації з client_id, response_type=code, state. Після підтвердження код обмінюється на токени через POST до oauth.bitrix.info. Токени містять access_token, refresh_token, expires_at та member_id. Згідно з документацією Бітрікс24, refresh_token живе 1 місяць, після чого потрібна повторна авторизація. Важливо зберігати токени в захищеному сховищі (база даних, AWS Secrets Manager, Vault). member_id — унікальний ідентифікатор порталу, служить ключем у multi-tenant архітектурі.

Member_id: ідентифікація порталу

member_id — хеш, що однозначно ідентифікує портал. Повертається разом з токенами і не змінюється. У багатопортальному застосунку служить ключем для зберігання токенів та конфігурації кожного клієнта.

Як забезпечити надійне зберігання токенів?

У production використовуємо таблицю:

CREATE TABLE bitrix_tokens ( id SERIAL PRIMARY KEY, member_id VARCHAR(64) UNIQUE NOT NULL, domain VARCHAR(255) NOT NULL, access_token TEXT NOT NULL, refresh_token TEXT NOT NULL, expires_at TIMESTAMPTZ NOT NULL, scope TEXT, created_at TIMESTAMPTZ DEFAULT NOW(), updated_at TIMESTAMPTZ DEFAULT NOW() ); 

Refresh при закінченні:

def get_valid_token(member_id: str) -> str: token = db.get_token(member_id) if token.expires_at < datetime.now() + timedelta(minutes=5): response = requests.post( 'https://oauth.bitrix.info/oauth/token/', data={ 'grant_type': 'refresh_token', 'client_id': CLIENT_ID, 'client_secret': CLIENT_SECRET, 'refresh_token': token.refresh_token, } ) new_token = response.json() db.update_token(member_id, new_token) return new_token['access_token'] return token.access_token 

Додавайте 5-хвилинний буфер — інакше токен може закінчитися між перевіркою та запитом. Альтернативно використовуйте Vault.

vault kv put secret/bitrix/member_abc123 \ access_token=xxx \ refresh_token=yyy \ expires_at=2025-01-01T00:00:00Z 

Підписка на події порталу

Підписка через REST: POST /rest/event.bind з параметрами event, handler, auth_type. При спрацьовуванні Бітрікс24 шле POST на handler. Підтримуються всі події CRM: додавання, оновлення, видалення угод, лідів, контактів.

Handler має відповідати 200 OK за 3 секунди. Якщо обробка довша — негайно повертайте 200 і відправляйте завдання в чергу (RabbitMQ, Redis Streams, SQS):

@app.route('/webhooks/bitrix/deal-add', methods=['POST']) def handle_deal_add(): data = request.json task_queue.enqueue(process_new_deal, data) return jsonify({'status': 'accepted'}), 200 

Робота з батч-запитами

REST API ліміт: 2 запити на секунду (50 для платних). При масових операціях використовуйте батч:

POST /rest/batch { "halt": 0, "cmd": { "get_deal": "crm.deal.get?id=42", "get_contact": "crm.contact.get?id=17", "get_company": "crm.company.get?id=5" } } 

В одному батчі до 50 команд. halt=1 зупиняє при помилці.

Як налаштувати OAuth за 4 кроки

1. Зареєструйте застосунок у Бітрікс24 (тип server).
2. Вкажіть redirect_uri — ендпоінт, що приймає код авторизації.
3. Реалізуйте обмін коду на токени через POST до oauth.bitrix.info.
4. Збережіть токени разом з member_id у захищеному сховищі.

Кожен крок потребує тестування: збої на етапі авторизації — часта помилка.

Багатопортальна архітектура

Якщо застосунок обслуговує декілька порталів, структура має ізолювати дані:

• /api/v1/{member_id}/sync — синхронізація.
• /webhooks/{member_id}/event — прийом подій.

Використання member_id в URL зручне, але перевіряйте підпис запиту — уникайте IDOR.

Які етапи включає розробка серверного застосунку?

• Аналіз вимог та проєктування.
• Реалізація на PHP/Python з REST API.
• Інтеграція з зовнішніми системами (1С, CRM, платіжні шлюзи).
• Деплой (Docker, CI/CD).
• Документація та навчання.
• Підтримка місяць після запуску.

Що входить у роботу?

• Аналіз вимог та технічне завдання
• Розробка та тестування
• Документація (API, інструкції)
• Надання доступів та інтеграція
• Навчання вашої команди
• Підтримка 1 місяць після запуску

Терміни розробки

Вартість розробки серверного застосунку починається від $500 для простих інтеграцій та до $5000 для складних багатопортальних рішень.

Основна складність — не REST API, а надійність: ідемпотентність, retry-логіка, моніторинг токенів. На це йде 40–60% часу. Ми гарантуємо стабільне рішення. Замовте розробку під ключ: ми реалізуємо проєкт за 5–30 днів залежно від складності. Напишіть нам для консультації, щоб переконатися, що ми підходимо під ваш проєкт.

Чому варто обрати серверний застосунок? Тому що це єдиний спосіб зробити інтеграцію, яка не потребує ручного втручання та витримує навантаження. Довірте автоматизацію експертам.