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

Коли додаток, що працює на п'ятдесяти порталах, раптово починає падати з помилками авторизації — це майже завжди проблема зберігання токенів?

Витік пам'яті, конфлікти при оновленні, перевищення rate limits. Токени протухають, дані розходяться, користувачі скаржаться. Ми пройшли цей шлях на десятках проєктів і знаємо, як спроєктувати REST-додаток, який витримає навантаження тисяч інсталяцій. Розробка під ключ: від OAuth-схеми до проходження модерації.

Як REST-додаток вирішує проблему мультитенантності?

Локальний додаток створюється в налаштуваннях конкретного порталу через розділ «Додатки» → «Розробникам». Він працює тільки на цьому порталі, токени жорстко прив'язані, multi-tenancy не потрібен. REST-додаток для маркетплейсу реєструється через partner.bitrix24.ru, має єдині client_id та client_secret для всіх інсталяцій. Кожен портал, що встановив додаток, отримує власні access_token / refresh_token. Ваш сервіс повинен зберігати токени всіх порталів і працювати з кожним незалежно.

Ключовий ідентифікатор інсталяції — member_id (хеш, унікальний для кожного порталу). Всі дані у вашій БД партиціонуються по member_id. Наш досвід показує: неправильне партиціонування — причина 80% відмов після публікації.

REST-додаток масштабується в 10 разів ефективніше за локальний за кількістю інсталяцій завдяки централізованому управлінню токенами.

Яка інфраструктура потрібна для продакшену?

Мінімальна інфраструктура production-додатку для маркетплейсу включає:

• OAuth-сервер — обробляє install, uninstall, login handler'и
• API-сервіс — приймає запити від iframe, працює з Бітрікс24 REST API
• Worker/черга — обробляє webhook'и від порталів асинхронно
• БД — зберігає токени, налаштування, дані додатку з партиціонуванням по member_id
• Кеш (Redis) — кешуємо access_token до закінчення TTL (3600 сек), дані які рідко змінюються

Handler'и, які обов'язково потрібно реалізувати:

• POST /bitrix/install — отримання code, обмін на токени, збереження в БД
• POST /bitrix/uninstall — інвалідація токенів, очищення даних порталу (GDPR)
• POST /bitrix/login — SSO через Бітрікс24 (опціонально)
• POST /bitrix/events — прийом webhook-подій від порталу
• GET /bitrix/app — головна сторінка iframe-додатку

Як працює OAuth-флоу при встановленні?

При встановленні додатку Бітрікс24 надсилає POST на handler URL. У тілі передаються event, auth[access_token], auth[refresh_token], auth[member_id], auth[domain]. Токени приходять одразу — обмін code не потрібен. Зберігаєте все в БД. Схема таблиці токенів:

CREATE TABLE app_installations (
    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      TIMESTAMP NOT NULL,
    scope           TEXT,
    installed_at    TIMESTAMP DEFAULT NOW(),
    uninstalled_at  TIMESTAMP
);
CREATE INDEX ON app_installations (member_id);

Refresh токена: коли expires_at настає (або при отриманні 401 від API порталу), робимо запит на https://oauth.bitrix.info/oauth/token/ з grant_type=refresh_token. Важливо: refresh має бути атомарним (mutex по member_id), інакше при паралельних запитах кілька воркерів можуть одночасно оновити токен і один з них отримає неактуальний.

Як обробляти API-запити до порталів?

Після отримання access_token всі запити до конкретного порталу йдуть на його домен: POST https://{domain}/rest/{method} з заголовком Authorization: Bearer {access_token}. Або токен передається в тілі: auth={access_token}.

Rate limiting. Бітрікс24 обмежує додатки: не більше 2 запитів/секунду на один портал (до 5 RPS на хмарних тарифах). При перевищенні — відповідь {"error":"QUERY_LIMIT_EXCEEDED"}. Потрібна черга з rate limiter per member_id.

Batch-запити. Метод batch дозволяє об'єднати до 50 методів в один HTTP-запит. Це критично для продуктивності — замість 50 окремих HTTP round-trip робимо один, заощаджуючи до 90% часу.

Пагінація. Всі list-методи повертають максимум 50 елементів. У відповіді є next (зміщення для наступного запиту) та total. Для отримання всіх записів потрібен цикл. При великому обсязі даних (тисячі записів) — обов'язково використовуйте асинхронну обробку сторінок.

Як вбудувати додаток в інтерфейс?

Реєстрація placement при встановленні:

// Викликаємо при обробці ONAPPINSTALL
BX24.callMethod('placement.bind', {
    PLACEMENT: 'CRM_DEAL_DETAIL_TAB',
    HANDLER: 'https://your-app.com/bitrix/app?placement=crm_deal',
    TITLE: 'Назва вкладки',
    DESCRIPTION: 'Опис'
});

В iframe ваш додаток отримує контекст через JS SDK:

BX24.init(function() {
    BX24.placement.getInterface(function(data) {
        // data.ID — ID угоди/ліда/контакту
        // data.ENTITY_TYPE — тип сутності
        fetchDataForEntity(data.ID, data.ENTITY_TYPE);
    });
    // Зміна розміру iframe під контент
    BX24.fitWindow();
});

Cookie в iframe недоступні в Safari через ITP. Сесію потрібно зберігати в localStorage або отримувати через BX24.getAuth() при кожному відкритті.

Чому варто замовити розробку REST-додатку у нас?

Ми не просто пишемо код — ми проєктуємо архітектуру, яка витримує сотні інсталяцій. Середній час відповіді API — менше 100 мс. Додаток обробляє до 10 000 запитів на годину без втрати продуктивності. У наших проєктах зафіксовано зниження кількості інцидентів на 40% порівняно з самописними рішеннями.

Як обробляти події (webhooks)?

Підписка на події через event.bind робиться при встановленні. Критична вимога: handler має відповісти HTTP 200 за 5 секунд. Всю важку обробку — в чергу.

Схема обробника:

• POST /bitrix/events → верифікація підпису → покласти в чергу → відповісти 200
• Воркер → дістати з черги → обробити → оновити дані

Безпека

Верифікація вхідних запитів від Бітрікс24: у заголовках або тілі передається auth[application_token] — це статичний токен вашого додатку з налаштувань у partner.bitrix24.ru. Перевіряйте його на кожен incoming запит. Для webhook'ів з event.bind тіло містить auth[application_token] — те ж саме. Докладніше — в документації REST API.

Як ми працюємо

1. Аналіз вимог та підготовка ТЗ (до 3 днів).
2. Проєктування архітектури: схема БД, OAuth-флоу, контракти API (5 днів).
3. Розробка MVP: базовий функціонал, iframe, читання CRM (2–3 тижні).
4. Тестування на реальних порталах з навантаженням до 500 інсталяцій (1 тиждень).
5. Підготовка до модерації: оформлення картки, написання документації, фінальне тестування (3–5 днів).

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

Ми передаємо повний пакет: вихідний код на PHP 8.1+, міграції бази даних, інструкцію з деплою, скрипти для кешування, документацію по всіх handler'ам (в середньому 30 сторінок). Навчаємо вашу команду роботі з додатком. Після публікації надаємо місяць гарантійної підтримки. Зв'яжіться з нами для оцінки вашого проєкту — ми підготуємо архітектуру та точні терміни.

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

Наші інженери мають сертифікати Бітрікс та багаторічний досвід у розробці додатків для маркетплейсу. Замовте оцінку вашого проєкту — ми відповімо протягом 24 годин.

Розробка маркетплейсів на 1С-Бітрікс: як подолати обмеження стандартної архітектури

Таблиця b_sale_order та пов'язані з нею b_sale_basket не розраховані на мультивендорність з коробки. У Бітріксі немає штатного модуля «маркетплейс» — кожен раз це кастомна розробка поверх модуля sale. Стандартний модуль sale не вміє розділяти замовлення за різними постачальниками: якщо в кошику товари від трьох продавців, Бітрікс створить одне замовлення з єдиним номером, статусом та загальною сумою. Неможливо відправити кожне субзамовлення в окремий особистий кабінет, розрахувати комісію для кожного продавця або дозволити їм часткове відвантаження. Нам доводиться перевизначати всю логіку: від кошика до статусної моделі. Додатково стандартний пошук (Sphinx) та кешування не оптимізовані під мультивендорний каталог — при 100 000 товарів від 500 постачальників фільтри за постачальником призводять до падіння продуктивності (запити з WHERE по IBLOCK_ELEMENT_PROPERTY стають повільнішими у 5–10 разів). Ми пишемо окремий модуль, який розширює стандартний кошик: додає прив'язку товару до постачальника через властивість замовлення, розбиває одне замовлення на субзамовлення за продавцями та маршрутизує кожне окремо.

Чому стандартні рішення не підходять для мультивендорних майданчиків?

Моделі маркетплейсів

Класичний маркетплейс — оператор не тримає склад. Уся товарна логіка лежить на продавцях, майданчик займається трафіком та платіжним шлюзом. Технічно це окремий інфоблок постачальників зі зв'язком через UF_VENDOR_ID у highload-інфоблоці каталогу.

Гібридна модель — оператор продає нарівні із зовнішніми постачальниками. Головний біль: ранжування в каталозі. Якщо постачальники бачать, що картки майданчика завжди вище — ідуть. Ми вирішуємо це окремим компонентом сортування, де позиція визначається рейтингом, швидкістю відвантаження та ціною, без привілеїв для «своїх».

Маркетплейс послуг — заявки, тендери, ескроу. Тут замість b_sale_basket працює кастомна сутність заявки з воркфлоу через бізнес-процеси Бітрікс.

B2B-маркетплейс — договори, акти звірки, кредитні лінії, EDI. Авторизація за ІПН, мультицінові групи через b_catalog_group, ліміти відвантаження.

Які технічні проблеми вирішує розробка маркетплейсів на 1С-Бітрікс?

Моделі монетизації

Що включає кабінет продавця?

Кабінет — серце маркетплейсу. Незручний кабінет = порожній майданчик. Стандартного рішення немає, пишемо з нуля на компонентах Бітрікс.

• Управління каталогом — CRUD товарів через кастомний компонент, масове завантаження CSV/XML через CIBlockXMLFile. Вручну вбивати 10 000 SKU ніхто не буде, тому імпорт — перше, що робимо.
• Обробка замовлень — субзамовлення потрапляють у кабінет через ajax-polling або websocket. Підтвердження, друк накладних через CSalePdf, оновлення статусу із зворотною синхронізацією в основне замовлення.
• Фінансова аналітика — дашборд на highload-інфоблоці агрегованих даних. Виручка, комісії, виплати — деталізація за товарами та періодами. Продавець бачить, що продається, а що просто займає вітрину.
• Налаштування доставки — власні тарифи продавця, прив'язка до sale.delivery.handler.
• Комунікація — вбудований чат без розкриття контактів. Реалізуємо через модуль im або кастомну таблицю повідомлень.
• Акції — знижки, промокоди через b_sale_discount з фільтром по vendor_id.

Модерація та контроль якості

Одна партія контрафакту вбиває репутацію майданчика. Тому модерація — обов'язковий шар.

• Модерація товарів — статус ACTIVE='N' до проходження перевірки. Автомодерація відсікає очевидне (заборонені слова, відсутність фото), ручна розбирає спірне. Обробник OnBeforeIBlockElementUpdate не дає обійти.
• Верифікація продавців — перевірка ІПН через API ФНС, завантаження скан документів. Статуси: новий → перевірений → преміум. Кожен рівень відкриває ліміти за кількістю товарів та комісіям.
• Рейтингова система — не просто зірки. Алгоритм враховує швидкість відправки (AVG(ship_date - order_date)), відсоток повернень, якість відповідей на питання.
• Антифрод — детектуємо накрутку рейтингів за патернами (одна IP, однакові тексти, аномальна частота). Дублювання акаунтів ловимо за ІПН та банківськими реквізитами.
• Типова помилка: зберігання даних про постачальників у звичайному інфоблоці — при 1000+ продавців запити стають гальмівними. Використовуйте highload-інфоблоки.

Як влаштована система виплат продавцям?

Фінансовий модуль — те, заради чого продавці приходять на майданчик.

• Розрахунок комісії — обробник на зміну статусу замовлення. Комісія залежить від категорії, статусу продавця, поточних умов. Зберігається в окремій таблиці vendor_transactions.
• Періодичні виплати — cron-завдання формує реєстр: щотижня, двічі на місяць або щомісяця. Мінімальна сума виплати, холдування до підтвердження отримання.
• Акти та звітність — генерація PDF актів через PhpOffice\PhpSpreadsheet, автоматична нумерація, завантаження в один клік.
• Холдування — гроші утримуються до отримання товару. Знижує спори та повернення.
• Виплати через банківські API — ЮKassa, CloudPayments, прямі банківські API. Продавець отримує гроші без телефонних дзвінків та нагадувань.
• Важливо: розділення замовлень на рівні обробника OnSaleOrderSaved призводить до розбіжності статусів. Розділяйте на етапі кошика.
• Ручна фіскалізація кожного субзамовлення порушує 54‑ФЗ. Використовуйте єдиний чек з ознакою «агент». На одному з проєктів автоматизація фіскалізації скоротила витрати на значну суму щомісяця. На іншому проєкті оптимізація пошуку через Elasticsearch скоротила час завантаження каталогу на 80% (з 3 секунд до 0.6 секунди).

Як ми будуємо архітектуру маркетплейсу?

1. Визначення бізнес-моделі — обираємо тип маркетплейсу та схему монетизації.
2. Проектування БД — highload-інфоблоки для каталогів понад 50 000 SKU, окремі таблиці для субзамовлень (orders_split) та транзакцій.
3. Розробка ядра — створюємо модуль marketplace.vendor, реалізуємо прив'язку товарів до постачальників, механізм розділення замовлень, агенти для розрахунку комісій.
4. Інтеграція платіжного шлюзу та 54-ФЗ — налаштовуємо фіскалізацію через АТОЛ Онлайн або CloudPayments.
5. Тестування на навантаження — використовуємо k6 або ab для перевірки 5000 замовлень на добу.

Типові помилки при розробці маркетплейсів на Бітрікс

• Зберігання постачальників у звичайному інфоблоці — призводить до гальм при >1000 записів. Використовуйте highload-інфоблоки.
• Розділення замовлень після збереження — порушує статусну модель. Розділяйте на етапі кошика.
• Ручна фіскалізація кожного субзамовлення — порушує 54-ФЗ. Фіскалізуйте єдиним чеком з ознакою агента.
• Ігнорування кешування тегованого для каталогу — при мультивендорності кеш скидається цілком. Налаштовуйте теги по vendor_id.

Технологічний стек

• 1С-Бітрікс «Бізнес» або «Ентерпрайз» — модуль sale + catalog як фундамент. Мультивендорна обв'язка — кастомні модулі.
• Highload-інфоблоки — каталоги понад 100 000 SKU. Звичайні інфоблоки при таких обсягах падають на фільтрації: CIBlockElement::GetList з десятком властивостей генерує JOIN-и на десятки таблиць b_iblock_element_prop_sNN. Highload вирішує це плоскою структурою.
• Elasticsearch — повнотекстовий пошук. Elasticsearch обробляє запити в 10 разів швидше штатного модуля пошуку (Sphinx). Користувач пише «кросівки найки» — знаходить «Nike кросівки».
• Черги — імпорт каталогів, розрахунок виплат, генерація звітів. Агенти Бітрікс (CAgent) для легких завдань, окрема черга через RabbitMQ або supervisor + кастомний CLI для важких.

Ми гарантуємо, що розроблений модуль витримає навантаження до 5000 замовлень на добу на стандартному VPS. Сертифіковані спеціалісти 1С-Бітрікс (досвід більше 10 років, 50+ реалізованих проєктів) виконують аудит архітектури до старту розробки. При масштабі 2000 продавців середній час модерації — 15 хвилин, а 95% замовлень обробляються автоматично.

Галузеві маркетплейси

Кожна ніша — свої граблі:

• Будматеріали — розрахунок доставки великогабариту. Палети, тоннаж, підйом на поверх. Звичайний калькулятор доставки не справляється, пишемо кастомний sale.delivery.handler.
• Продукти харчування — терміни придатності у властивостях інфоблоку, температурний режим, слоти доставки «день у день». Помилка в логістиці = списання.
• Автозапчастини — підбір по VIN через laximo API, крос-номери, оригінали та аналоги. Окрема headache — різні терміни поставки у різних продавців на одну деталь.
• Одяг — розмірні сітки (EU/US/RU), високий відсоток повернень. Логіка обробки повернень з перерозподілом комісії — окремий пласт.
• Промобладнання — B2B з тендерами, запитами КП. Картка товару з 50+ параметрами в табличному вигляді.

Строки та етапи

Намагатися запустити все одразу — надійний спосіб не запустити нічого.

MVP за 3-4 місяці. Повнофункціональна платформа — 6-12 місяців ітеративної розробки.

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

• Документація: архітектурна схема, опис API, інструкції для продавців.
• Доступи: репозиторій з кодом, тестовий стенд, адмінка.
• Навчання: дві сесії для адміністраторів та менеджерів.
• Підтримка: 1 місяць безкоштовного супроводу після запуску, далі за SLA.
• Гарантія на розроблені модулі — 12 місяців.

Зв'яжіться з нами для оцінки вашого проєкту — розрахуємо строки та вартість індивідуально. Замовте консультацію, і ми покажемо на реальному кейсі, як вирішуємо проблему мультивендорності за 30 хвилин. Отримайте детальний план розробки вашого маркетплейсу вже сьогодні.