Мастер настройки для REST-only приложений

Выберите инструмент для разработки с AI-агентом:

  • используйте Битрикс24 Вайбкод, чтобы создать приложение для Битрикс24 по описанию задачи без знания языков программирования. Агент напишет код и разместит приложение на сервере без ручной настройки хостинга
  • используйте MCP-сервер, чтобы разрабатывать интеграцию через REST API в своем проекте. Агент будет обращаться к официальной REST-документации

Мастер настройки REST-only приложений — это встроенная форма Битрикс24 для приложений без интерфейса. При разработке достаточно описать поля в формате JSON. Мастер настройки сам сформирует пошаговую форму, соберет данные и отправит их в указанный обработчик.

Используйте мастер настройки:

  • если у приложения нет своего интерфейса,
  • нужны простые настройки: ввод текста в строку, выбор варианта из списка,
  • нужен интерфейс в стиле Битрикс24, без отдельного UI,
  • данных от callback-обработчика события установки недостаточно.

Принцип работы мастера

Укажите параметр URL_SETTINGS в поле Настройки приложения при регистрации приложения в кабинете разработчика, в разделе REST-only. Если параметр заполнен, после установки приложения пользователь увидит слайдер с формой настройки.

Если параметр URL_SETTINGS не заполнен, форма настройки не откроется и Битрикс24 не отправит запрос для получения конфигурации формы.

Жизненный цикл формы

  1. Пользователь устанавливает приложение.
  2. Битрикс24 делает POST-запрос на URL_SETTINGS с параметром event: OnAppSettingsInstall.
  3. Приложение возвращает JSON-конфигурацию формы.
  4. Битрикс24 показывает форму в слайдере.
  5. При updateForm: true Битрикс24 повторно запрашивает URL_SETTINGS с параметром event: OnAppSettingsChange.
  6. Пользователь нажимает «Сохранить», и данные уходят на form.action.
  7. Приложение возвращает success или список ошибок. При success Битрикс24 закрывает слайдер и при необходимости выполняет переход на form.redirect.

жизненный цикл формы

Структура JSON-конфигурации

Конфигурация состоит из трех блоков:

  • заголовок,
  • шаги с полями,
  • параметры сохранения.

Заголовок

Заголовок задает название страницы настроек и версию конструктора.

{
  "title": "Название мастера",
  "version": "1"
}

Обязательные параметры отмечены *

Название
тип

Описание

title*
string

Заголовок в интерфейсе

version*
string

Версия конструктора, всегда "1"

Шаги

steps — массив шагов. Каждый шаг описывает отдельный экран формы.

{
  "id": "step1",
  "title": "API-ключ",
  "description": "Введите ключ доступа",
  "fields": [
    {
      "id": "api-key",
      "name": "api-key",
      "type": "input",
      "label": "API-ключ",
      "placeholder": "Введите API-ключ"
    }
  ]
}

Обязательные параметры отмечены *

Название
тип

Описание

id*
string

Уникальный идентификатор шага

title*
string

Заголовок шага

description
string

Пояснительный текст

help
boolean

Флаг отображения значка справки

fields*
array

Массив полей, подробное описание

Параметр fields

Обязательные параметры отмечены *

Название
тип

Описание

id*
string

Идентификатор поля

name*
string

Имя поля, ключ в данных

type*
string

Тип поля:

  • input — строка ввода данных,
  • dropdown-list — список

label
string

Подпись над полем

placeholder
string

Подсказка внутри поля

value
string

Значение по умолчанию

items
array

Список вариантов для dropdown-list

updateForm
boolean

Флаг обновления формы при изменении поля

Если параметр updateForm равен true, Битрикс24 повторно запросит URL_SETTINGS и передаст в запросе текущие значения полей.
Это позволяет обновлять форму в процессе ее заполнения пользователем. Например, можно добавить новое поле со списком регионов в зависимости от выбранного значения в поле страна.

Параметры сохранения

Блок form описывает, куда отправлять данные и какие кнопки показать.

"form": {
  "id": "config-form",
  "action": "https://example.ru/save-handler.php",
  "clientId": "local.123...",
  "redirect": "/crm/",
  "saveCaption": "Сохранить",
  "cancelCaption": "Отмена"
}

Обязательные параметры отмечены *

Название
тип

Описание

id*
string

Идентификатор формы

action*
string

URL обработчика сохранения

clientId*
string

Идентификатор приложения client_id

redirect
string

Путь после успешного сохранения

saveCaption
string

Подпись кнопки «Сохранить»

cancelCaption
string

Подпись кнопки «Отмена»

Пример конфигурации

{
  "title": "Storecove e-invoice connector",
  "version": "1",
  "steps": [
    {
      "id": "step1",
      "title": "API-ключ",
      "description": "Укажите ключ из личного кабинета Storecove",
      "fields": [
        {
          "id": "api-key",
          "name": "api-key",
          "type": "input",
          "label": "Storecove API-ключ",
          "placeholder": "Введите API-ключ"
        }
      ]
    },
    {
      "id": "step2",
      "title": "Страна",
      "fields": [
        {
          "id": "country",
          "name": "country",
          "type": "dropdown-list",
          "label": "Ваша страна",
          "items": [
            { "value": "RU", "name": "Россия" },
            { "value": "DE", "name": "Германия" },
            { "value": "US", "name": "США" }
          ],
          "updateForm": true
        }
      ]
    },
    {
      "id": "step3",
      "title": "Реквизиты компании",
      "fields": [
        {
          "id": "vat-id",
          "name": "vat-id",
          "type": "input",
          "label": "VAT ID",
          "placeholder": "Введите VAT ID"
        }
      ]
    }
  ],
  "form": {
    "id": "config-form",
    "action": "https://example.ru/save.php",
    "clientId": "local.6537665f598492.98090704",
    "redirect": "/",
    "saveCaption": "Подключить",
    "cancelCaption": "Позже"
  }
}

Обработчик URL_SETTINGS

Битрикс24 отправляет POST-запрос на URL_SETTINGS для получения конфигурации формы. Значения OnAppSettingsInstall, OnAppSettingsDisplay и OnAppSettingsChange не являются отдельными событиями. Это значения параметра event, по которым приложение определяет сценарий запроса.

В ответ на запрос приложение должно вернуть JSON-конфигурацию формы. Если ответ корректный, Битрикс24 покажет форму в интерфейсе.

Сценарии вызова

В примерах объект auth сокращен.

OnAppSettingsInstall передается после установки приложения.

{
  "event": "OnAppSettingsInstall",
  "auth": {}
}

OnAppSettingsDisplay передается, когда пользователь вручную открывает настройки приложения из карточки приложения.

{
  "event": "OnAppSettingsDisplay",
  "auth": {}
}

OnAppSettingsChange передается, когда пользователь изменяет значение поля с параметром updateForm: true. В запросе дополнительно передается объект data с текущими значениями полей.

{
  "event": "OnAppSettingsChange",
  "data": {
    "api-key": "cc1107f4-...",
    "country": "DE"
  },
  "auth": {}
}

Пример POST-запроса в PHP:

[
  'event' => 'OnAppSettingsInstall', // или OnAppSettingsChange / OnAppSettingsDisplay
  'data'  => [ /* текущие значения полей */ ],
  'auth'  => [
    'access_token' => '***',
    'expires' => 1768385511,
    'expires_in' => 3600,
    'scope' => 'crm,bizproc,appform,user_brief,placement,catalog',
    'domain' => 'some-domain.bitrix24.ru',
    'server_endpoint' => 'https://oauth.bitrix24.tech/rest/',
    'status' => 'F',
    'client_endpoint' => 'https://some-domain.bitrix24.ru/rest/',
    'member_id' => '***',
    'refresh_token' => '***',
    'user_id' => 431,
    'client_id' => '***',
    'application_token' => '***'
  ]
]

Название
тип

Описание

event
string

Сценарий запроса:

  • OnAppSettingsInstall — после установки приложения
  • OnAppSettingsDisplay — при открытии настроек приложения
  • OnAppSettingsChange — при изменении поля с updateForm: true

data
object

Текущие значения полей формы. Передается для OnAppSettingsChange

auth
object

Данные авторизации

Обработчик после сохранения

Когда пользователь нажимает «Сохранить», Битрикс24 отправляет данные формы на адрес из поля form.action.

$_POST = [
  'data' => [
    'api-key' => 'cc1107f4-...',
    'country' => 'DE',
    // остальные поля по имени (name)
  ],
  'auth' => [
    'access_token' => '***',
    'expires' => 1768385511,
    'expires_in' => 3600,
    'scope' => 'crm,bizproc,appform,user_brief,placement,catalog',
    'domain' => 'some-domain.bitrix24.ru',
    'server_endpoint' => 'https://oauth.bitrix24.tech/rest/',
    'status' => 'F',
    'client_endpoint' => 'https://some-domain.bitrix24.ru/rest/',
    'member_id' => '***',
    'refresh_token' => '***',
    'user_id' => 431,
    'client_id' => '***',
    'application_token' => '***'
  ],
  'saveform' => 'Y'
];

Пример чтения данных:

$data = $_POST['data'] ?? [];
$apiKey = $data['api-key'] ?? null;
$country = $data['country'] ?? null;

Успешный ответ

Успешный ответ сообщает Битрикс24, что данные сохранены. После этого слайдер закрывается. Если задан параметр form.redirect, будет выполнен переход по адресу в параметре.

header("HTTP/1.1 200 OK");
header("Content-Type: application/json");
echo json_encode(['status' => 'success']);

Ответ с ошибками

Если данные некорректны, верните HTTP 400 и список ошибок. Поле field должно совпадать со значением name в конфигурации.

header("HTTP/1.1 400 Bad Request");
header("Content-Type: application/json");
echo json_encode([
  'status' => 'error',
  'errors' => [
    ['field' => 'api-key', 'message' => 'Неверный формат API-ключа'],
    ['field' => 'country', 'message' => 'Страна обязательна']
  ]
]);

Битрикс24 показывает ошибки под соответствующими полями. Можно вернуть несколько ошибок для одного поля.

Пример обработчика для возврата статуса

<?php
$data = $_POST['data'] ?? [];

if (($data['api-key'] ?? null) === 'error')
{
    header("HTTP/1.1 400 Bad Request");
    header("Content-Type: application/json");

    echo json_encode([
        'status' => 'error',
        'errors' => [
            [
                'field' => 'api-key',
                'message' => 'You input invalid value',
            ],
            [
                'field' => 'api-key',
                'message' => 'You input invalid value 2',
            ],
        ],
    ]);
    exit();
}

file_put_contents('./settings.json', json_encode($_POST));

header("HTTP/1.1 200 OK");
header("Content-Type: application/json");
echo json_encode(['status' => 'success']);
exit();
?>

Устаревший способ показа формы

Метод appform.show — альтернативный способ открытия формы через push-событие showForm.

Особенности:

  • требуется активная сессия пользователя в Битрикс24, иначе событие теряется,
  • нужен access_token для вызова от имени пользователя.

Пример вызова appform.show через PHP SDK

use Bitrix24\SDK\Core\Credentials\ApplicationProfile;
use Bitrix24\SDK\Services\ServiceBuilderFactory;
use Psr\Log\NullLogger;
use Symfony\Component\EventDispatcher\EventDispatcher;
use Symfony\Component\HttpFoundation\Request;

require_once __DIR__ . '/vendor/autoload.php';

$appProfile = ApplicationProfile::initFromArray([
    'BITRIX24_PHP_SDK_APPLICATION_CLIENT_ID'     => 'local.6537665f598492.98090704',
    'BITRIX24_PHP_SDK_APPLICATION_CLIENT_SECRET' => 'client_secret',
    'BITRIX24_PHP_SDK_APPLICATION_SCOPE'         => 'crm,appform,placement',
]);

// Предполагается, что запрос пришел от Битрикс24 (placement)
$serviceBuilder = ServiceBuilderFactory::createServiceBuilderFromPlacementRequest(
    Request::createFromGlobals(),
    $appProfile,
    new EventDispatcher(),
    new NullLogger()
);

$config = [
    'title' => 'Push-инициированная форма',
    'version' => '1',
    'steps' => [
        [
            'id' => 'step1',
            'title' => 'API-ключ',
            'fields' => [
                ['id' => 'key', 'name' => 'key', 'type' => 'input']
            ]
        ]
    ],
    'form' => [
        'id' => 'config-form',
        'action' => 'https://example.ru/save.php',
        'clientId' => 'local.6537665f598492.98090704',
        'redirect' => '/'
    ]
];

try {
    $serviceBuilder->core->call('appform.show', [
        'config' => json_encode($config, JSON_THROW_ON_ERROR)
    ]);
} catch (\Throwable $e) {
    // обработка ошибки
}

Основной способ — автоматический запрос к URL_SETTINGS после установки приложения. Метод appform.show устарел.

Предыдущая
Мастер установки тиражного приложения
Следующая
Callback установки