API для работы с Грузами — описания методов API ATI.SU
Возможности API
API Грузов позволяет работам с Грузами. С помощью API:
Грузовладелец может:
- добавлять, обновлять, редактировать и удалять общедоступные грузы и грузы на Площадках;
- настраивать приоритетный показ груза;
- получать встречные предложения по грузу.
Перевозчик может:
- узнавать о грузах компаний на Площадках (кроме Общей площадки АТИ);
- добавлять и редактировать встречные предложения;
- добавлять и редактировать комментарии к грузу.
Дубликаты и объединение грузов
При добавлении или редактировании груза могут происходить конфликты, если в системе уже имеются похожие грузы.
Дубликаты
У грузов совпадают все перечисленные параметры:
- Одинаковые параметры CargoTypeId;
- Одинаковые или отсутствующие параметры Weight, Volume, ADR;
- Одинаковый или отсутствующий параметр PackType или различие у грузов только в то, что у load1= значение из словаря, у load2=0;
- Одинаковые или отсутствующие параметра PalletCount, BeltCount или различие у грузов только в том, что у load1>0, у load2=0;
- Одинаковые или отсутствующие параметры структуры Size;
- Одинаковый параметр DogruzType;
- Одинаковый или отсутствующий параметр SborGruz или различие только в этом параметре;
- Одинаковые параметры Loading.
CityId, Unloading.CityId; - Одинаковые параметры Loading.Street и Unloading.Street;
- Любые списки дополнительных пунктов маршрута ExtraPoints;
- Любое значение параметра Krugoreis;
- Одинаковые или отсутствующие параметры Transport.CarType, LoadingType, UnloadingType или различие у грузов только в том, что значение load1>load2;
- Одинаковые или отсутствующие параметры Stsepka, Pnevmohod, Koniki, TIR, CMR, T1, SanPassport или различие у грузов только в том, что значение у load1=true, у load2=false;
- Любой параметр TrucksQuantity;
- Одинаковые параметры DateType, а так же если совпадает FirstDate при разных значениях DateType;
- Одинаковые или отсутствующие параметры TimeStart, TimeEnd, или различие у грузов только в то, что значение load1>load2;
- Одинаковый или отсутствующий параметр Note;
- Одинаковые параметры ставки Payment.RateSum, Payment.SumWithNDS, Payment.SumWithoutNDS и Payment.CurrencyID. Если различие у грузов только в значении перечисленных полей, груз будет дубликатом;
- Одинаковые параметры оплаты Torg, PrepayPercentEnabled, InFuel, DirectContract, OnUnloading, PayDaysEnabled или различие у грузов только в то, что значение у load1=true, у load2= false;
- Любой параметр AcceptPaymentTypes в параметре “Запрос ставки”;
- Любой параметр структуры LoadFile и любой параметр OrderNumber.
CityId, Unloading.CityId;
Под любым параметром понимается, что изменение только этого параметра приведет к дубликату груза. Например:
- load1 и load2 отличаются только тем, что у груза load2 нет сцепки — ошибка дубликата груза
- load1 и load2 отличаются только размером ставки — ошибка дубликата груза
- load1 и load2 отличаются размером ставки и городом загрузки — добавится новый груз
- load1 и load2 отличаются только городом загрузки — добавится новый груз
Если груз оказался дубликатом, то новый груз не добавится и будет отправлена ошибка 409 Conflict.
{
"Error": "load_conflict_error",
"Reason": "Найден дубликат в грузах",
"ConflictLoadId": "e87584af-1bed-457b-9ee3-a595b715c550"
}
Объединение
Объединение происходит, если в системе уже имеется груз load1, который отличается от load2, одним или несколькими из перечисленных параметров:
- Параметр PackType у load1 = 0, у load2 = значение из словаря;
- Параметры PalletCount, BeltCount у load1 ≥ 0, у load2 > 0;
- Параметры Transport. CarType, LoadingType, UnloadingType load1 < load2;
- Параметры Stsepka, Pnevmohod, Koniki, TIR, CMR, T1, SanPassport у load1 = false, у load2 = true;
- Параметры TimeStart, TimeEnd load1 < load2;
- Параметры Torg, PrepayPercentEnabled, InFuel, DirectContract, OnUnloading, PayDaysEnabled у load1 = false, у load2 = true.
CarType, LoadingType, UnloadingType load1 < load2;Эффект при объединении
Новый груз не добавляется, а редактируется уже имеющийся. Например, уже имеющийся груз получает CarType от обоих грузов.
После объединения грузов будет отправлено сообщение с кодом ответа сервера 202, содержащее json с обновленным грузом.
Пользовательские ошибки в API грузов
В API грузов может произойти достаточно много пользовательских ошибок, и для идентификации конкретной ошибки не всегда достаточно http кода ошибки. Поэтому при возникновении ошибки в теле ответа всегда будет присутствовать объект ошибки, содержащий 2 поля: Reason с пояснением.
В групповых операциях поля Error и Reason будут указаны для каждого груза, с которым произошла ошибка во время выполнения операции.
Примеры ошибок
Ошибка при одиночной операции (на примере добавления груза)
{
"Error": "load_conflict_error",
"Reason": "Найден дубликат в грузах",
"ConflictLoadId": "271be1d2-2a91-e611-a37f-005056c00008"
}
Ошибка при групповой операции (на примере группового восстановления)
{
"0e9050e4-f5cb-4835-acb2-c211151bad64": {
"Status": 2,
"Message": "Груз был помещен в архив менее 60 минут назад",
"Error": "load_archive_delay_not_elapsed",
"Reason": "Груз был помещен в архив менее 60 минут назад"
},
"9b380991-433f-4738-a68d-8b851c1b5472": {
"Status": 0,
"Message": "Успешная операция"
}
}
Ошибка валидации(на примере добавления груза)
В случае ошибки валидации json в теле запроса возникает ошибка json_validation_error.
В теле ответа будут поля Error и Reason, и, кроме того, поле ErrorList, содержащее массив объектов вида {property;reason}, где:property – название поля, в котором произошла ошибка;reason – причина ошибки.
{
"Error": "json_validation_error",
"Reason": "Ошибка валидации json",
"ErrorsList": [
{
"property": "Cargo.Weight",
"reason": "Максимальная длина для параметра вес - 4 символа",
"error": "length_out_of_range",
"context": {
"Min": 0,
"Max": 4
}
},
{
"property": "FirstDate",
"reason": "Если значение параметра DateType равно 0 или 2, допустимое значение параметра FirstDate - текущая дата",
"error": "must_be_current_date"
},
{
"property": "LastDate",
"reason": "Параметр LastDate должен быть больше либо равен параметру FirstDate",
"error": "must_be_greater_or_equal_than",
"context": {
"Min": "2021-06-16T12:00:00. 51"
}
}
]
}
Ошибка доступа (на примере добавления груза)
{
"Error": "access_denied_error",
"Reason": "У вашего контакта нет доступа для работы с одной или несколькими персональными площадками, указанными в грузе",
"AccessDeniedReason": 13,
"ExceededLimit": null
}
Список возможных 4хх ошибок
| Код ошибки | Пояснение |
|---|---|
| deserialization_error | Ошибка десериализации json |
| json_validation_error | Ошибка валидации json из тела запроса |
| validation_error | Ошибка валидации. Возникает в случае любой ошибки валидации, кроме ошибки валидации тела запроса (json_validation_error) |
| load_conflict_error | Найден дубликат в грузах |
| load_archive_delay_not_elapsed | Груз был помещен в архив менее 60 минут назад |
| load_renew_delay_not_elapsed | Груз был обновлен менее 60 минут назад |
| boards_access_denied_error | Некоторые из указанных площадок не существуют или вы не имеете доступа к ним |
| access_denied_error | Отказано в доступе |
| account_not_found_error | Фирма не найдена |
| contact_not_found_or_deleted | Первый контакт не существует или удален |
| unavailable_contact_selected | В качестве первого контакта должен быть указан контакт из доступного подразделения |
| city_not_found_error | Город не найден |
| comment_not_found_error | Комментарий для груза не найден |
| dictionary_element_not_found_error | Элемент словаря не найден |
| load_not_found_error | Груз не найден |
| response_not_found_error | Отзыв на груз не найден |
| avatar_not_found_error | Аватар не найден |
| load_reserved_error | Груз зарезервирован/взят, операции с грузом запрещены |
| load_cant_reserve | Невозможно зарезервировать груз. Наверх
|