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

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

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

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

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

Название `тип`	Описание
SHIPMENTS `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

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

Примеры

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

{
    "SHIPMENTS":[
        {
            "ID":4063,
            "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":2
                }
            ],
            "RESPONSIBLE_CONTACT":{
                "NAME":"Роман Горшков",
                "PHONES":[
                    {
                        "TYPE":"MOBILE",
                        "VALUE":"+79097996161"
                    }
                ]
            },
            "RECIPIENT_CONTACT":{
                "NAME":"Алексей Миронов",
                "PHONES":[
                    {
                        "TYPE":"WORK",
                        "VALUE":"+79097996162"
                    }
                ]
            }
        }
    ]
}

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

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

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

Название `тип`	Описание
SUCCESS* `string`	Результат создания заказа на доставку. Возможные значения: `Y` — заказ на доставку создан `N` — заказ на доставку не создан
REQUEST_ID* `string`	Идентификатор созданного заказа на доставку во внешней системе. Обязателен, если `SUCCESS` = `Y`
REASON `object`	Причина, по которой заказ на доставку не создан. Передается, если `SUCCESS` = `N` (подробное описание)

Объект REASON

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

Пример ответа с успешным созданием заказа на доставку

{
    "SUCCESS": "Y",
    "REQUEST_ID": "4757aca4931a4f029f49c0db4374d13d"
}

Пример ответа с ошибкой создания заказа на доставку

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

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

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

При SUCCESS = Y поле REQUEST_ID должно содержать непустую строку. Ответ без идентификатора считается ошибочным.

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

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

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

Отменить заказ на доставку

Создать заказ на доставку CREATE_DELIVERY_REQUEST_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

Пример ответа с успешным созданием заказа на доставкуПример ответа с успешным созданием заказа на доставку

Пример ответа с ошибкой создания заказа на доставкуПример ответа с ошибкой создания заказа на доставку

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

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