Изменение адреса и времени доставки
Общие сведения
Сервис позволяет изменить терминал доставки (
Бесплатное внесение изменений с помощью этого сервиса доступно, если заказ был оформлен в системах самообслуживания и по нему нет другого незавершенного запроса на изменение данных, при этом текущий статус заказа - один из следующих:
- "Груз принят к перевозке", "Груз принят к перевозке. Платное хранение", "Груз в пути", "Груз прибыл на терминал", "Груз прибыл на терминал. Платное хранение";
- "Доставка груза до адреса", при этом текущее местное время пункта доставки - до 17:00 последнего рабочего дня, предшествующего дню доставки.
Для внесения изменений необходим полный доступ к отправителю, получателю или плательщику, при этом перенаправление груза в другой город возможно только при наличии полного доступа к отправителю (подробнее о полном доступе см. в описании параметра ответа 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 | Да | string | ID сессии. Для получения сессии необходимо воспользоваться сервисом "Авторизация пользователя" |
orderID | Да | string | Номер заказа, в который необходимо внести изменения |
delivery | Да | object | Параметры доставки |
delivery.arrival | Да | Arrival | Доставка до адреса |
storePayer | Нет* | string | Сторона, берущая на себя расходы на платное хранение. Возможные значения:
*Параметр может быть передан, только если инициатором внесения изменений в заявку является отправитель, и в этом случае параметр является обязательным |
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 | Способ доставки груза. Доступные значения:
*Если требуется указать новый терминал/адрес доставки, то параметр является обязательным. Должен быть обязательно передан хотя бы один из параметров: "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 | Плательщик за услугу доставки/перенаправление груза. Возможные значения:
Параметр может быть передан, только если инициатором внесения изменений в заявку является отправитель |
Address
Address | |||
---|---|---|---|
Параметр | Обязательный | Тип | Описание |
search | Нет* | string | Адрес в виде текста или координат. Координаты не следует использовать для передачи информации о юридическом адресе, то есть в блоках "juridicalAddress" класса "Counteragent". При передаче адреса в виде текста в запрос следует включать:
Элементы необходимо указывать через запятую, например "Омская обл., Омск, Ленина, 5". При передаче адреса в виде координат они также указываются через запятую, первое число - широта, например "59.924501, 30.241762". Минимальная длина поля - 2 символа, максимальная - 1024 символа *Передача параметра "search" или пары параметров "street" и "house" является обязательной.Параметр "search" и набор параметров "street", "house", "building" и "structure" являются взаимоисключающими В случае возникновения ошибок разбора строки адреса рекомендуем воспользоваться методами подбора адресов |
street | Нет* | string | Код КЛАДР улицы (см. "Поиск КЛАДР") *Передача параметра "search" или пары параметров "street" и "house" является обязательнойПараметр "search" и набор параметров "street", "house", "building" и "structure" являются взаимоисключающими |
house | Нет* | string | Номер дома, включая литеру. Например, "13/А". Максимальная длина поля - 7 символов *Передача параметра "search" или пары параметров "street" и "house" является обязательнойПараметр "search" и набор параметров "street", "house", "building" и "structure" являются взаимоисключающими |
building | Нет | string | Корпус. Максимальная длина поля - 5 символов Параметр "search" и набор параметров "street", "house", "building" и "structure" являются взаимоисключающими |
structure | Нет | string | Строение. Максимальная длина поля - 7 символов Параметр "search" и набор параметров "street", "house", "building" и "structure" являются взаимоисключающими |
flat | Нет | string | Номер квартиры/офиса. Допускается написание с буквой, например "222 А". Максимальная длина поля - 5 символов *Если одновременно переданы параметры "search" и "flat", то в качестве номера квартиры/офиса будет использоваться значение параметра "flat" |
Requester
Requester | |||
---|---|---|---|
Параметр | Обязательный | Тип | Описание |
role | Да | string | Роль инициатора изменений в перевозке. Доступные значения:
|
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 цифр |
Нет | string | Email для отправки уведомлений участнику перевозки | |
dataForReceipt | Нет* | object | Контактные данные для отправки электронного чека плательщику-физическому лицу *Параметр обязателен для контрагента-физического лица. Для контрагента-юридического лица параметр не является обязательным и игнорируется |
dataForReceipt.send | Да | boolean | Согласие на получение электронного чека об оплате. Доступные значения:
|
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 | Тип документа. Доступные значения:
Для некоторых стран значение "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 | ||
---|---|---|
Параметр | Тип | Описание |
metadata | object | Системная информация |
metadata.status | integer | Эмуляция http-кода состояния. В случае успешного выполнения возвращается код "200". В случае ошибки - "400" |
metadata.generated_at | string | Дата и время генерации ответа сервера. Формат: "ГГГГ-ММ-ДД ЧЧ:ММ:СС" |
data | object | Подтверждение успешности операции |
data.state | string | Статус операции на английском языке. Возможное значение - "success" Статус "success" означает, что заявка на внесение изменений была принята. После дополнительной проверки заявка может быть одобрена или отклонена. Проверить статус заявки можно при помощи метода "История изменений заказа" |
data.information | array of strings | Информация об условиях бесплатного изменения адреса и времени доставки или предупреждение о том, что внесение изменений в заявку может повлечь дополнительные расходы |
data.foundAddresses | array of FoundAddresses | Данные по найденным адресам. Параметр присутствует в ответе, только если в запросе был передан параметр "search" класса "Address" |
FoundAddresses
FoundAddresses | ||
---|---|---|
Параметр | Тип | Описание |
field | string | Объект, в котором был передан параметр "search" |
source | string | Введённое значение |
result | string | Найденный адрес |
Обработка ошибок
Помимо общих ошибок API, в ответе метода могут присутствовать следующие ошибки:
Номер ошибки | http-код | Краткое описание ошибки | Детальное описание ошибки |
---|---|---|---|
622001 | 400 | По данному заказу изменение адреса и времени недоступно | - |
622002 | 400 | По данному заказу изменение адреса и времени недоступно | Изменение по данному заказу недоступно в связи с отсутствием доступа |
622003 | 400 | Указанная роль заказчика для данного заказа недоступна | - |
622004 | 400 | Нет доступа к контрагенту заказа | - |
622005 | 400 | Невозможно оформить доставку до терминала | - |
622006 | 400 | Невозможно оформить доставку до адреса | - |
622007 | 400 | По данному заказу изменение получателя недоступно | - |
622008 | 400 | По данному заказу изменение плательщика недоступно | - |
622014 | 400 | Ошибка наложенного платежа | Получателем в заказе с наложенным платежом может быть только физическое лицо |