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

API
Главная / API - Дополнение заказа доставкой

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

Обновлено 02.02.2021
197 кб

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

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

Оформление заявок на доставку от терминала до адреса

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

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

Адрес метода: 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",
      "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>
      <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Адрес в виде произвольной строки. Минимум 2 символа, максимум - 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 символов

Примечания:

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

Список телефонных номеров.

Максимальное количество элементов в массиве для авторизованных пользователей - 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

Вид оплаты.

Доступные значения:

  • "cash" - оплата наличными или банковской картой;
  • "noncash" - оплата посредством банковского перевода
emailНетstring

Адрес электронной почты для отправки счёта. Параметр используется только в случае оплаты посредством банковского перевода (значение параметра "type" - "noncash")

paymentCityНет*string

Код КЛАДР населенного пункта оплаты. Может быть получен с помощью сервисов, представленных на странице "Использование кодов КЛАДР"

*Если плательщик - третье лицо (значение параметра запроса "delivery.arrival.payer" - "third") и выбрана оплата наличными/банковской картой (значение параметра запроса "payment.type" - "cash", то один из взаимоисключающих параметров "paymentCity" или "paymentCitySearch" является обязательным, в противном случае параметр игнорируется

paymentCitySearch

Нет*object

Данные по населённому пункту оплаты в виде произвольной строки

*Если плательщик - третье лицо (значение параметра запроса "delivery.arrival.payer" - "third") и выбрана оплата наличными/банковской картой (значение параметра запроса "payment.type" - "cash", то один из взаимоисключающих параметров "paymentCity" или "paymentCitySearch" является обязательным, в противном случае параметр игнорируется

paymentCitySearch.search

ДаstringНаселённый пункт в виде произвольной строки. Минимум 2 символа, максимум - 1024. Помимо наименования населённого пункта, в строке может быть передано наименование страны, региона, района - это позволит уточнить поиск и исключить ошибки, которые могут возникнуть из-за одинаковых названий населённых пунктов

Ответ метода

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

{  
   "metadata":{
      "status":200,
      "generatedAt":"2020-11-03 12:37:28"
   },
   "data":{
      "state":"success",
      "requestID":3954004,
      "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>
      <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
ПараметрТипОписание
metadataobjectСистемная информация
metadata.statusinteger

Эмуляция http-кода состояния. В случае успешного выполнения возвращается код "200" (OK)

metadata.generatedAtstring

Дата и время генерации ответа сервера.

Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС"

dataobjectИнформация по итогу формирования заявки
data.statestringСтатус операции на английском языке. Возможное значение - "success"
data.requestIDintegerНомер созданной заявки
data.foundAddressesarray of FoundAddresses

Данные по найденным адресам/населённым пунктам. Параметр присутствует в ответе, только если в запросе был передан параметр "search" класса "Address" или параметр "payment.paymentCitySearch.search"

FoundAddresses
FoundAddresses
ПараметрТипОписание
fieldstringОбъект, в котором был передан параметр "search"
sourcestring

Введённое значение

resultstring

Найденный адрес/населённый пункт

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

В методе используются общие ошибки API, описание формата и перечень ошибок см. в документе "Ошибки методов API".