Дополнение заказа доставкой до адреса получателя
Общие сведения
Сервис позволяет оформить заявку на доставку груза от терминала компании Деловые Линии до адреса получателя на основании существующего заказа на перевозку груза до терминала. При этом заказ должен находиться в одном из следующих статусов:
- Груз принят к перевозке;
- Груз принят к перевозке. Платное хранение;
- Груз в пути;
- Груз прибыл на терминал;
- Груз прибыл на терминал. Платное хранение;
- Груз прибыл в аэропорт;
- Груз прибыл в аэропорт. Платное хранение.
Сервис доступен как авторизованным, так и не авторизованным пользователям. Авторизованным пользователям, в отличие от неавторизованных, при работе с методом доступно использование данных адресной книги.
Дополнение заказа доставкой до адреса получателя
Запрос метода
Структура запроса
Адрес метода: https://api.dellin.ru/v2/request_delivery.json
{ "appkey":"111", "sessionID":"00000000-0000-0000-0000-000000000000", "docID":"2000000000000", "delivery":{ "arrival":{ "addressID":457824578, "address":{ "search":"Омск, Ленина, 5", "street":"7800000000004380000000000", "house":"4", "building":"3", "structure":"лит.А", "flat":"214а" }, "produceDate":"2020-11-30", "time":{ "worktimeStart":"09:00", "worktimeEnd":"18:00", "exactTime":true, "breakStart":"12:30", "breakEnd":"13:30" }, "handling":{ "freightLift":true, "toFloor":10, "carry":50 }, "requirements":[ "0x9951e0ff97188f6b4b1b153dfde3cfec", "0xabb9c63c596b08f94c3664c930e77778" ], "payer":"third" }, "comment":"комментарий к отправке" }, "members":{ "receiver":{ "contactIDs":[ 12345678, 78456123 ], "contactPersons":[ { "name":"Иван Иванович" }, { "name":"Петр Петрович" } ], "phoneIDs":[ 98765412, 65478921 ], "phoneNumbers":[ { "number":"79213332211", "ext":"0123" } ] }, "third":{ "counteragentID":456783515, "counteragent":{ "form":"0x8F51001438C4D49511DBD774581EDB80", "name":"Ромашка", "inn":"1234567890", "juridicalAddress":{ "search":"Омск, Ленина, 5", "street":"7800000000004380000000000", "house":"4", "building":"2", "structure":"3А", "flat":"Б-234" }, "document":{ "type":"passport", "serial":"0000", "number":"123456" } }, "contactIDs":[ 12345678, 78456123 ], "contactPersons":[ { "name":"Иван Иванович" }, { "name":"Петр Петрович" } ], "phoneIDs":[ 98765412, 65478921 ], "phoneNumbers":[ { "number":"79213332211", "ext":"0123" } ], "email":"test@mail.ru", "dataForReceipt":{ "send":true, "phone":"+79999999999", "email":"test@mail.ru" } } }, "payment":{ "type":"cash", "promocode":"promo123", "email":"test@mail.ru", "paymentCity":"7800000000000000000000000", "paymentCitySearch":{ "search":"Омск" } }, "notify":{ "phone":"79999999999", "email":"test@mail.ru" } }
Адрес метода: https://api.dellin.ru/v2/request_delivery.xml
<request> <appkey>111</appkey> <sessionID>00000000-0000-0000-0000-000000000000</sessionID> <docID>2000000000000</docID> <delivery> <arrival> <addressID>457824578</addressID> <address> <search>Омск, Ленина, 5</search> <street>7800000000004380000000000</street> <house>4</house> <building>3</building> <structure>лит.А</structure> <flat>214а</flat> </address> <produceDate>2020-11-30</produceDate> <time> <worktimeStart>09:00</worktimeStart> <worktimeEnd>18:00</worktimeEnd> <exactTime>true</exactTime> <breakStart>12:30</breakStart> <breakEnd>13:30</breakEnd> </time> <handling> <freightLift>true</freightLift> <toFloor>10</toFloor> <carry>50</carry> </handling> <requirements>0x9951e0ff97188f6b4b1b153dfde3cfec</requirements> <requirements>0xabb9c63c596b08f94c3664c930e77778</requirements> <payer>third</payer> </arrival> <comment>комментарий к отправке</comment> </delivery> <members> <receiver> <contactIDs>12345678</contactIDs> <contactIDs>78456123</contactIDs> <contactPersons> <name>Иван Иванович</name> </contactPersons> <contactPersons> <name>Петр Петрович</name> </contactPersons> <phoneIDs>98765412</phoneIDs> <phoneIDs>65478921</phoneIDs> <phoneNumbers> <number>79213332211</number> <ext>0123</ext> </phoneNumbers> </receiver> <third> <counteragentID>456783515</counteragentID> <counteragent> <form>0x8F51001438C4D49511DBD774581EDB80</form> <name>Ромашка</name> <inn>1234567890</inn> <juridicalAddress> <search>Омск, Ленина, 5</search> <street>7800000000004380000000000</street> <house>4</house> <building>2</building> <structure>3А</structure> <flat>Б-234</flat> </juridicalAddress> <document> <type>passport</type> <serial>0000</serial> <number>123456</number> </document> </counteragent> <contactIDs>12345678</contactIDs> <contactIDs>78456123</contactIDs> <contactPersons> <name>Иван Иванович</name> </contactPersons> <contactPersons> <name>Петр Петрович</name> </contactPersons> <phoneIDs>98765412</phoneIDs> <phoneIDs>65478921</phoneIDs> <phoneNumbers> <number>79213332211</number> <ext>0123</ext> </phoneNumbers> <email>test@mail.ru</email> <dataForReceipt> <send>true</send> <phone>+79999999999</phone> <email>test@mail.ru</email> </dataForReceipt> </third> </members> <payment> <type>cash</type> <promocode>promo123</promocode> <email>test@mail.ru</email> <paymentCity>7800000000000000000000000</paymentCity> <paymentCitySearch> <search>Омск</search> </paymentCitySearch> </payment> <notify> <phone>79999999999</phone> <email>test@mail.ru</email> </notify> </request>
Описание параметров
Request
Request | |||
---|---|---|---|
Параметр | Обязательный | Тип | Описание |
appkey | Да | string | Ключ приложения. Для получения ключа необходимо пройти регистрацию |
sessionID | Нет | string | ID сессии. Для получения сессии можно воспользоваться методом "Авторизация пользователя" |
docID | Да | string | Номер заказа или накладной |
delivery | Да | object | Параметры доставки |
delivery.arrival | Да | Arrival | Доставка до адреса |
delivery.comment | Нет | string | Комментарий к заказу. Максимум 500 символов |
members | Да | object | Участники перевозки |
members.receiver | Да | Member | Получатель |
members.third | Нет* | Member | Третье лицо *Параметр является обязательным, если плательщик - третье лицо (значение параметра запроса "delivery.arrival.payer" - "third" |
payment | Да | Payment | Параметры оплаты |
notify | Нет | object | Контактные данные для отправки уведомлений |
notify.phone | Нет | string | Номер телефона. Формат: "7XXXXXXXXXX" (11 цифр с ведущей семёркой) |
notify.email | Нет | string | Адрес электронной почты |
Arrival
Arrival | |||
---|---|---|---|
Параметр | Обязательный | Тип | Описание |
addressID | Нет* | integer | ID адреса из "Адресной книги" *Если пользователь не авторизован (параметр "sessionID" отсутствует в запросе), то параметр игнорируется. Если пользователь авторизован (в запросе передан параметр "sessionID"), то передача одного из взаимоисключающих параметров "addressID" или "address" является обязательной |
address | Нет* | Address | Адрес. *Если пользователь не авторизован (параметр "sessionID" отсутствует в запросе), то параметр является обязательным. Если пользователь авторизован (в запросе передан параметр "sessionID"), то передача одного из взаимоисключающих параметров "addressID" или "address" является обязательной |
produceDate | Да | string | Дата приезда машины к получателю. Формат: ГГГГ-ММ-ДД Получить список дат, на которые может быть назначена доставка груза, можно при помощи метода "Подбор даты доставки" |
time | Да | object | Время доставки груза |
time.worktimeStart | Да | string | Начало периода. Формат: ЧЧ:ММ |
time.worktimeEnd | Да | string | Конец периода. Формат: ЧЧ:ММ |
time.exactTime | Нет | boolean | Доставка груза в точное время. Значение по умолчанию: "false" |
time.breakStart | Нет | string | Начало перерыва. Формат: ЧЧ:ММ |
time.breakEnd | Нет | string | Окончание перерыва. Формат: ЧЧ:ММ |
handling | Нет | object | Погрузо-разгрузочные работы на адресе |
handling.freightLift | Нет | boolean | Флаг, обозначающий, что есть грузовой лифт. Значение по умолчанию: "false" |
handling.toFloor | Нет | integer | Номер этажа, на который необходимо поднять груз. Максимальная длина поля: 5 символов |
handling.carry | Нет | integer | Расстояние, на которое необходимо перенести груз (в метрах). Максимальная длина поля: 5 символов |
requirements | Нет | array of strings | Дополнительные требования к транспорту. Указываются UID'ы из "Справочника специальных требований к транспорту" и "Справочника видов загрузки". Дополнительные требования включают в себя вид загрузки машины (боковая, задняя и пр.), а также другие требования: манипулятор, растентовка и пр. Невозможно выбрать одновременно боковую и верхнюю загрузку |
payer | Да | string | Плательщик по услуге. Доступные значения:
|
Address
Address | |||
---|---|---|---|
Параметр | Обязательный | Тип | Описание |
search | Нет (1) | string | Адрес в виде произвольной строки. Адрес может быть передан в виде текста или координат. Однако, координаты не следует использовать для передачи информации о юридическом адресе, то есть в блоках "juridicalAddress" класса "Counteragent". При передаче адреса в виде текста, помимо собственно адреса, в запрос следует включать наименование населённого пункта, элементы необходимо указывать через запятую, например, "Омск, Ленина, 5". Координаты также указываются через запятую, первое число - широта, например, "59.924501, 30.241762". Максимум - 1024 символа (2) |
street | Нет (1) | string | Код КЛАДР улицы. Может быть получен с помощью сервисов, представленных на странице "Поиск КЛАДР" (2) |
house | Нет (1) | string | Номер дома, включая литеру. Например, "13/А" (2). Максимальная длина поля: 7 символов |
building | Нет | string | Корпус (2). Максимальная длина поля: 5 символов |
structure | Нет | string | Строение (2). Максимальная длина поля: 7 символов |
flat | Нет | string | Номер квартиры/офиса. Допускается написание с буквой, например "222 А"(2). Максимальная длина поля: 5 символов |
Примечания:
|
Member
Member | |||
---|---|---|---|
Параметр | Обязательный | Тип | Описание |
counteragentID | Нет* | integer | ID контрагента из "Адресной книги" *Данный параметр используется только для объекта "request.members.third", при этом если пользователь не авторизован, то параметр игнорируется. Если пользователь авторизован, то передача одного из взаимоисключающих параметров "counteragentID" или "counteragent" является обязательной |
counteragent | Нет* | Counteragent | Данные контрагента в виде набора параметров *Данный параметр используется только для объекта "request.members.third", при этом если пользователь не авторизован, то параметр является обязательным. Если пользователь авторизован, то передача одного из взаимоисключающих параметров "counteragentID" или "counteragent" является обязательной |
contactIDs | Нет* | array of integers | Список ID контактных лиц из "Адресной книги". Максимальное количество элементов в массиве - 3 *Если пользователь не авторизован, то параметр игнорируется. Если пользователь авторизован, то передача одного из взаимоисключающих параметров "contactID" или "contactPersons" является обязательной |
contactPersons | Нет* | array of ContactPersons | Данные контактных лиц. Максимальное количество элементов в массиве для авторизованных пользователей - 3, для неавторизованных - 1 *Если пользователь не авторизован, то параметр игнорируется. Если пользователь авторизован, то передача одного из взаимоисключающих параметров "contactID" или "contactPersons" является обязательной |
contactPersons.name | Да | string | Имя контактного лица |
phoneIDs | Нет* | array of integers | Список IDтелефонных номеров из "Адресной книги". Максимальное количество элементов в массиве: 3 *Если пользователь не авторизован, то параметр игнорируется. Если пользователь авторизован, то передача одного из взаимоисключающих параметров "phoneID" или "phoneNumbers" является обязательной |
phoneNumbers | Нет* | array of PhoneNumbers | Список телефонных номеров. Максимальное количество элементов в массиве для авторизованных пользователей - 3, для неавторизованных - 1 *Параметр является обязательным для неавторизованных пользователей. Для авторизованных пользователей обязательна передача одного из взаимоисключающих параметров "phoneID" or "phoneNumbers" |
phoneNumbers.number | Да | string | Номер телефона. Допускаются цифры и знак "+" в начале строк, начинающихся с 7 или 375 |
phoneNumbers.ext | Нет | string | Добавочный номер. Максимум 5 цифр |
Нет | string | Адрес электронной почты заказчика перевозки Данный параметр используется только для объекта "request.members.third" | |
dataForReceipt | Нет* | object | Контактные данные для отправки электронного чека плательщику-физическому лицу *Данный параметр используется только для объекта "request.members.third", при этом параметр является обязательным для контрагента-физического лица то есть, если UID физического лица передан в качестве значения параметра "form" в текущем запросе в классе "Counteragent" или же при создании контрагента при помощи метода "Создание и редактирование контрагентов" |
dataForReceipt.send | Да | boolean | Флаг, свидетельствующий о согласии на получение электронного чека об оплате |
dataForReceipt.phone | Нет* | string | Номер телефона для отправки чека в формате "+79XXXXXXXXX" (где X - любая цифра) *Если значение параметра "dataForReceipt.send" - "true", то обязательно должен быть передан хотя бы один из параметров: "dataForReceipt.phone" или "dataForReceipt.email" |
dataForReceipt.email | Нет* | string | Адрес электронной почты для отправки чека *Если значение параметра "dataForReceipt.send" - "true", то обязательно должен быть передан хотя бы один из параметров: "dataForReceipt.phone" или "dataForReceipt.email". |
Counteragent
Counteragent | |||
---|---|---|---|
Параметр | Обязательный | Тип | Описание |
form | Да | string | UID организационно-правовой формы (далее - ОПФ), см. метод "Поиск ОПФ" |
name | Да | string | Имя контрагента или наименование юридического лица |
inn | Нет* | string | ИНН. Максимальная допустимая длина поля зависит от страны и ОПФ. *Если контрагент является юридическим лицом (в качестве значения параметра "form" передан UID ОПФ юридического лица), то параметр является обязательным, если контрагент является физическим лицом (в качестве значения параметра "form" передан UID ОПФ физического лица), то параметр игнорируется |
juridicalAddress | Нет | Address | Юридический адрес. Параметр используется только для юридических лиц |
document | Нет* | object | Документ, удостоверяющий личность *Если контрагент является физическим лицом, то параметр является обязательным |
document.type | Да | string | Тип документа. Доступные значения:
|
document.serial | Да* | string | Серия документа. *Для некоторых стран параметр не является обязательным и игнорируется |
document.number | Да | string | Номер документа. Формат номера зависит от страны |
Payment
Payment | |||
---|---|---|---|
Параметр | Обязательный | Тип | Описание |
type | Да | string | Вид оплаты (1). Доступные значения:
|
promocode | Нет | string | Промокод |
Нет | string | Адрес электронной почты для отправки счёта. Параметр используется только в случае оплаты посредством банковского перевода (значение параметра "type" - "noncash") | |
paymentCity | Нет* | string | Код КЛАДР населенного пункта оплаты (1). Может быть получен с помощью сервисов, представленных на странице "Поиск КЛАДР" *Если плательщик - третье лицо (значение параметра запроса "delivery.arrival.payer" - "third"), то один из взаимоисключающих параметров "paymentCity" или "paymentCitySearch" является обязательным, в противном случае параметр игнорируется |
paymentCitySearch | Нет* | object | Данные по населённому пункту оплаты в виде произвольной строки (1) *Если плательщик - третье лицо (значение параметра запроса "delivery.arrival.payer" - "third"), то один из взаимоисключающих параметров "paymentCity" или "paymentCitySearch" является обязательным, в противном случае параметр игнорируется |
paymentCitySearch.search | Да | string | Населённый пункт в виде произвольной строки. Максимум - 1024 символа. Помимо наименования населённого пункта, в строке может быть передано наименование страны, региона, района - это позволит уточнить поиск и исключить ошибки, которые могут возникнуть из-за одинаковых названий населённых пунктов |
Примечания:
|
Ответ метода
Структура ответа
{ "metadata":{ "status":200, "generatedAt":"2020-11-03 12:37:28" }, "data":{ "state":"success", "requestID":3954004, "information":[ "Промокод нельзя применить в заказе" ], "foundAddresses":[ { "field":"delivery.arrival.address", "source":"Омск, Ленина, 5", "result":"Россия, Омская обл, г Омск, ул Ленина, д 5" }, { "field":"members.third.counteragent.juridicalAddress", "source":"Омск, Ленина, 5", "result":"Россия, Омская обл, г Омск, ул Ленина, д 5" }, { "field":"payment.paymentCitySearch", "source":"Омск", "result":"Россия, Омская обл, г Омск" } ] } }
<response> <metadata> <status>200</status> <generatedAt>2020-11-03 12:37:28</generatedAt> </metadata> <data> <state>success</state> <requestID>3954004</requestID> <information>Промокод нельзя применить в заказе</information> <foundAddresses> <field>delivery.arrival.address</field> <source>Омск, Ленина, 5</source> <result>Россия, Омская обл, г Омск, ул Ленина, д 5</result> </foundAddresses> <foundAddresses> <field>members.third.counteragent.juridicalAddress</field> <source>Омск, Ленина, 5</source> <result>Россия, Омская обл, г Омск, ул Ленина, д 5</result> </foundAddresses> <foundAddresses> <field>payment.paymentCitySearch</field> <source>Омск</source> <result>Россия, Омская обл, г Омск</result> </foundAddresses> </data> </response>
Описание параметров
Response
Response | ||
---|---|---|
Параметр | Тип | Описание |
metadata | object | Системная информация |
metadata.status | integer | Эмуляция http-кода состояния. В случае успешного выполнения возвращается код "200" (OK) |
metadata.generatedAt | string | Дата и время генерации ответа сервера. Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС" |
data | object | Информация по итогу формирования заявки |
data.state | string | Статус операции на английском языке. Возможное значение - "success" |
data.requestID | integer | Номер созданной заявки |
data.information | array of strings | Информационное сообщение. Отображается, например, если в запросе был передан промокод, но применить его по какой-то причине невозможно |
data.foundAddresses | array of FoundAddresses | Данные по найденным адресам/населённым пунктам. Параметр присутствует в ответе, только если в запросе был передан параметр "search" класса "Address" или параметр "payment.paymentCitySearch.search" |
FoundAddresses
FoundAddresses | ||
---|---|---|
Параметр | Тип | Описание |
field | string | Объект, в котором был передан параметр "search" |
source | string | Введённое значение |
result | string | Найденный адрес/населённый пункт |
Обработка ошибок
В методе используются общие ошибки API, описание формата и перечень ошибок см. в документе "Ошибки методов API".