Розробка програм для маркетплейсу Бітрікс24

Розроблення додатків для маркетплейса Бітрікс24

Додаток для маркетплейса Бітрікс24 — це не просто веб-сервіс з OAuth. Це продукт, який повинен працювати в iframe всередину корпоративного портала десятків тисяч компаній, на різних тарифних планах, з різними наборами модулів та правами користувачів. Більшість проблем виникає не на етапі розроблення, а після публікації — коли виявляється, що у половини користувачів немає потрібних прав, а REST-метод недоступний на тарифі «Базовий».

Типи додатків в екосистемі Бітрікс24

Перед розробленням важливо вибрати правильний тип додатку:

Вбудовані додатки (embed) — працюють в iframe, інтегруються в інтерфейс Бітрікс24 через placement API. Точки вбудовування: CRM_LEAD_DETAIL_TAB, CRM_DEAL_DETAIL_TAB, CRM_CONTACT_DETAIL_TAB, CALL_LIST, TASKS_TASK_VIEW_TAB, USER_PROFILE_MENU та ще кілька десятків. Це найпоширеніший тип.

Вджети — вбудовуються в конкретні області інтерфейсу через BX24.placement.call(). Корисні для невеликих дій: кнопка в карточці CRM, панель в чаті.

Додатки з власним інтерфейсом — відкриваються в окремій вкладці або модальному вікні, використовують REST API повністю в своій логіці. Більше свободи в UX, але користувач «виходить» з контексту Б24.

Боти та чат-додатки — працюють через imbot.* та imsetting.* методи, мають власний обробник подій.

Механізм авторизації: OAuth 2.0 + Server-to-Server

Авторизація в додатку Бітрікс24 працює через OAuth 2.0 з кодом авторизації. Флоу при першому запуску:

1. Користувач встановлює додаток → Бітрікс24 редиректить на redirect_uri з code
2. Додаток обмінює code на access_token та refresh_token через https://oauth.bitrix.info/oauth/token/
3. access_token живе 1 година, refresh_token — 180 днів
4. Додаток зберігає токени в своїй БД, прив'язуючи їх до member_id (унікальний ідентифікатор портала)

Для server-to-server взаємодії (без участі користувача) потрібно запитувати права від імені додатку, а не користувача. Це працює через OAuth з grant_type=client_credentials — доступно тільки для додатків типу «Додаток», не «Вджет».

Критичний момент: member_id потрібно використовувати як tenant-ідентифікатор, якщо ваш додаток мультиарендний. Всі дані в БД повинні партиціонуватися за member_id, інакше дані однієї компанії попадуть до іншої.

REST API: робота з даними Бітрікс24

Бітрікс24 REST API — не класичний REST. Методи викликаються через POST на https://{portal}.bitrix24.ru/rest/{method} з тілом у вигляді form-data або JSON. Пагінація працює через start (зміщення), ліміт фіксований — 50 записів. Щоб отримати всі записи, потрібна цикл з next із відповіді.

Найчастіше використовувані групи методів:

• crm.lead., crm.deal., crm.contact., crm.company. — робота з CRM
• tasks.task.*, task.item.list — завдання
• disk.folder., disk.file. — файли та диски
• im.message.add, imbot.message.add — повідомлення
• user.get, user.search — користувачі
• placement.bind — реєстрація точок вбудовування

Батчинг: одночасно можна відправити до 50 запитів через метод batch. Це критично для продуктивності — не робіть 50 окремих HTTP-запитів там, де можна зробити один batched.

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

Вебхуки та події

Додаток може підписуватися на події портала через event.bind. При наступленні події Бітрікс24 робить POST-запит на handler URL додатку. Важливі деталі:

• Handler повинен відповісти в течение 5 секунд, інакше Бітрікс24 вважає доставку невдалою
• Після 3 невдалих доставок поспіль — обробник автоматично відв'язується
• Для важкої обробки обов'язково використовуйте чергу: приймайте webhook, кладіть в чергу, відповідайте 200, обробляйте асинхронно

Доступні события: ONCRMLEADADD, ONCRMDEALUPDATE, ONTASKUPDATE, ONIMMESSAGECHAT, ONUSERADD та сотні інших. Повний список залежить від тарифу та встановлених модулів портала.

Розміщення (placements) — як додаток вбудовується в інтерфейс

Реєстрація placement вироблюється при встановленні додатку через виклик placement.bind. Розміщення прив'язується до конкретної точки інтерфейсу та передає в додаток контекст: ID сутності, тип, права користувача.

// У iframe додатку:
BX24.placement.getInterface(function(data) {
    // data містить контекст: entityType, entityId тощо
    console.log(data);
});

Для роботи з BX24 JS SDK потрібно підключити //api.bitrix24.com/api/v1/ та викликати BX24.init() перед будь-якими запитами до API. В iframe-середовищі cookies працюють з обмеженнями — потрібно використовувати localStorage або передавати токен через postMessage.

Робота з тарифними обмеженнями

Головна біль додатків для маркетплейса: REST-методи доступні не на всіх тарифах. Методи crm.* існують тільки починая з певних планів, telephony.* — тільки при підключенній телефонії, tasks.* можуть бути недоступни при відключеному модулі.

Правильний підхід — при встановленні перевіряти доступність потрібних методів через app.info та profile, явно повідомляти користувачу, якщо його тариф не підтримує функціональність додатку. Падати з необробленим 403 при виклику методу недопустимо.

Зберігання даних додатку

Бітрікс24 надає власне сховище для додатків через методи app.option.set / app.option.get — це просте key-value сховище на стороні портала, ліміт значення ~32KB. Для серйозних даних додаток повинен мати власну БД.

Для користувацьких налаштувань: user.option.set / user.option.get — зберігання per-user налаштувань на стороні Бітрікс24.

Часові рамки розроблення

Інфраструктура додатку

Додаток повинен бути доступний по HTTPS з валідним SSL-сертифікатом — Бітрікс24 не працює з HTTP або самопідписаними сертифікатами. Для production: окремий домен, можливість горизонтального масштабування (токени зберігаються в Redis/БД, не в пам'яті процесу), моніторинг webhook-обробників.

Логування: всі виклики REST API, всі вхідні webhook'и, всі OAuth-обміни. При розборі інцидентів у клієнта це єдиний спосіб зрозуміти, що пішло не так.