Создать коннектор biconnector.connector.add

Scope: biconnector

Кто может выполнять метод: пользователь с доступом к разделу «Рабочее место аналитика»

Метод biconnector.connector.add создает новый коннектор, который позволяет интегрировать внешние источники данных в Битрикс24.

Параметры метода

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

Название
тип

Описание

fields*
object

Объект, содержащий данные для создания нового коннектора. Формат объекта:

{
            "field_1": "value_1",
            "field_2": "value_2",
            ...,
            "field_n": "value_n"
        }
        
  • field_n — название поля
  • value_n — значение поля

Подробное описание ниже

Параметр fields

Название
тип

Описание

title*
string

Название коннектора

logo*
string

Логотип коннектора. Может передаваться ссылкой на изображение или строкой формата base64, например data:image/svg+xml;base64,PHN2ZyB3...

description
string

Описание коннектора

urlCheck*
string

Эндпоинт коннектора для проверки доступности, (подробное описание)

urlTableList*
string

Эндпоинт коннектора для получения списка таблиц, (подробное описание)

urlTableDescription*
string

Эндпоинт коннектора для получения описания конкретной таблицы, (подробное описание)

urlData*
string

Эндпоинт коннектора для получения данных по выбранной таблице, (подробное описание)

settings*
array

Список параметров подключения, (подробное описание)

sort
int

Параметр сортировки коннекторов. Значение по умолчанию 100

Примеры кода

Как использовать примеры в документации

curl -X POST \
             -H "Content-Type: application/json" \
             -H "Accept: application/json" \
             -d '{
                 "fields": {
                     "title": "SUPER REST CONNECTOR",
                     "logo": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjIiIGhlaWdodD0iMjIiIHZpZXdCb3g9IjAgMCAyMiAyMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KCTxjaXJjbGUgY3g9IjExIiBjeT0iMTEiIHI9IjEwIiBmaWxsPSIjRkYzQjNCIiAvPgoJPHRleHQgeD0iMTEiIHk9IjEzIiBmb250LWZhbWlseT0iQXJpYWwsIHNhbnMtc2VyaWYiIGZvbnQtc2l6ZT0iNiIgZmlsbD0iI0ZGRkZGRiIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZm9udC13ZWlnaHQ9ImJvbGQiPlJFU1Q8L3RleHQ+Cjwvc3ZnPg==",
                     "description": "Connector with token",
                     "urlCheck": "http://example.com/api/check",
                     "urlTableList": "http://example.com/api/table_list",
                     "urlTableDescription": "http://example.com/api/table_description",
                     "urlData": "http://example.com/api/data",
                     "settings": [
                        {
                            "name": "Логин",
                            "type": "STRING",
                            "code": "login"
                        },
                        {
                            "name": "Пароль",
                            "type": "STRING",
                            "code": "password"
                        }
                     ],
                     "sort": 100
                 }
                 }' \
             https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/biconnector.connector.add
        
curl -X POST \
             -H "Content-Type: application/json" \
             -H "Accept: application/json" \
             -d '{
                 "fields": {
                     "title": "SUPER REST CONNECTOR",
                     "logo": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjIiIGhlaWdodD0iMjIiIHZpZXdCb3g9IjAgMCAyMiAyMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KCTxjaXJjbGUgY3g9IjExIiBjeT0iMTEiIHI9IjEwIiBmaWxsPSIjRkYzQjNCIiAvPgoJPHRleHQgeD0iMTEiIHk9IjEzIiBmb250LWZhbWlseT0iQXJpYWwsIHNhbnMtc2VyaWYiIGZvbnQtc2l6ZT0iNiIgZmlsbD0iI0ZGRkZGRiIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZm9udC13ZWlnaHQ9ImJvbGQiPlJFU1Q8L3RleHQ+Cjwvc3ZnPg==",
                     "description": "Connector with token",
                     "urlCheck": "http://example.com/api/check",
                     "urlTableList": "http://example.com/api/table_list",
                     "urlTableDescription": "http://example.com/api/table_description",
                     "urlData": "http://example.com/api/data",
                     "settings": [
                        {
                            "name": "Логин",
                            "type": "STRING",
                            "code": "login"
                        },
                        {
                            "name": "Пароль",
                            "type": "STRING",
                            "code": "password"
                        }
                     ],
                     "sort": 100
                 },
                 "auth": "**put_access_token_here**"
                 }' \
             https://**put_your_bitrix24_address**/rest/biconnector.connector.add
        
try
        {
        	const response = await $b24.callMethod(
        		'biconnector.connector.add',
        		{
        			fields: {
        				"title": "SUPER REST CONNECTOR",
        				"logo": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjIiIGhlaWdodD0iMjIiIHZpZXdCb3g9IjAgMCAyMiAyMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KCTxjaXJjbGUgY3g9IjExIiBjeT0iMTEiIHI9IjEwIiBmaWxsPSIjRkYzQjNCIiAvPgoJPHRleHQgeD0iMTEiIHk9IjEzIiBmb250LWZhbWlseT0iQXJpYWwsIHNhbnMtc2VyaWYiIGZvbnQtc2l6ZT0iNiIgZmlsbD0iI0ZGRkZGRiIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZm9udC13ZWlnaHQ9ImJvbGQiPlJFU1Q8L3RleHQ+Cjwvc3ZnPg==",
        				"description": "Connector with token",
        				"urlCheck": "http://example.com/api/check",
        				"urlTableList": "http://example.com/api/table_list",
        				"urlTableDescription": "http://example.com/api/table_description",
        				"urlData": "http://example.com/api/data",
        				"settings": [
        					{
        						"name": "Логин",
        						"type": "STRING",
        						"code": "login"
        					},
        					{
        						"name": "Пароль",
        						"type": "STRING",
        						"code": "password"
        					}
        				],
        				"sort": 100
        			},
        		}
        	);
        	
        	const result = response.getData().result;
        	result.error()
        		? console.error(result.error())
        		: console.info(result.data());
        }
        catch( error )
        {
        	console.error(error);
        }
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'biconnector.connector.add',
                    [
                        'fields' => [
                            "title"               => "SUPER REST CONNECTOR",
                            "logo"                => "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjIiIGhlaWdodD0iMjIiIHZpZXdCb3g9IjAgMCAyMiAyMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KCTxjaXJjbGUgY3g9IjExIiBjeT0iMTEiIHI9IjEwIiBmaWxsPSIjRkYzQjNCIiAvPgoJPHRleHQgeD0iMTEiIHk9IjEzIiBmb250LWZhbWlseT0iQXJpYWwsIHNhbnMtc2VyaWYiIGZvbnQtc2l6ZT0iNiIgZmlsbD0iI0ZGRkZGRiIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZm9udC13ZWlnaHQ9ImJvbGQiPlJFU1Q8L3RleHQ+Cjwvc3ZnPg==",
                            "description"          => "Connector with token",
                            "urlCheck"             => "http://example.com/api/check",
                            "urlTableList"         => "http://example.com/api/table_list",
                            "urlTableDescription"  => "http://example.com/api/table_description",
                            "urlData"              => "http://example.com/api/data",
                            "settings"             => [
                                [
                                    "name" => "Логин",
                                    "type" => "STRING",
                                    "code" => "login"
                                ],
                                [
                                    "name" => "Пароль",
                                    "type" => "STRING",
                                    "code" => "password"
                                ]
                            ],
                            "sort"                => 100
                        ],
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            if ($result->error()) {
                echo 'Error: ' . $result->error();
            } else {
                echo 'Success: ' . print_r($result->data(), true);
            }
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error adding connector: ' . $e->getMessage();
        }
        
BX24.callMethod(
            'biconnector.connector.add',
            {
                fields: {
                    "title": "SUPER REST CONNECTOR",
                    "logo": "data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjIiIGhlaWdodD0iMjIiIHZpZXdCb3g9IjAgMCAyMiAyMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KCTxjaXJjbGUgY3g9IjExIiBjeT0iMTEiIHI9IjEwIiBmaWxsPSIjRkYzQjNCIiAvPgoJPHRleHQgeD0iMTEiIHk9IjEzIiBmb250LWZhbWlseT0iQXJpYWwsIHNhbnMtc2VyaWYiIGZvbnQtc2l6ZT0iNiIgZmlsbD0iI0ZGRkZGRiIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZm9udC13ZWlnaHQ9ImJvbGQiPlJFU1Q8L3RleHQ+Cjwvc3ZnPg==",
                    "description": "Connector with token",
                    "urlCheck": "http://example.com/api/check",
                    "urlTableList": "http://example.com/api/table_list",
                    "urlTableDescription": "http://example.com/api/table_description",
                    "urlData": "http://example.com/api/data",
                    "settings": [
                        {
                            "name": "Логин",
                            "type": "STRING",
                            "code": "login"
                        },
                        {
                            "name": "Пароль",
                            "type": "STRING",
                            "code": "password"
                        }
                    ],
                    "sort": 100
                },
            },
            (result) => {
                result.error()
                    ? console.error(result.error())
                    : console.info(result.data());
            },
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'biconnector.connector.add',
            [
                'fields' => [
                    'title' => 'SUPER REST CONNECTOR',
                    'logo' => 'data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMjIiIGhlaWdodD0iMjIiIHZpZXdCb3g9IjAgMCAyMiAyMiIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KCTxjaXJjbGUgY3g9IjExIiBjeT0iMTEiIHI9IjEwIiBmaWxsPSIjRkYzQjNCIiAvPgoJPHRleHQgeD0iMTEiIHk9IjEzIiBmb250LWZhbWlseT0iQXJpYWwsIHNhbnMtc2VyaWYiIGZvbnQtc2l6ZT0iNiIgZmlsbD0iI0ZGRkZGRiIgdGV4dC1hbmNob3I9Im1pZGRsZSIgZm9udC13ZWlnaHQ9ImJvbGQiPlJFU1Q8L3RleHQ+Cjwvc3ZnPg==',
                    'description' => 'Connector with token',
                    'urlCheck' => 'http://example.com/api/check',
                    'urlTableList' => 'http://example.com/api/table_list',
                    'urlTableDescription' => 'http://example.com/api/table_description',
                    'urlData' => 'http://example.com/api/data',
                    'settings' => [
                        [
                            'name' => 'Логин',
                            'type' => 'STRING',
                            'code' => 'login'
                        ],
                        [
                            'name' => 'Пароль',
                            'type' => 'STRING',
                            'code' => 'password'
                        ]
                    ],
                    'sort' => 100
                ]
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';
        

Обработка ответа

HTTP-статус: 200

{
            "result": {
              "id": 4
            },
            "time": {
                "start": 1725013197.635808,
                "finish": 1725013198.580873,
                "duration": 0.9450650215148926,
                "processing": 0.6822988986968994,
                "date_start": "2024-08-30T12:19:57+02:00",
                "date_finish": "2024-08-30T12:19:58+02:00",
                "operating": 0
            }
        }
        

Возвращаемые данные

Название
тип

Описание

result
integer

Корневой элемент ответа, содержит идентификатор созданного коннектора

time
time

Информация о времени выполнения запроса

Обработка ошибок

HTTP-статус: 200

{
            "error": "VALIDATION_FIELDS_NOT_PROVIDED",
            "error_description": "Fields not provided."
        }
        

Название
тип

Описание

error
string

Строковый код ошибки. Может состоять из цифр, латинских букв и знака подчеркивания

error_description
error_description

Текстовое описание ошибки. Описание не предназначено для показа конечному пользователю в необработанном виде

Возможные коды ошибок

Код

Описание

Значение

VALIDATION_FIELDS_NOT_PROVIDED

Fields not provided

Поля не переданы в запросе

VALIDATION_UNKNOWN_PARAMETERS

Unknown parameters: #LIST_OF_PARAMS#

Обнаружены неизвестные параметры: перечень

VALIDATION_REQUIRED_FIELD_MISSING

Field "#TITLE#" is required.

Обязательное поле #TITLE# не передано

VALIDATION_READ_ONLY_FIELD

Field "#TITLE#" is read only.

Поле #TITLE# доступно только для чтения и не может быть изменено

VALIDATION_IMMUTABLE_FIELD

Field "#TITLE#" is immutable.

Поле #TITLE# неизменяемое

VALIDATION_INVALID_FIELD_TYPE

Field "#TITLE#" must be of type #TYPE#.

Поле #TITLE# должно быть типа #TYPE#

VALIDATION_SETTINGS_MISSING_REQUIRED_FIELDS

Settings must include "type", "name" and "code" fields.

В настройках должны быть указаны поля type, name и code

VALIDATION_SETTINGS_NAME_TOO_LONG

Parameter "name" must be less than 512 characters.

Значение параметра name не должно превышать 512 символов

VALIDATION_SETTINGS_CODE_TOO_LONG

Parameter "code" must be less than 512 characters.

Значение параметра code не должно превышать 512 символов

VALIDATION_SETTINGS_INVALID_TYPE

Parameter "type" is not correct.

Недопустимое значение параметра type

Статусы и коды системных ошибок

HTTP-статус: 20x, 40x, 50x

Описанные ниже ошибки могут возникнуть при вызове любого метода

Статус

Код
Текст ошибки

Описание

500

INTERNAL_SERVER_ERROR
Internal server error

Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24

500

ERROR_UNEXPECTED_ANSWER
Server returned an unexpected response

Возникла внутренняя ошибка сервера, обратитесь к администратору сервера или в техническую поддержку Битрикс24

503

QUERY_LIMIT_EXCEEDED
Too many requests

Превышен лимит на интенсивность запросов

405

ERROR_BATCH_METHOD_NOT_ALLOWED
Method is not allowed for batch usage

Текущий метод не разрешен для вызова с помощью batch

400

ERROR_BATCH_LENGTH_EXCEEDED
Max batch length exceeded

Превышена максимальная длина параметров, переданных в метод batch

401

NO_AUTH_FOUND
Wrong authorization data

Неверный access-токен или код вебхука

400

INVALID_REQUEST
Https required

Для вызовов методов требуется использовать протокол HTTPS

503

OVERLOAD_LIMIT
REST API is blocked due to overload

REST API заблокирован из-за перегрузки. Это ручная индивидуальная блокировка, для снятия необходимо обращаться в техническую поддержку Битрикс24

403

ACCESS_DENIED
REST API is available only on commercial plans

REST API доступен только на коммерческих планах

403

INVALID_CREDENTIALS
Invalid request credentials

У пользователя, с чьим access-токеном или вебхуком был вызван метод, не хватает прав

404

ERROR_MANIFEST_IS_NOT_AVAILABLE
Manifest is not available

Манифест недоступен

403

insufficient_scope
The request requires higher privileges than provided by the webhook token

Запрос требует более высоких привилегий, чем предоставляет токен вебхука

401

expired_token
The access token provided has expired

Предоставленный access-токен доступа истек

403

user_access_error
The user does not have access to the application

Пользователь не имеет доступа к приложению. Это означает, что приложение установлено, но администратор портала разрешил доступ к этому приложению только конкретным пользователям

500

PORTAL_DELETED
Portal was deleted

Публичная часть сайта закрыта. Чтобы открыть публичную часть сайта на коробочной установке отключите опцию «Временное закрытие публичной части сайта». Путь к настройке: Рабочий стол > Настройки > Настройки продукта > Настройки модулей > Главный модуль > Временное закрытие публичной части сайта

Продолжите изучение