Изменение адреса и времени доставки
Общие сведения
Сервис позволяет изменить терминал доставки (
Изменение адреса или времени доставки
Запрос метода
Структура запроса
Адрес метода: 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 | Нет (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 символов |
Примечания:
|
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 | Ошибка наложенного платежа | Получателем в заказе с наложенным платежом может быть только физическое лицо |