Рассчитать стоимость доставки CALCULATE_URL

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

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

Битрикс24 отправляет HTTP-запрос методом POST на адрес из параметра CALCULATE_URL, который передан при создании обработчика доставки методом sale.delivery.handler.add. Внешняя система должна рассчитать стоимость доставки и вернуть результат в формате JSON.

Параметры запроса

Название `тип`	Описание
SHIPMENT `object`	Информация об отгрузке (подробное описание приведено ниже)

SHIPMENT

Название `тип`	Описание
ID `sale_order_shipment.id`	Идентификатор отгрузки. В случае, если расчет идет по еще несохраненной отгрузке, то значение параметра будет `null`. Получить идентификаторы отгрузок можно с помощью метода sale.shipment.list
DELIVERY_SERVICE `object`	Информация о выбранной службе доставки, ее профиле и настройках (подробное описание приведено ниже). Может быть `null`, если служба доставки не найдена
PRICE `double`	Полная стоимость товаров для клиента в отгрузке
CURRENCY `crm_currency.CURRENCY`	Код валюты стоимости
WEIGHT `double`	Полный вес товаров в отгрузке (в граммах)
PROPERTY_VALUES `object[]`	Массив, содержащий значения свойств отгрузки (подробное описание приведено ниже)
ITEMS `object[]`	Массив, содержащий все товары, входящие в отгрузку (подробное описание приведено ниже)
EXTRA_SERVICES_VALUES `object[]`	Массив, содержащий список необходимых дополнительных услуг, выбранных для доставки (подробное описание приведено ниже)
RESPONSIBLE_CONTACT `object`	Информация о сотруднике, ответственном за доставку со стороны Битрикс24 (подробное описание приведено ниже). Может быть `null`, если ответственный не указан или не найден
RECIPIENT_CONTACT `object`	Информация о получателе груза (подробное описание приведено ниже). Может быть `null`, если контакт получателя недоступен

DELIVERY_SERVICE

Название `тип`	Описание
ID `sale_delivery_service.ID`	Идентификатор службы доставки
CONFIG `object[]`	Значения настроек службы доставки (подробное описание приведено ниже)
PARENT `object`	Информация о родительской службе доставки (подробное описание приведено ниже). Поле отсутствует, если родительская служба не задана

PARENT

Название `тип`	Описание
ID `sale_delivery_service.ID`	Идентификатор родительской службы доставки
CONFIG `object[]`	Значения настроек родительской службы доставки (подробное описание приведено ниже)

CONFIG

Название `тип`	Описание
CODE `string`	Символьный код настройки
VALUE `any`	Значение настройки

PROPERTY_VALUES

Название `тип`	Описание
ID `sale_shipment_property.id`	Идентификатор свойства отгрузки. Получить идентификатор свойств отгрузки можно с помощью метода sale.shipmentproperty.list
TYPE `string`	Тип свойства. Возможные значения: `STRING` — строка `ADDRESS` — адрес
VALUE `string` \| `object`	Значение свойства. Для типа `object` подробное описание приведено ниже. Может быть `null`, если значение адреса отсутствует

VALUE

Название `тип`	Описание
LATITUDE `double`	Географическая широта. Может быть `null`
LONGITUDE `double`	Географическая долгота. Может быть `null`
FIELDS `object`	Детальная информация по адресу доставки (подробное описание приведено ниже)

FIELDS

Состав объекта зависит от заполненных частей адреса. Битрикс24 передает доступные поля из следующего списка.

Название `тип`	Описание
POSTAL_CODE `string`	Почтовый индекс
COUNTRY `string`	Страна
ADM_LEVEL_1 `string`	Единица административно-территориального деления первого уровня (например, штат или область)
ADM_LEVEL_2 `string`	Единица административно-территориального деления второго уровня (например, район)
ADM_LEVEL_3 `string`	Единица административно-территориального деления третьего уровня
ADM_LEVEL_4 `string`	Единица административно-территориального деления четвертого уровня
LOCALITY `string`	Населенный пункт
SUB_LOCALITY `string`	Район или часть населенного пункта
SUB_LOCALITY_LEVEL_1 `string`	Первый уровень части населенного пункта
SUB_LOCALITY_LEVEL_2 `string`	Второй уровень части населенного пункта
STREET `string`	Улица
BUILDING `string`	Здание, номер дома
ADDRESS_LINE_1 `string`	Адрес (улица, здание, номер дома)
ADDRESS_LINE_2 `string`	Дополнительная строка адреса
FLOOR `string`	Этаж
ROOM `string`	Помещение
RECIPIENT_COMPANY `string`	Название компании получателя
RECIPIENT `string`	Имя получателя
PO_BOX `string`	Номер абонентского ящика

ITEMS

Название `тип`	Описание
NAME `string`	Название товара
PRICE `double`	Стоимость одной позиции товара
CURRENCY `crm_currency.CURRENCY`	Код валюты стоимости
WEIGHT `double`	Вес одной позиции товара. Может быть `null`, если вес не указан
QUANTITY `double`	Количество единиц товара
DIMENSIONS `object`	Размеры груза (подробное описание приведено ниже). Может быть `null`, если размеры не указаны полностью

DIMENSIONS

Название `тип`	Описание
LENGTH `double`	Длина товара в миллиметрах
WIDTH `double`	Ширина товара в миллиметрах
HEIGHT `double`	Высота товара в миллиметрах

EXTRA_SERVICES_VALUES

Название `тип`	Описание
ID `sale_delivery_extra_service.ID`	Идентификатор услуги. Получить идентификаторы услуг службы доставки можно с помощью метода sale.delivery.extra.service.get
CODE `string`	Символьный код дополнительной услуги
VALUE `string` \| `double`	Значение. В зависимости от типа (sale_delivery_extra_service.TYPE) дополнительной услуги значение формируется различно: `checkbox` `Y` — если услуга требуется `N` — если услуга не требуется `enum` — строка, содержащая символьный код выбранного значения списка услуги `quantity` — число, отражающее необходимое количество для дополнительной услуги

RESPONSIBLE_CONTACT

Название `тип`	Описание
NAME `string`	Полное имя контакта
PHONES `object[]`	Массив с номерами телефонов контакта (подробное описание приведено ниже)

RECIPIENT_CONTACT

Название `тип`	Описание
NAME `string`	Полное имя контакта
PHONES `object[]`	Массив с номерами телефонов контакта (подробное описание приведено ниже). Поле отсутствует, если телефоны не указаны

PHONES

Название
тип

Описание

TYPE
string

Тип телефона. Возможные значения:

WORK — рабочий
MOBILE — мобильный
HOME — домашний
FAX — факс
PAGER — пейджер

VALUE
string

Номер телефона

Пример запроса

{
    "SHIPMENT":{
        "ID":4060,
        "DELIVERY_SERVICE":{
            "ID":225,
            "CONFIG":[
                {
                    "CODE":"PROFILE_TYPE",
                    "VALUE":"CARGO"
                }
            ],
            "PARENT":{
                "ID":223,
                "CONFIG":[
                    {
                        "CODE":"SETTING_1",
                        "VALUE":"String Example Value"
                    }
                ]
            }
        },
        "PRICE":179998,
        "CURRENCY":"RUB",
        "WEIGHT":600,
        "PROPERTY_VALUES":[
            {
                "ID":100,
                "TYPE":"ADDRESS",
                "VALUE":{
                    "LATITUDE":55.726421,
                    "LONGITUDE":37.61187,
                    "FIELDS":{
                        "COUNTRY":"Россия",
                        "ADM_LEVEL_1":"Москва",
                        "ADM_LEVEL_2":"Москва",
                        "ADM_LEVEL_3":"Якиманка",
                        "LOCALITY":"Москва",
                        "SUB_LOCALITY_LEVEL_1":"Центральный административный округ",
                        "STREET":"улица Шаболовка",
                        "BUILDING":"9",
                        "ADDRESS_LINE_1":"улица Шаболовка, 9"
                    }
                }
            },
            {
                "ID":101,
                "TYPE":"ADDRESS",
                "VALUE":{
                    "LATITUDE":55.724779,
                    "LONGITUDE":37.614294,
                    "FIELDS":{
                        "POSTAL_CODE":"115162",
                        "COUNTRY":"Россия",
                        "ADM_LEVEL_1":"Москва",
                        "ADM_LEVEL_2":"район Якиманка",
                        "LOCALITY":"Москва",
                        "STREET":"улица Шаболовка",
                        "BUILDING":"13 с10",
                        "ADDRESS_LINE_1":"улица Шаболовка, 13 с10"
                    }
                }
            }
        ],
        "ITEMS":[
            {
                "NAME":"iPhone 14",
                "PRICE":89999,
                "WEIGHT":300,
                "CURRENCY":"RUB",
                "QUANTITY":2,
                "DIMENSIONS":{
                    "WIDTH":400,
                    "HEIGHT":80,
                    "LENGTH":500
                }
            }
        ],
        "EXTRA_SERVICES_VALUES":[
            {
                "ID":138,
                "CODE":"cargo_type",
                "VALUE":"small_package"
            },
            {
                "ID":137,
                "CODE":"door_delivery",
                "VALUE":"Y"
            },
            {
                "ID":139,
                "CODE":"some_quantity_service",
                "VALUE":3
            }
        ],
        "RESPONSIBLE_CONTACT":{
            "NAME":"Роман Горшков",
            "PHONES":[
                {
                    "TYPE":"MOBILE",
                    "VALUE":"+79097996161"
                }
            ]
        },
        "RECIPIENT_CONTACT":{
            "NAME":"Алексей Миронов",
            "PHONES":[
                {
                    "TYPE":"WORK",
                    "VALUE":"+79097996161"
                }
            ]
        }
    }
}

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

Обработчик должен вернуть HTTP-статус 200 и JSON-объект.

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

Название `тип`	Описание
SUCCESS* `string`	Индикатор успеха расчета стоимости доставки. Возможные значения: `Y` — стоимость успешно рассчитана `N` — произошла ошибка при попытке расчета стоимости
PRICE `double`	Рассчитанная стоимость доставки в валюте службы доставки
PERIOD_DESCRIPTION `string`	Текстовое описание срока доставки
PERIOD_FROM `integer`	Нижняя граница срока доставки в единицах, указанных в `PERIOD_TYPE`
PERIOD_TO `integer`	Верхняя граница срока доставки в единицах, указанных в `PERIOD_TYPE`
PERIOD_TYPE `string`	Единица измерения срока доставки. Возможные значения: `MIN` — минуты `H` — часы `D` — дни `M` — месяцы
DESCRIPTION `string`	Дополнительное описание результата расчета
REASON `object`	Причина ошибки. Передается в случае неудачной попытки расчета стоимости (подробное описание приведено ниже)

Объект REASON

Название `тип`	Описание
TEXT* `string`	Описание ошибки

Пример ответа с успешным расчетом стоимости

{
    "SUCCESS": "Y",
    "PRICE": 79.99,
    "PERIOD_DESCRIPTION": "1-2 дня",
    "PERIOD_FROM": 1,
    "PERIOD_TO": 2,
    "PERIOD_TYPE": "D",
    "DESCRIPTION": "Доставка курьером до двери"
}

Пример ответа с ошибкой при расчете стоимости

{
    "SUCCESS": "N",
    "REASON": {
        "TEXT": "Delivery is not available for the specified address"
    }
}

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

Если SUCCESS отсутствует или отличается от Y, Битрикс24 считает расчет неуспешным. Передайте пояснение в REASON.TEXT. Если поле REASON.TEXT отсутствует или пустое, Битрикс24 использует стандартный текст ошибки расчета доставки.

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

Была ли статья полезна?

Вебхуки при работе с доставками

Создать заказ на доставку

Рассчитать стоимость доставки CALCULATE_URL

Параметры запросаПараметры запроса

SHIPMENTSHIPMENT

DELIVERY_SERVICEDELIVERY_SERVICE

PARENTPARENT

CONFIGCONFIG

PROPERTY_VALUESPROPERTY_VALUES

VALUEVALUE

FIELDSFIELDS

ITEMSITEMS

DIMENSIONSDIMENSIONS

EXTRA_SERVICES_VALUESEXTRA_SERVICES_VALUES

RESPONSIBLE_CONTACTRESPONSIBLE_CONTACT

RECIPIENT_CONTACTRECIPIENT_CONTACT

PHONESPHONES

Пример запросаПример запроса

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

Объект REASONОбъект REASON

Пример ответа с успешным расчетом стоимостиПример ответа с успешным расчетом стоимости

Пример ответа с ошибкой при расчете стоимостиПример ответа с ошибкой при расчете стоимости

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

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