API раздела «Ваши машины»
API позволяет управлять вашими машинами — добавлять, изменять и удалять их.
Терминология
Машина — объявление о свободном транспорте. Содержит в себе информацию о машине, датах, в которые машина свободна, направлениях перевозки и комфортной ставке.
Ваши машины — раздел на сайте ATI.SU, в котором пользователь может добавлять, удалять и редактировать машины.
Архив ваших машин — информация об удаленной машине помещается в архив. Объявление из архива можно восстановить.
Приоритетный показ — услуга, закрепляющая объявление вверху поиска машин. Cтатья про приоритетный показ.
Атисы — валюта виртуального счета в ATI.SU. 1 атис равен 1 российскому рублю. Используется для приоритетного показа и других услуг. Статья про атисы.
Комментарий к машине — дополнительная информация, которая может быть добавлена к машине сотрудниками вашей фирмы. Видна только сотрудникам вашей фирмы.
Пользовательские ошибки в API машин
В API машин может произойти достаточно много пользовательских ошибок, и для идентификации конкретной ошибки не всегда достаточно http кода ошибки. Поэтому при возникновении ошибки в теле ответа всегда будет присутствовать объект ошибки, содержащий 2 поля: error с кодом ошибки в виде строки и reason с пояснением. В групповых операциях поля error и reason будут указаны для каждой машины, с которой произошла ошибка во время выполнения операции.
Примеры ошибок
Ошибка при одиночной операции (на примере добавления машины)
Ошибка при одиночной операции (не обновилась машина, так как уже была обновлена менее 60 минут назад).
{
"error": "truck_duplicate",
"reason": "Машина имеет дубликат в системе. Операция невозможна.",
"duplicate_truck_id": "2fb37893-3587-eb11-bb9f-0cc47af30c1b"
}
Ошибка при групповой операции (на примере группового обновления)
{
"2fb37893-3587-eb11-bb9f-0cc47af30c1b": {
"error": "truck_renew_delay_not_elapsed_error",
"reason": "Машина была обновлена менее 60 минут назад. Следующее обновление возможно через 57 минут.",
"remaining_minutes": 57
},
"89d8e0db-3587-eb11-bb9f-0cc47af30c1b": {
"error": "truck_renew_delay_not_elapsed_error",
"reason": "Машина была обновлена менее 60 минут назад. Следующее обновление возможно через 59 минут.",
"remaining_minutes": 59
}
}
Ошибка валидации (на примере добавления машины)
В случае ошибки валидации json в теле запроса возникает ошибка json_validation_error. В теле ответа будут поля error и reason, и, кроме того, поле error_list, содержащее массив объектов вида {property;reason}, где:
property – название поля, в котором произошла ошибка;
reason – причина ошибки.
{
"error": "json_validation_error",
"reason": "Одна или несколько машин не прошли проверку. Отредактируйте машину, чтобы исправить ошибки.",
"details": [
{
"property": "priority.view_rate",
"reason": "Параметр \"Ставка за просмотр\" должен должен принимать значения от 0.60 атисов до значения вашего баланса включительно"
},
{
"property": "first_date",
"reason": "Если значение параметра date_type равно 1, допустимое значение параметра first_date - от текущей даты до 60 дней вперед"
}
]
}
Ошибка доступа (на примере добавления машины)
{
"error": "contact_access_denied_error",
"reason": "У данного контакта имеются ограничения на данную операцию"
}
Список возможных 4хх ошибок
| Код ошибки | Пояснение |
|---|---|
| deserialization_error | Ошибка десериализации json |
| json_validation_error | Ошибка валидации json из тела запроса |
| validation_error | Ошибка валидации. Возникает в случае любой ошибки валидации, кроме ошибки валидации тела запроса (json_validation_error) |
| contact_access_denied_error | Отказано в доступе |
| truck_renew_delay_not_elapsed_error | Машина была обновлена менее 60 минут назад |
| dictionary_element_not_found_error | Элемент словаря не найден |
| truck_not_found_error | Машина не найдена |
Список методов
Работа с машинами
- Получение одной машины
- Получение всех машин
- Получение машин контакта
- Получение количества машин
- Получение доступа на добавление машины
- Добавление машины
- Обновление машины
- Редактирование машины
- Удаление машины
Работа с архивом ваших машин
- Получение одной архивной машины
- Получение всех архивных машин
- Получение архивных машин для определенного контакта
- Восстановление архивной машины
- Удаление машины из архива
Групповые методы
- Групповое обновление машин (POST)
- Групповое обновление машин (PUT)
- Групповое удаление машин
- Групповое удаление машин из архива
Работа с комментариями к машинам
- Получение комментариев ко всем машинам
- Получение комментариев к машине
- Добавление/редактирование комментария к машине (POST)
- Добавление/редактирование комментария к машине (PUT)
- Удаление комментария к машине (DELETE)
- Удаление комментария к машине (POST)
- Получение комментариев к архивной машине
- Получение комментариев ко всем архивным машинам
- Добавление/редактирование комментария к архивной машине (POST)
- Добавление/редактирование комментария к архивной машине (PUT)
- Удаление комментария к архивной машине (DELETE)
- Удаление комментария к архивной машине (POST)
Работа с приоритетным показом
- Изменение приоритетного показа в актуальной машине
- Удаление приоритетного показа в актуальной машине
API отзывов на машины
API позволяет оставить встречное предложение или жалобу на машину, а также запросить все встречные предложения и отзывы на ваши машины.
Терминология
Машина — объявление о свободном транспорте. Содержит в себе информацию о машине, датах, в которые машина свободна, направлениях перевозки и комфортной ставке.
Ваши машины — раздел на сайте ATI.SU, в котором пользователь может добавлять, удалять и редактировать машины.
Встречное предложение — предложение перевезти груз.
Жалоба — жалоба на объявление о машине. Пользователь может оставить жалобу, если информация в объявлении нарушает правила сайта ATI.SU, либо содержит устаревшие или ложные сведения.
Машины нет — этот тип жалобы используется, если машина, о которой идет речь в объявлении, недоступна.