Добавить обработчик службы доставки sale.delivery.handler.add

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

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

Scope: sale

Кто может выполнять метод: администратор CRM

Метод добавляет обработчик службы доставки.

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

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

Название
тип

Описание

NAME*
string

Название обработчика службы доставки

CODE*
string

Символьный код обработчика службы доставки

SORT
integer

Сортировка

DESCRIPTION
integer

Описание обработчика службы доставки

SETTINGS*
object

Объект, содержащий информацию о настройках обработчика службы доставки (подробное описание приведено ниже)

PROFILES*
object[]

Массив, содержащий список объектов профилей доставки (подробное описание приведено ниже).

Подразумевается, что у обработчика службы доставки должен быть как минимум 1 профиль

Параметр SETTINGS

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

Название
тип

Описание

CALCULATE_URL*
string

URL для расчёта стоимости доставки.

На данный URL приходят данные о посылке (что доставить, куда и как), стоимость доставки которой нужно рассчитать в ответе.

Формат запроса и ответа детально описан в документации по веб-хуку Расчет стоимости доставки

CREATE_DELIVERY_REQUEST_URL
string

URL для создания заказа на доставку.

На данный URL приходят данные о посылке (что доставить, куда и как), заказ на которую нужно оформить в службе доставки.

Формат запроса и ответа детально описан в документации по веб-хуку Создание заказа на доставку

CANCEL_DELIVERY_REQUEST_URL
string

URL для отмены заказа на доставку

На данный URL приходят данные о посылке (что доставить, куда и как), заказ на которую нужно отменить в службе доставки.

Формат запроса и ответа детально описан в документации по веб-хуку Отмена заказа на доставку

HAS_CALLBACK_TRACKING_SUPPORT
string

Индикатор того, будет ли служба доставки присылать оповещения о статусе заказа на доставку (см. метод sale.delivery.request.sendmessage).

В случае, если поддержка событий указана, то в интерфейсе менеджера при заказе доставки будет создано дело на доставку, в которое могут транслироваться изменения, связанные с текущим статусом доставки.

Возможные значения:

  • Y — есть поддержка
  • N — нет поддержки

CONFIG
object[]

Массив объектов с доступными настройками для службы доставки, создаваемой с использованием данного обработчика (подробное описание приведено ниже)

Параметр CONFIG

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

Название
тип

Описание

TYPE*
string

Тип поля настройки
Возможные значения:

  • STRING — строка
  • Y/N — чекбокс (да / нет)
  • NUMBER — число
  • ENUM — список
  • DATE — дата
  • LOCATION — местоположение

CODE*
string

Символьный код настройки

NAME*
string

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

OPTIONS
object

Список опций для выбора. Объект в формате ключ=значение. Где ключ — код опции, а значение — опция.

Пример:

{
           "Option1Code": "Option1Value",
           "Option2Code": "Option2Value",
           "Option3Code": "Option3Value"
        }

Параметр актуален только для настройки типа ENUM

Параметр PROFILES

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

Название
тип

Описание

NAME*
string

Название профиля обработчика службы доставки

CODE*
string

Символьный код профиля обработчика службы доставки

DESCRIPTION
string

Описание профиля обработчика службы доставки

Примеры кода

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

curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"CODE":"uber","NAME":"Uber","DESCRIPTION":"Uber Description","SORT":250,"SETTINGS":{"CALCULATE_URL":"http://gateway.bx/calculate.php","CREATE_DELIVERY_REQUEST_URL":"http://gateway.bx/create_delivery_request.php","CANCEL_DELIVERY_REQUEST_URL":"http://gateway.bx/cancel_delivery_request.php","HAS_CALLBACK_TRACKING_SUPPORT":"Y","CONFIG":[{"TYPE":"STRING","CODE":"SETTING_1","NAME":"String Example"},{"TYPE":"Y/N","CODE":"SETTING_2","NAME":"Checkbox Example"},{"TYPE":"NUMBER","CODE":"SETTING_3","NAME":"Number Example"},{"TYPE":"ENUM","CODE":"SETTING_4","NAME":"Enum Example","OPTIONS":{"Option1Code":"Option1Value","Option2Code":"Option2Value","Option3Code":"Option3Value","Option4Code":"Option4Value","Option5Code":"Option5Value"}},{"TYPE":"DATE","CODE":"SETTING_5","NAME":"Date Example"},{"TYPE":"LOCATION","CODE":"SETTING_6","NAME":"Location Example"}]},"PROFILES":[{"NAME":"Taxi","CODE":"TAXI","DESCRIPTION":"Taxi Delivery"},{"NAME":"Cargo","CODE":"CARGO","DESCRIPTION":"Cargo Delivery"}]}' \
        https://**put_your_bitrix24_address**/rest/**put_your_user_id_here**/**put_your_webhook_here**/sale.delivery.handler.add
        
curl -X POST \
        -H "Content-Type: application/json" \
        -H "Accept: application/json" \
        -d '{"CODE":"uber","NAME":"Uber","DESCRIPTION":"Uber Description","SORT":250,"SETTINGS":{"CALCULATE_URL":"http://gateway.bx/calculate.php","CREATE_DELIVERY_REQUEST_URL":"http://gateway.bx/create_delivery_request.php","CANCEL_DELIVERY_REQUEST_URL":"http://gateway.bx/cancel_delivery_request.php","HAS_CALLBACK_TRACKING_SUPPORT":"Y","CONFIG":[{"TYPE":"STRING","CODE":"SETTING_1","NAME":"String Example"},{"TYPE":"Y/N","CODE":"SETTING_2","NAME":"Checkbox Example"},{"TYPE":"NUMBER","CODE":"SETTING_3","NAME":"Number Example"},{"TYPE":"ENUM","CODE":"SETTING_4","NAME":"Enum Example","OPTIONS":{"Option1Code":"Option1Value","Option2Code":"Option2Value","Option3Code":"Option3Value","Option4Code":"Option4Value","Option5Code":"Option5Value"}},{"TYPE":"DATE","CODE":"SETTING_5","NAME":"Date Example"},{"TYPE":"LOCATION","CODE":"SETTING_6","NAME":"Location Example"}]},"PROFILES":[{"NAME":"Taxi","CODE":"TAXI","DESCRIPTION":"Taxi Delivery"},{"NAME":"Cargo","CODE":"CARGO","DESCRIPTION":"Cargo Delivery"}],"auth":"**put_access_token_here**"}' \
        https://**put_your_bitrix24_address**/rest/sale.delivery.handler.add
        
// This snippet is an ES module: top-level await requires type="module" or a bundler.
        // $b24 is an already-initialized SDK instance (see the SDK "Get started" guide).
        import { Text } from '@bitrix24/b24jssdk'
        import type { B24Frame } from '@bitrix24/b24jssdk'
        
        declare const $b24: B24Frame
        
        try {
          const response = await $b24.actions.v2.call.make<number>({
            method: 'sale.delivery.handler.add',
            params: {
              CODE: 'uber',
              NAME: 'Uber',
              DESCRIPTION: 'Uber Description',
              SORT: 250,
              SETTINGS: {
                CALCULATE_URL: 'http://gateway.bx/calculate.php',
                CREATE_DELIVERY_REQUEST_URL: 'http://gateway.bx/create_delivery_request.php',
                CANCEL_DELIVERY_REQUEST_URL: 'http://gateway.bx/cancel_delivery_request.php',
                HAS_CALLBACK_TRACKING_SUPPORT: 'Y',
                CONFIG: [
                  { TYPE: 'STRING', CODE: 'SETTING_1', NAME: 'String Example' },
                  { TYPE: 'Y/N', CODE: 'SETTING_2', NAME: 'Checkbox Example' },
                  { TYPE: 'NUMBER', CODE: 'SETTING_3', NAME: 'Number Example' },
                  {
                    TYPE: 'ENUM',
                    CODE: 'SETTING_4',
                    NAME: 'Enum Example',
                    OPTIONS: {
                      Option1Code: 'Option1Value',
                      Option2Code: 'Option2Value',
                      Option3Code: 'Option3Value',
                      Option4Code: 'Option4Value',
                      Option5Code: 'Option5Value',
                    },
                  },
                  { TYPE: 'DATE', CODE: 'SETTING_5', NAME: 'Date Example' },
                  { TYPE: 'LOCATION', CODE: 'SETTING_6', NAME: 'Location Example' },
                ],
              },
              PROFILES: [
                { NAME: 'Taxi', CODE: 'TAXI', DESCRIPTION: 'Taxi Delivery' },
                { NAME: 'Cargo', CODE: 'CARGO', DESCRIPTION: 'Cargo Delivery' },
              ],
            },
            requestId: Text.getUuidRfc4122()
          })
        
          // The payload is available only on a successful response
          if (!response.isSuccess) {
            console.error(response.getErrorMessages().join('; '))
          } else {
            const result = response.getData()!.result
            console.info('Added delivery handler, ID:', result)
          }
        } catch (error) {
          // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
          console.error(error)
        }
        
<!-- Load the SDK (UMD build); it is exposed as the global B24Js -->
        <script src="https://unpkg.com/@bitrix24/b24jssdk@1/dist/umd/index.min.js"></script>
        <script>
          async function addDeliveryHandler() {
            try {
              // Initialize the SDK inside a Bitrix24 frame
              const $b24 = await B24Js.initializeB24Frame()
        
              const response = await $b24.actions.v2.call.make({
                method: 'sale.delivery.handler.add',
                params: {
                  CODE: 'uber',
                  NAME: 'Uber',
                  DESCRIPTION: 'Uber Description',
                  SORT: 250,
                  SETTINGS: {
                    CALCULATE_URL: 'http://gateway.bx/calculate.php',
                    CREATE_DELIVERY_REQUEST_URL: 'http://gateway.bx/create_delivery_request.php',
                    CANCEL_DELIVERY_REQUEST_URL: 'http://gateway.bx/cancel_delivery_request.php',
                    HAS_CALLBACK_TRACKING_SUPPORT: 'Y',
                    CONFIG: [
                      { TYPE: 'STRING', CODE: 'SETTING_1', NAME: 'String Example' },
                      { TYPE: 'Y/N', CODE: 'SETTING_2', NAME: 'Checkbox Example' },
                      { TYPE: 'NUMBER', CODE: 'SETTING_3', NAME: 'Number Example' },
                      {
                        TYPE: 'ENUM',
                        CODE: 'SETTING_4',
                        NAME: 'Enum Example',
                        OPTIONS: {
                          Option1Code: 'Option1Value',
                          Option2Code: 'Option2Value',
                          Option3Code: 'Option3Value',
                          Option4Code: 'Option4Value',
                          Option5Code: 'Option5Value',
                        },
                      },
                      { TYPE: 'DATE', CODE: 'SETTING_5', NAME: 'Date Example' },
                      { TYPE: 'LOCATION', CODE: 'SETTING_6', NAME: 'Location Example' },
                    ],
                  },
                  PROFILES: [
                    { NAME: 'Taxi', CODE: 'TAXI', DESCRIPTION: 'Taxi Delivery' },
                    { NAME: 'Cargo', CODE: 'CARGO', DESCRIPTION: 'Cargo Delivery' },
                  ],
                },
                requestId: B24Js.Text.getUuidRfc4122()
              })
        
              // The payload is available only on a successful response
              if (!response.isSuccess) {
                console.error(response.getErrorMessages().join('; '))
                return
              }
        
              const result = response.getData().result
              console.info('Added delivery handler, ID:', result)
            } catch (error) {
              // Thrown on transport or SDK failures (AjaxError, SdkError, etc.)
              console.error(error)
            }
          }
        
          document.addEventListener('DOMContentLoaded', addDeliveryHandler)
        </script>
        
try {
            $response = $b24Service
                ->core
                ->call(
                    'sale.delivery.handler.add',
                    [
                        'CODE'        => "uber",
                        'NAME'        => "Uber",
                        'DESCRIPTION' => "Uber Description",
                        'SORT'        => 250,
                        'SETTINGS'    => [
                            'CALCULATE_URL'                => "http://gateway.bx/calculate.php",
                            'CREATE_DELIVERY_REQUEST_URL'  => "http://gateway.bx/create_delivery_request.php",
                            'CANCEL_DELIVERY_REQUEST_URL'  => "http://gateway.bx/cancel_delivery_request.php",
                            'HAS_CALLBACK_TRACKING_SUPPORT' => "Y",
                            'CONFIG'                       => [
                                [
                                    'TYPE' => "STRING",
                                    'CODE' => "SETTING_1",
                                    'NAME' => "String Example",
                                ],
                                [
                                    'TYPE' => "Y/N",
                                    'CODE' => "SETTING_2",
                                    'NAME' => "Checkbox Example",
                                ],
                                [
                                    'TYPE' => "NUMBER",
                                    'CODE' => "SETTING_3",
                                    'NAME' => "Number Example",
                                ],
                                [
                                    'TYPE'    => "ENUM",
                                    'CODE'    => "SETTING_4",
                                    'NAME'    => "Enum Example",
                                    'OPTIONS' => [
                                        "Option1Code" => "Option1Value",
                                        "Option2Code" => "Option2Value",
                                        "Option3Code" => "Option3Value",
                                        "Option4Code" => "Option4Value",
                                        "Option5Code" => "Option5Value",
                                    ],
                                ],
                                [
                                    'TYPE' => "DATE",
                                    'CODE' => "SETTING_5",
                                    'NAME' => "Date Example",
                                ],
                                [
                                    'TYPE' => "LOCATION",
                                    'CODE' => "SETTING_6",
                                    'NAME' => "Location Example",
                                ],
                            ],
                        ],
                        'PROFILES'    => [
                            [
                                'NAME'        => "Taxi",
                                'CODE'        => "TAXI",
                                'DESCRIPTION' => "Taxi Delivery",
                            ],
                            [
                                'NAME'        => "Cargo",
                                'CODE'        => "CARGO",
                                'DESCRIPTION' => "Cargo Delivery",
                            ],
                        ],
                    ]
                );
        
            $result = $response
                ->getResponseData()
                ->getResult();
        
            echo 'Success: ' . print_r($result, true);
        
        } catch (Throwable $e) {
            error_log($e->getMessage());
            echo 'Error adding delivery handler: ' . $e->getMessage();
        }
        
BX24.callMethod(
            'sale.delivery.handler.add', {
                CODE: "uber",
                NAME: "Uber",
                DESCRIPTION: "Uber Description",
                SORT: 250,
                SETTINGS: {
                    CALCULATE_URL: "http://gateway.bx/calculate.php",
                    CREATE_DELIVERY_REQUEST_URL: "http://gateway.bx/create_delivery_request.php",
                    CANCEL_DELIVERY_REQUEST_URL: "http://gateway.bx/cancel_delivery_request.php",
                    HAS_CALLBACK_TRACKING_SUPPORT: "Y",
                    CONFIG: [{
                            TYPE: "STRING",
                            CODE: "SETTING_1",
                            NAME: "String Example",
                        },
                        {
                            TYPE: "Y/N",
                            CODE: "SETTING_2",
                            NAME: "Checkbox Example",
                        },
                        {
                            TYPE: "NUMBER",
                            CODE: "SETTING_3",
                            NAME: "Number Example",
                        },
                        {
                            TYPE: "ENUM",
                            CODE: "SETTING_4",
                            NAME: "Enum Example",
                            OPTIONS: {
                                "Option1Code": "Option1Value",
                                "Option2Code": "Option2Value",
                                "Option3Code": "Option3Value",
                                "Option4Code": "Option4Value",
                                "Option5Code": "Option5Value",
                            },
                        },
                        {
                            TYPE: "DATE",
                            CODE: "SETTING_5",
                            NAME: "Date Example",
                        },
                        {
                            TYPE: "LOCATION",
                            CODE: "SETTING_6",
                            NAME: "Location Example",
                        },
                    ],
                },
                PROFILES: [{
                        NAME: "Taxi",
                        CODE: "TAXI",
                        DESCRIPTION: "Taxi Delivery",
                    },
                    {
                        NAME: "Cargo",
                        CODE: "CARGO",
                        DESCRIPTION: "Cargo Delivery",
                    },
                ],
            },
            function(result) {
                if (result.error()) {
                    console.error(result.error());
                } else {
                    console.info(result.data());
                }
            }
        );
        
require_once('crest.php');
        
        $result = CRest::call(
            'sale.delivery.handler.add',
            [
                'CODE' => "uber",
                'NAME' => "Uber",
                'DESCRIPTION' => "Uber Description",
                'SORT' => 250,
                'SETTINGS' => [
                    'CALCULATE_URL' => "http://gateway.bx/calculate.php",
                    'CREATE_DELIVERY_REQUEST_URL' => "http://gateway.bx/create_delivery_request.php",
                    'CANCEL_DELIVERY_REQUEST_URL' => "http://gateway.bx/cancel_delivery_request.php",
                    'HAS_CALLBACK_TRACKING_SUPPORT' => "Y",
                    'CONFIG' => [
                        ['TYPE' => "STRING", 'CODE' => "SETTING_1", 'NAME' => "String Example"],
                        ['TYPE' => "Y/N", 'CODE' => "SETTING_2", 'NAME' => "Checkbox Example"],
                        ['TYPE' => "NUMBER", 'CODE' => "SETTING_3", 'NAME' => "Number Example"],
                        [
                            'TYPE' => "ENUM",
                            'CODE' => "SETTING_4",
                            'NAME' => "Enum Example",
                            'OPTIONS' => [
                                "Option1Code" => "Option1Value",
                                "Option2Code" => "Option2Value",
                                "Option3Code" => "Option3Value",
                                "Option4Code" => "Option4Value",
                                "Option5Code" => "Option5Value",
                            ],
                        ],
                        ['TYPE' => "DATE", 'CODE' => "SETTING_5", 'NAME' => "Date Example"],
                        ['TYPE' => "LOCATION", 'CODE' => "SETTING_6", 'NAME' => "Location Example"],
                    ],
                ],
                'PROFILES' => [
                    ['NAME' => "Taxi", 'CODE' => "TAXI", 'DESCRIPTION' => "Taxi Delivery"],
                    ['NAME' => "Cargo", 'CODE' => "CARGO", 'DESCRIPTION' => "Cargo Delivery"],
                ],
            ]
        );
        
        echo '<PRE>';
        print_r($result);
        echo '</PRE>';

Ответ в случае успеха

HTTP-статус: 200

{
           "result":14,
           "time":{
              "start":1713872092.378366,
              "finish":1713872092.691408,
              "duration":0.31304192543029785,
              "processing":0.015096187591552734,
              "date_start":"2024-04-23T14:34:52+03:00",
              "date_finish":"2024-04-23T14:34:52+03:00"
           }
        }

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

Название
тип

Описание

result
sale_delivery_handler.ID

Идентификатор обработчика службы доставки

time
time

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

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

HTTP-статус: 400, 403

{
           "error":"ERROR_CHECK_FAILURE",
           "error_description":"Parameter CODE is not defined"
        }

Название
тип

Описание

error
string

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

error_description
error_description

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

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

Код

Описание

Статус

ERROR_CHECK_FAILURE

Ошибка валидации входящих параметров (детали в описании ошибки)

400

ERROR_HANDLER_ADD

Ошибка при попытке добавления обработчика службы доставки

400

ERROR_HANDLER_ALREADY_EXIST

Обработчик службы доставки с указанным кодом CODE уже существует

400

ACCESS_DENIED

Недостаточно прав для добавления обработчика службы доставки

403

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

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

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

429

OPERATION_TIME_LIMIT
Method is blocked due to operation time limit

Метод заблокирован из-за превышения лимита на ресурсоемкость запросов. Блокировка снимается автоматически через 10 минут

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

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

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

Предыдущая
Обзор методов
Следующая
Удалить обработчик службы доставки