Дополнение заказа доставкой до адреса получателя

Обновлено 08.08.2023

199 кб

Общие сведения

Сервис позволяет оформить заявку на доставку груза от терминала компании Деловые Линии до адреса получателя на основании существующего заказа на перевозку груза до терминала. При этом заказ должен находиться в одном из следующих статусов:

Груз принят к перевозке;
Груз принят к перевозке. Платное хранение;
Груз в пути;
Груз прибыл на терминал;
Груз прибыл на терминал. Платное хранение;
Груз прибыл в аэропорт;
Груз прибыл в аэропорт. Платное хранение.

Сервис доступен как авторизованным, так и не авторизованным пользователям. Авторизованным пользователям, в отличие от неавторизованных, при работе с методом доступно использование данных адресной книги.

Дополнение заказа доставкой до адреса получателя

Запрос метода

Адрес метода: 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	Плательщик по услуге. Доступные значения: "sender" - отправитель; "receiver" - получатель; "third" - третье лицо

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 символов
Примечания: Обязательно должен быть передан адрес - в виде строки ("search") или набора параметров (в этом случае обязательными являются параметры "street" и "house"). Передача параметра "search" исключает передачу параметров "street", "house", "building" и "structure", но допускает передачу параметра "flat" (в этом случае в качестве номера квартиры/офиса будет использоваться значение параметра "flat")

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 цифр
email	Нет	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	Тип документа. Доступные значения: "passport" - паспорт; "drivingLicence" - водительское удостоверение; "foreignPassport" - заграничный паспорт. Для некоторых стран значение "foreignPassport" недоступно
document.serial	Да*	string	Серия документа. *Для некоторых стран параметр не является обязательным и игнорируется
document.number	Да	string	Номер документа. Формат номера зависит от страны

Payment

Payment
Параметр	Обязательный	Тип	Описание
type	Да	string	Вид оплаты (1). Доступные значения: "cash" - оплата наличными или банковской картой; "noncash" - оплата посредством банковского перевода
promocode	Нет	string	Промокод
email	Нет	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 символа. Помимо наименования населённого пункта, в строке может быть передано наименование страны, региона, района - это позволит уточнить поиск и исключить ошибки, которые могут возникнуть из-за одинаковых названий населённых пунктов
Примечания: В некоторых населённых пунктах оплата наличными/банковской картой (значение параметра "type" - "cash") невозможна, оплатить услугу в этих населённых пунктах можно только посредством банковского перевода (значение параметра "type" - "noncash"). Передав один из взаимоисключающих параметров - "paymentCity" или "paymentCitySearch", можно удостовериться, что в населённом пункте доступна выбранная форма оплаты. Кроме того, список населённых пунктов, в которых доступна только оплата посредством банковского перевода, можно найти в "Справочнике населенных пунктов с ограничениями по оплате"

Ответ метода

Структура ответа

JSON
XML

{  
   "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".

Поиск по сайту

Дополнение заказа доставкой до адреса получателя

Общие сведения

Дополнение заказа доставкой до адреса получателя

Запрос метода

Структура запроса

Описание параметров

Request

Arrival

Address

Member

Counteragent

Payment

Ответ метода

Структура ответа

Описание параметров

Response

FoundAddresses

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