запрос importPerformers
Запрос используется для импорта водителей (Performers) в систему. Для импорта водителей по API используется структура application/xml и HTTP-метод POST.
URL: [account-name].maxoptra.com/rest/2/distribution-api/objects/importPerformers
Список поддерживаемых атрибутов:
| № | Название поля | Тип | Длина | Обязательное | Примеры | Описание |
| 1 | performer | Блок информации о водителе | ||||
| 1.1 | externalId | Текст | 255 | Нет | Петр Уваров | Внешний идентификатор водителя. |
| 1.2 | login | Текст | 255 | Да | driver03 | Логин водителя для входа в систему. Логин должен быть уникальным для каждого водителя. |
| 1.3 | password | Текст | 255 | Да | 12345678 | Пароль пароль для входа в систему |
| 1.4 | name | Текст | 255 | Да | Петр Уваров | Имя водителя |
| 1.5 | Текст | 255 | Да | driver03@gmail.com | Адрес электронной почты водителя | |
| 1.6 | phone | Текст | 255 | Нет | +75554378200 | Номер телефона водителя |
| 1.7 | comments | Текст | 255 | Нет | Высокий, носит очки | Дополнительная информация о водителе |
| 1.8 | priceForOneHour | Число | 255 | Да | 100 | Стоимость одного часа работы |
| 1.9 | breakShift | Число | 255 | Да | 30 | Величина на которую обед может быть автоматически сдвинут при составлении маршрута. Данный параметр обязателен только если аккаунт настроен на работу со статическими обедами. |
| 1.10 | areaOfControl | Текст | 255 | Да | Ногинск | Наименование распределительного центра, которому принадлежит водитель |
| 1.11 | allowDailyDrivingLimit | Логический | true / false | Нет | Признак использования для данного водителя индивидуальных настроек максимально допустимой длительности вождения, возможные значения:
| |
| 1.12 | dailyDrivingLimit | Число | [1;4320] | Нет | 360 | Максимально допустимая длительность вождения в минутах |
| 1.13 | allowDailyWorkingLimit | Логический | true / false | Нет | Признак использования для данного водителя индивидуальных настроек максимально допустимой продолжительности работы, возможные значения:
| |
| 1.14 | dailyWorkingLimit | Число | [1;4320] | Нет | 720 | Максимально допустимая длительность рабочего дня за смену в минутах |
| 1.15 | scheduleZonesId | Число | 255 | Нет | Идентификатор территории планирования, которую может обслуживать данный водитель | |
| 2 | availability | Да | Блок информации о графике работы водителя | |||
| 2.1 | weekDay | Текст | 255 | Да | monday | День работы. Возможные значения: sunday, monday, tuesday, wednesday, thursday, friday, saturday |
| 2.2 | from | Время | [00:00;23:59] | Да | Время начала рабочего дня водителя: с ... часов | |
| 2.3 | to | Время | [00:00;23:59] | Да | Время окончания рабочего дня водителя: до ... часов | |
| 2.4 | startDayShift | Число | 255 | Нет | 08:00 | День начала рабочей смены относительно заданного в атрибуте “weekDay” дня недели. Возможные значения:
|
| 2.5 | endDayShift | Число | 255 | Нет | 20:00 | День окончания рабочей смены относительно заданного в атрибуте “weekDay” дня недели. Возможные значения:
|
| 2.6 | breakFrom | Число | [00:00;23:59] | Да* | 10:00 | Время начала обеда. Данный параметр обязателен только, если аккаунт настроен на работу со статическими обедами. Данный параметр обязателен, если заполнен параметр “breakTo”. Означает - Обед с ... |
| 2.7 | breakTo | Число | [00:00;23:59] | Да* | 10:45 | Время окончания обеда. Данный параметр обязателен только, если аккаунт настроен на работу со статическими обедами. Данный параметр обязателен, если заполнен параметр “breakFrom”. Означает - Обед до ... |
| 2.8 | fixedDayStart | [0;1] | Нет | Фиксированное начало рабочего дня | ||
| 3 | zone | Нет | Блок, в котором указывается территория, в которой может работать водитель (см.Территории / Группы территорий) Примечание Данный раздел не обязателен для включения в API запрос. НО если вы все-таки влкючили его в запрос, вы должны заполнить его ОБЯЗАТЕЛЬНО! | |||
| 3.1 | name | Текст | 255 | Нет | А | Название территории |
| 4 | startLocation | 255 | Нет | Блок информации об адресе начала рабочего дня. Если start location не используются, не заполнять данный блок. | ||
| 4.1 | address | Текст | 255 | Да | ул.Панфилова 42, Химки, Россия | Адрес начала рабочего дня. |
| 4.2 | latitude | Число | [-90;90] | Нет | 55.896023 | Долгота |
| 4.3 | longitude | Число | [-180;180] | Нет | 37.431775 | Широта |
| 4.4 | onlyWithDeliveries | Логический | true/false | Нет | False является эквивалентом значения Посетить перед первой Доставкой в форме водителя . False используется по умолчанию. | |
| 5 | homeLocation | Нет | Блок информации об адресе возврата в конце дня. Если home location не используются, не заполнять данный блок. | |||
| 5.1 | address | Текст | 255 | Да | ул.Панфилова 42, Химки, Россия | Адрес возврата в конце дня. |
| 5.2 | latitude | Число | [-90;90] | Нет | 55.896023 | Долгота |
| 5.3 | longitude | Число | [-180;180] | Нет | 37.431775 | Широта |
| 5.4 | onlyWithCollections | Логический | true/false | Нет | False является эквивалентом значения Посетить после последнего сбора в форме водителя . False используется по умолчанию. | |
| 5.5 | endDayOnLastOrder | Логический | true/false | Нет | Используется, если маршрут заканчивается на последнем заказе. False используется по умолчанию. Если не указан адрес возврата в конце дня (address), маршрут закончится в распределительном центре (areaOfControl). |
Метод importPerformers ищет по логину водителя. Если логин найден, то содержание всех полей обновляется. Если нет, то в системе создается новый водитель.
Значение полей dailyDrivingLimit и dailyDrivingLimit имеют смысл только при наличии включенных полей allowDailyDrivingLimit и allowDailyWorkingLimit соответственно
Пример (перечислены все доступные поля):
<?xml version="1.0" encoding="UTF-8"?>
<apiRequest>
<sessionID>6345e0588e384fc4acc3a2e63e9a4d39</sessionID>
<performersDetails>
<units />
<performers>
<performer name="Водитель Иванов" phone="555-437-82" email="ivanov_magenta_voditel@gmail.com" login="Driver_API_3782387121" password="12345678" comments="Высокий, носит очки." priceForOneHour="10.5" breakShift="30" dailyDrivingLimit="720" allowDailyDrivingLimit="1" dailyWorkingLimit="720" allowDailyWorkingLimit="1" areaOfControl="chippenhamzone" scheduleZonesId="71" externalId="1234567890qwerty">
<startLocation address="10 Bishops Park Road, London, SW6 6DZ" latitude="" longitude="" onlyWithDeliveries="false" />
<homeLocation address="Drake Crescent, Chippenham, Wiltshire, SN14, GB" latitude="51.453891" longitude="-2.148895" onlyWithCollections="true"/>
<availabilities>
<availability weekDay="monday" from="05:00" to="19:00" breakFrom="10:00" endDayShift="0" breakTo="10:45" />
<availability weekDay="thursday" from="04:30" to="19:00" breakFrom="10:00" breakTo="10:45" />
<availability weekDay="friday" from="06:30" to="19:00" breakFrom="10:00" breakTo="10:45" />
<availability weekDay="saturday" from="05:00" to="19:00" breakFrom="10:00" breakTo="10:45" />
<availability weekDay="sunday" from="05:00" to="19:00" breakFrom="10:00" breakTo="10:45" />
</availabilities>
<zones>
<zone name="Center" />
</zones>
</performer>
</performers>
</performersDetails>
</apiRequest>
Ответ при успешном импорте:
<?xml version="1.0" encoding="UTF-8"?>
<apiResponse version="1.0">
<performers>
<performer>
<name>Водитель Иванов</name>
<login>Driver_API_3782387121</login>
</performer>
</performers>
</apiResponse>
Возможные ошибки:
| причина | ошибка |
1 | При указании некорректного sessionID | 1009 - "Provided credentials are invalid" |
2 | При отсутствии обязательного параметра | 1230 - "Parameter is required: %name%", name – имя отсуствующего параметра |
3 | При некорректном вводе email | 1232 - "Invalid value for e-mail: %wrongname%" |
4 | При вводе некорректных значений | 1107 - "Field type is incorrect: %name% = %valuename%. Expected %expectedtype% type" |
5 | При вводе несуществующего DC | 1203 - "Area Of Control was not found" |
6 | При запросе к DC, на которое у пользователя нет прав | 1019 - "User with provided credentials doesn't have AoC access or AoC doesn't exist" |
7 | При отсутствии одного из полей breakFrom или breakTo, когда одно из них задано | 1231 - "Invalid value for break, both values breakFrom and breakTo are required" |
8 | Пустое значение password при редактировании водителя | 1233 - "The value for password is empty" |
| 9 | Водитель и депо принадлежат разным территориям | 1217 - "Invalid value for scheduleZonesString" |
| 10 | В случае не корректного сочетания начальной и конечной точки маршрута | 1317 - "Invalid parameters in start\end point sections" |