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

API
Главная / API - Изменение адреса и времени доставки

Изменение адреса и времени доставки

Обновлено 08.08.2023
Скачать в PDF
210 кб
Содержание:

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

Сервис позволяет изменить терминал доставки (в случае, если изначально была заказана доставка до терминала) или адрес, дату и время приезда экспедитора (если была заказана доставка до адреса) и при необходимости указать нового получателя и/или плательщика за услугу доставки/перенаправление груза. Для внесения изменений необходим полный доступ к отправителю, получателю или плательщику, однако, перенаправление груза в другой город возможно только при наличии полного доступа к отправителю (подробнее о полном доступе см. в описании параметра ответа info.accessLevel метода "Список контрагентов"). Для проверки возможности внесения изменений следует использовать метод "Доступные изменения заказа". Изменения вступают в силу не сразу. После дополнительной проверки заявка на внесение изменений может быть одобрена или отклонена. Проверить статус заявки можно при помощи метода "История изменений заказа".

Изменение адреса или времени доставки

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

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

Адрес метода: https://api.dellin.ru/v3/orders/change_delivery.json 

{
   "appkey":"00000000-0000-0000-0000-000000000000",
   "sessionID":"00000000-0000-0000-0000-000000000000",
   "orderID":"00000000",
   "delivery":{
      "arrival":{
         "produceDate":"2020-04-10",
         "variant":"terminal",
         "terminalID":123,
         "addressID":"457824578",
         "address":{
            "search":"Омск, Ленина, 5",
            "street":"5500000100005970000000000",
            "house":"5",
            "building":"1",
            "structure":"3А",
            "flat":"Б-234"
         },
         "city":"5500000100000000000000000",
         "time":{
            "worktimeStart":"09:00",
            "worktimeEnd":"18:00",
            "breakStart":"12:30",
            "breakEnd":"13:30",
            "exactTime":true
         },
         "payer":"receiver"
      }
   },
   "storePayer":"third",
   "members":{
      "requester":{
         "role":"sender"
      },
      "receiver":{
         "counteragentID":456783515,
         "counteragent":{
            "form":"0x8F51001438C4D49511DBD774581EDB80",
            "name":"Ромашка",
            "document":{
               "type":"passport",
               "serial":"0000",
               "number":"123456"
            },
            "inn":1234567890,
            "juridicalAddress":{
               "search":"Омск, Ленина, 5",
               "street":"5500000100005970000000000",
               "house":"5",
               "building":"1",
               "structure":"3А",
               "flat":"Б-234"
            }
         },
         "contactIDs":[
            12345678,
            78456123
         ],
         "contactPersons":[
            {
               "name":"Иван Иванович"
            },
            {
               "name":"Петр Петрович"
            }
         ],
         "phoneIDs":[
            98765412,
            65478921
         ],
         "phoneNumbers":[
            {
               "number":"79213332211",
               "ext":"0123"
            }
         ],
         "email":"testSender@mail.ru",
         "dataForReceipt":{
            "send":true,
            "phone":"+79999999999",
            "email":"test@mail.ru"
         }
      },
      "third":{
         "counteragentID":456783515,
         "counteragent":{
            "form":"0x8F51001438C4D49511DBD774581EDB80",
            "name":"Ромашка",
            "document":{
               "type":"passport",
               "serial":"0000",
               "number":"123456"
            },
            "inn":1234567890,
            "juridicalAddress":{
               "search":"Омск, Ленина, 5",
               "street":"5500000100005970000000000",
               "house":"5",
               "building":"1",
               "structure":"3А",
               "flat":"Б-234"
            }
         },
         "contactIDs":[
            12345678,
            78456123
         ],
         "contactPersons":[
            {
               "name":"Иван Иванович"
            },
            {
               "name":"Петр Петрович"
            }
         ],
         "phoneIDs":[
            98765412,
            65478921
         ],
         "phoneNumbers":[
            {
               "number":"79213332211",
               "ext":"0123"
            }
         ],
         "email":"testSender@mail.ru",
         "dataForReceipt":{
            "send":true,
            "phone":"+79999999999",
            "email":"test@mail.ru"
         }
      },
      "storeThird":{
         "counteragentID":456783515,
         "counteragent":{
            "form":"0x8F51001438C4D49511DBD774581EDB80",
            "name":"Ромашка",
            "document":{
               "type":"passport",
               "serial":"0000",
               "number":"123456"
            },
            "inn":1234567890,
            "juridicalAddress":{
               "search":"Омск, Ленина, 5",
               "street":"5500000100005970000000000",
               "house":"5",
               "building":"1",
               "structure":"3А",
               "flat":"Б-234"
            }
         },
         "contactIDs":[
            12345678,
            78456123
         ],
         "contactPersons":[
            {
               "name":"Иван Иванович"
            },
            {
               "name":"Петр Петрович"
            }
         ],
         "phoneIDs":[
            98765412,
            65478921
         ],
         "phoneNumbers":[
            {
               "number":"79213332211",
               "ext":"0123"
            }
         ],
         "email":"testSender@mail.ru",
         "dataForReceipt":{
            "send":true,
            "phone":"+79999999999",
            "email":"test@mail.ru"
         }
      }
   }
}

Адрес метода: https://api.dellin.ru/v3/orders/change_delivery.xml

<request>
   <appkey>00000000-0000-0000-0000-000000000000</appkey>
   <sessionID>00000000-0000-0000-0000-000000000000</sessionID>
   <orderID>00000000</orderID>
   <delivery>
      <arrival>
         <produceDate>2020-04-10</produceDate>
         <variant>terminal</variant>
         <terminalID>123</terminalID>
         <addressID>457824578</addressID>
         <address>
            <search>Омск, Ленина, 5</search>
            <street>5500000100005970000000000</street>
            <house>5</house>
            <building>1</building>
            <structure>3А</structure>
            <flat>Б-234</flat>
         </address>
         <city>5500000100000000000000000</city>
         <time>
            <worktimeStart>09:00</worktimeStart>
            <worktimeEnd>18:00</worktimeEnd>
            <breakStart>12:30</breakStart>
            <breakEnd>13:30</breakEnd>
            <exactTime>true</exactTime>
         </time>
         <payer>receiver</payer>
      </arrival>
   </delivery>
   <storePayer>third</storePayer>
   <members>
      <requester>
         <role>sender</role>
      </requester>
      <receiver>
         <counteragentID>456783515</counteragentID>
         <counteragent>
            <form>0x8F51001438C4D49511DBD774581EDB80</form>
            <name>Ромашка</name>
            <document>
               <type>passport</type>
               <serial>0000</serial>
               <number>123456</number>
            </document>
            <inn>1234567890</inn>
            <juridicalAddress>
               <search>Омск, Ленина, 5</search>
               <street>5500000100005970000000000</street>
               <house>5</house>
               <building>1</building>
               <structure>3А</structure>
               <flat>Б-234</flat>
            </juridicalAddress>
         </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>testSender@mail.ru</email>
         <dataForReceipt>
            <send>true</send>
            <phone>+79999999999</phone>
            <email>test@mail.ru</email>
         </dataForReceipt>
      </receiver>
      <third>
         <counteragentID>456783515</counteragentID>
         <counteragent>
            <form>0x8F51001438C4D49511DBD774581EDB80</form>
            <name>Ромашка</name>
            <document>
               <type>passport</type>
               <serial>0000</serial>
               <number>123456</number>
            </document>
            <inn>1234567890</inn>
            <juridicalAddress>
               <search>Омск, Ленина, 5</search>
               <street>5500000100005970000000000</street>
               <house>5</house>
               <building>1</building>
               <structure>3А</structure>
               <flat>Б-234</flat>
            </juridicalAddress>
         </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>testSender@mail.ru</email>
         <dataForReceipt>
            <send>true</send>
            <phone>+79999999999</phone>
            <email>test@mail.ru</email>
         </dataForReceipt>
      </third>
      <storeThird>
         <counteragentID>456783515</counteragentID>
         <counteragent>
            <form>0x8F51001438C4D49511DBD774581EDB80</form>
            <name>Ромашка</name>
            <document>
               <type>passport</type>
               <serial>0000</serial>
               <number>123456</number>
            </document>
            <inn>1234567890</inn>
            <juridicalAddress>
               <search>Омск, Ленина, 5</search>
               <street>5500000100005970000000000</street>
               <house>5</house>
               <building>1</building>
               <structure>3А</structure>
               <flat>Б-234</flat>
            </juridicalAddress>
         </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>testSender@mail.ru</email>
         <dataForReceipt>
            <send>true</send>
            <phone>+79999999999</phone>
            <email>test@mail.ru</email>
         </dataForReceipt>
      </storeThird>
   </members>
</request>

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

Request
Request
ПараметрОбязательныйТипОписание

appkey

ДаstringКлюч приложения. Для получения ключа необходимо пройти регистрацию

sessionID

ДаstringID сессии. Для получения сессии необходимо воспользоваться сервисом "Авторизация пользователя"

orderID

Даstring

Номер заказа, в который необходимо внести изменения

deliveryДаobjectПараметры доставки
delivery.arrivalДаArrivalДоставка до адреса
storePayerНет*string

Сторона, берущая на себя расходы на платное хранение.

Возможные значения:

  • "sender" - отправитель;
  • "receiver" - получатель;
  • "payer" - третье лицо, указанное в качестве плательщика при оформлении заказа;
  • "third" - третье лицо. В случае передачи данного значения, параметр "members.storeThird" является обязательным
*Параметр может быть передан, только если инициатором внесения изменений в заявку является отправитель, и в этом случае параметр является обязательным
membersДаobjectУчастники перевозки
members.requesterДаRequesterИнициатор внесения изменений в заявку
members.receiverНетMember

Новый получатель. Если получатель остаётся прежним, то параметр в запросе передавать не следует

Если инициатором внесения изменений в заказ является изначальный получатель по заказу (то есть значение параметра "members.requester.role" - "receiver"), то изменить получателя нельзя
members.thirdНет*Member

Новый плательщик за услугу доставки/перенаправление груза. Если плательщик остаётся прежним, то параметр в запросе передавать не следует 

*Параметр является обязательным, если новым плательщиком за услугу доставки является третье лицо, то есть значение параметра "delivery.arrival.payer" - "third"
members.storeThirdНет*Member

Третье лицо, берущее на себя расходы на платное хранение

*Параметр является обязательным, если расходы за платное хранение берёт на себя третье лицо (то есть значение параметра "storePayer" - "sender")

Arrival
Arrival
ПараметрОбязательныйТипОписание

produceDate

Нет*string

Дата приезда водителя-экспедитора к получателю.

Формат: ГГГГ-ММ-ДД

*Обязательно должен быть передан хотя бы один из параметров: "produceDate", "time", "variant"

variant

Нет*string

Способ доставки груза.

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

  • "terminal" - доставка груза до терминала.
  • "address" - доставка груза до адреса
*Если требуется указать новый терминал/адрес доставки, то параметр является обязательным. Должен быть обязательно передан хотя бы один из параметров: "produceDate", "time", "variant"

terminalID

Нет*integer

ID терминала из "Справочника терминалов". 

Может быть передан только ID пункта выдачи заказов (ПВЗ) или терминала по умолчанию (в "Справочника терминалов" значение параметра "city.terminals.terminal.isPVZ" или параметра "city.terminals.terminal.default" - "true").

При доставке до адреса (значение параметра запроса "variant" - "address") передача параметра невозможна

*Если передан параметр "variant", то обязательно должен быть передан один из взаимоисключающих параметров: "terminalID", "addressID", "address", "city"
addressIDНет*integer

ID адреса из "Адресной книги"

*Если передан параметр "variant", то обязательно должен быть передан один из взаимоисключающих параметров: "terminalID", "addressID", "address", "city"
addressНет*Address

Адрес

*Если передан параметр "variant", то обязательно должен быть передан один из взаимоисключающих параметров: "terminalID", "addressID", "address", "city"
cityНет*string

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

При доставке до адреса (значение параметра запроса "variant" - "address") передача параметра невозможна

*Если передан параметр "variant", то обязательно должен быть передан один из взаимоисключающих параметров: "terminalID", "addressID", "address", "city"
timeНет*object

Время доставки груза

*Обязательно должен быть передан хотя бы один из параметров: "produceDate", "time", "variant"
time.worktimeStartДаstring

Начало периода.

Формат: ЧЧ:ММ

time.worktimeEndДаstring

Окончание периода.

Формат: ЧЧ:ММ

time.breakStartНетstring

Начало перерыва.

Формат: ЧЧ:ММ

time.breakEndНетstring

Окончание перерыва.

Формат: ЧЧ:ММ

time.exactTimeНетboolean

Передача груза в точное время.

Значение по умолчанию: "false"

payerНетstring

Плательщик за услугу доставки/перенаправление груза.

Возможные значения:

  • "sender" - отправитель;
  • "receiver" - получатель;
  • "payer" - третье лицо, указанное в качестве плательщика при оформлении заказа;
  • "third" - новое третье лицо. В случае передачи данного значения, параметр "members.third" является обязательным
Параметр может быть передан, только если инициатором внесения изменений в заявку является отправитель

Address
Address
ПараметрОбязательныйТипОписание

search

Нет (1)string

Адрес в виде текста или координат.

Координаты не следует использовать для передачи информации о юридическом адресе, то есть в блоках "juridicalAddress" класса "Counteragent".

При передаче адреса в виде текста, помимо собственно адреса, в запрос следует включать наименование населённого пункта, элементы необходимо указывать через запятую, например "Омск, Ленина, 5".

Координаты также указываются через запятую, первое число - широта, например "59.924501, 30.241762".

Максимум - 1024 знака (2)

streetНет (1)string

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

houseНет (1)string

Номер дома (2).

Максимальная длина поля: 7 символов

buildingНетstring

Корпус (2).

Максимальная длина поля: 5 символов

structureНетstring

Строение (2).

Максимальная длина поля: 7 символов

flatНетstring

Квартира (2).

Максимальная длина поля: 5 символов

Примечания:

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

Requester
Requester
ПараметрОбязательныйТипОписание

role

Даstring

Роль инициатора изменений в перевозке.

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

  • "sender" - отправитель;
  • "receiver" - получатель;
  • "customer" - третье лицо, указанное в качестве плательщика при оформлении заказа

Member
Member
ПараметрОбязательныйТипОписание
counteragentIDНет*integer

ID контрагента из "Адресной книги"

*Передача одного из взаимоисключающих параметров "counteragentID" или "counteragent" является обязательной
counteragentНет*Counteragent

Контрагент в форме набора параметров

*Передача одного из взаимоисключающих параметров "counteragentID" или "counteragent" является обязательной
contactIDsНет*array of integers

Список ID контактных лиц из "Адресной книги".

Максимальное количество элементов в массиве - 3

*Передача одного из взаимоисключающих параметров "contactID" или "contactPersons" является обязательной
contactPersonsНет*array of ContactPersons

Список контактных лиц.

Максимальное количество элементов в массиве - 3

*Передача одного из взаимоисключающих параметров "contactID" или "contactPersons" является обязательной
contactPersons.nameДаstringИмя контактного лица
phoneIDsНет*array of integers

Список ID телефонных номеров из "Адресной книги".

Максимальное количество элементов в массиве - 3 

*Передача одного из взаимоисключающих параметров "phoneIDs" или "phoneNumbers" является обязательной
phoneNumbersНет*array of PhoneNumbers

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

Максимальное количество элементов в массиве - 3

*Передача одного из взаимоисключающих параметров "phoneIDs" или "phoneNumbers" является обязательной
phoneNumbers.numberДаstring

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

Допускаются цифры и знак "+" в начале строк, начинающихся с 7 или 375

phoneNumbers.extНетstring

Добавочный номер.

Максимальная длина поля: 5 цифр

emailНетstring

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

dataForReceiptНет*object

Контактные данные для отправки электронного чека плательщику-физическому лицу

*Параметр обязателен для контрагента-физического лица. Для контрагента-юридического лица параметр не является обязательным и игнорируется
dataForReceipt.sendДаboolean

Согласие на получение электронного чека об оплате. Доступные значения:

  • "true" - пользователь ввел "phone" и/или "email" для отправки чека;
  • "false" - пользователь отказался предоставлять контактные данные для отправки чека
dataForReceipt.phoneНет*string

Номер телефона для отправки чека.

Формат номера: "+79XXXXXXXXX" (12 символов: начинается с "+79", и далее 9 цифр)

*Если значение параметра "dataForReceipt.send" - "true", то обязательна передача хотя бы одного из параметров: "dataForReceipt.phone" или "dataForReceipt.email". Если "dataForReceipt.send" - "false", то параметр игнорируется
dataForReceipt.emailНет*string

Email адрес для отправки чека

*Если значение параметра "dataForReceipt.send" - "true", то обязательна передача хотя бы одного из параметров: "dataForReceipt.phone" или "dataForReceipt.email". Если "dataForReceipt.send" - "false", то параметр игнорируется

Counteragent
Counteragent
ПараметрОбязательныйТипОписание
formДаstring

UID организационно-правовой формы (ОПФ), см. "Поиск ОПФ"

nameДаstringНаименование юридического лица или имя физического лица
documentНет*object

Данные документа, удостоверяющего личность

*Если контрагент является физическим лицом (в качестве значения параметра "form" передан UID ОПФ физического лица), то параметр является обязательным. Если контрагент является юридическим лицом, то параметр не используется
document.typeДаstring

Тип документа.

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

  • "passport" - паспорт;
  • "drivingLicence" - водительское удостоверение;
  • "foreignPassport" - заграничный паспорт.

Для некоторых стран значение "foreignPassport" недоступно

document.serialДа*string

Серия документа.

*Для некоторых стран параметр не является обязательным и игнорируется

document.numberДаstring

Номер документа.

Формат номера зависит от страны

innНет*string

ИНН.

Максимальная длина поля зависит от страны и ОПФ

*Если контрагент является юридическим лицом (в качестве значения параметра "form" передан UID ОПФ юридического лица), то параметр является обязательным. Если контрагент является физическим лицом, то параметр не используется
juridicalAddressНетAddress

Юридический адрес.

Параметр используется только для юридических лиц (в качестве значения параметра "form" передан UID ОПФ юридического лица)

Ответ метода

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

{
   "metadata":{
      "status":200,
      "generated_at":"2019-11-18 12:52:26"
   },
   "data":{
      "state":"success",
      "information": [
         "Смена адреса и времени доставки груза будет бесплатной при подаче запроса до 17:00 (по местному времени)."
      ],
      "foundAddresses": [
         {
            "field": "delivery.arrival.address",
            "source": "Омск, Ленина, 5",
            "result": "Россия, Омская обл, г Омск, ул Ленина, д 5"
         },
         {
            "field": "members.receiver.counteragent.juridicalAddress",
            "source": "Омск, Ленина, 5",
            "result": "Россия, Омская обл, г Омск, ул Ленина, д 5"
         },
         {
            "field": "members.third.counteragent.juridicalAddress",
            "source": "Омск, Ленина, 5",
            "result": "Россия, Омская обл, г Омск, ул Ленина, д 5"
         },
         {
            "field": "members.storeThird.counteragent.juridicalAddress",
            "source": "Омск, Ленина, 5",
            "result": "Россия, Омская обл, г Омск, ул Ленина, д 5"
         }
      ]
   }
}
<response>
   <metadata>
      <status>200</status>
      <generated_at>2019-11-18 12:52:26</generated_at>
   </metadata>
   <data>
      <state>success</state>
      <information>Смена адреса и времени доставки груза будет бесплатной при подаче запроса до 17:00 (по местному времени).</information>
      <foundAddresses>
         <field>delivery.arrival.address</field>
         <source>Омск, Ленина, 5</source>
         <result>Россия, Омская обл, г Омск, ул Ленина, д 5</result>
      </foundAddresses>
      <foundAddresses>
         <field>members.receiver.counteragent.juridicalAddress</field>
         <source>Омск, Ленина, 5</source>
         <result>Россия, Омская обл, г Омск, ул Ленина, д 5</result>
      </foundAddresses>
      <foundAddresses>
         <field>members.third.counteragent.juridicalAddress</field>
         <source>Омск, Ленина, 5</source>
         <result>Россия, Омская обл, г Омск, ул Ленина, д 5</result>
      </foundAddresses>
      <foundAddresses>
         <field>members.storeThird.counteragent.juridicalAddress</field>
         <source>Омск, Ленина, 5</source>
         <result>Россия, Омская обл, г Омск, ул Ленина, д 5</result>
      </foundAddresses>
   </data>
</response>

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

Response
Response
ПараметрТипОписание
metadataobjectСистемная информация
metadata.statusinteger

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

metadata.generated_atstring

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

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

dataobjectПодтверждение успешности операции
data.statestring

Статус операции на английском языке. Возможное значение - "success"

Статус "success" означает, что заявка на внесение изменений была принята. После дополнительной проверки заявка может быть одобрена или отклонена. Проверить статус заявки можно при помощи метода "История изменений заказа" 
data.informationarray of stringsИнформация об условиях бесплатного изменения адреса и времени доставки или предупреждение о том, что внесение изменений в заявку может повлечь дополнительные расходы
data.foundAddressesarray of FoundAddressesДанные по найденным адресам. Параметр присутствует в ответе, только если в запросе был передан параметр "search" класса "Address"

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

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

resultstring

Найденный адрес

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

Помимо общих ошибок API, в ответе метода могут присутствовать следующие ошибки:

Номер ошибки

http-код

Краткое описание ошибки

Детальное описание ошибки

622001

400

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

-

622002

400По данному заказу изменение адреса и времени недоступноИзменение по данному заказу недоступно в связи с отсутствием доступа

622003

400Указанная роль заказчика для данного заказа недоступна-

622004

400Нет доступа к контрагенту заказа-

622005

400Невозможно оформить доставку до терминала-

622006

400Невозможно оформить доставку до адреса-

622007

400По данному заказу изменение получателя недоступно-

622008

400По данному заказу изменение плательщика недоступно-

622014

400Ошибка наложенного платежаПолучателем в заказе с наложенным платежом может быть только физическое лицо