Помощь
Чат для вопросов по API
Мгновенно ответим на ваши вопросы
api@ati.su
Электронная почта техподдержки
Тикетная система
Оставить заявку на отдел
«Консультанты по интеграции (API)»
api.ati.su - заказы, торги, площадки
Наш телеграм-канал
Код в АТИ:
Выход

API для работы с Грузами

Возможности API

API Грузов позволяет работам с Грузами. С помощью API:

Грузовладелец может:

Перевозчик может:

Дубликаты и объединение грузов

При добавлении или редактировании груза могут происходить конфликты, если в системе уже имеются похожие грузы.

Дубликаты

У грузов совпадают все перечисленные параметры:

  1. Одинаковые параметры CargoTypeId;
  2. Одинаковые или отсутствующие параметры Weight, Volume, ADR;
  3. Одинаковый или отсутствующий параметр PackType или различие у грузов только в то, что у load1= значение из словаря, у load2=0;
  4. Одинаковые или отсутствующие параметра PalletCount, BeltCount или различие у грузов только в том, что у load1>0, у load2=0;
  5. Одинаковые или отсутствующие параметры структуры Size;
  6. Одинаковый параметр DogruzType;
  7. Одинаковый или отсутствующий параметр SborGruz или различие только в этом параметре;
  8. Одинаковые параметры Loading.CityId, Unloading.CityId;
  9. Одинаковые параметры Loading.Street и Unloading.Street;
  10. Любые списки дополнительных пунктов маршрута ExtraPoints;
  11. Любое значение параметра Krugoreis;
  12. Одинаковые или отсутствующие параметры Transport.CarType, LoadingType, UnloadingType или различие у грузов только в том, что значение load1>load2;
  13. Одинаковые или отсутствующие параметры Stsepka, Pnevmohod, Koniki, TIR, CMR, T1, SanPassport или различие у грузов только в том, что значение у load1=true, у load2=false;
  14. Любой параметр TrucksQuantity;
  15. Одинаковые параметры DateType, а так же если совпадает FirstDate при разных значениях DateType;
  16. Одинаковые или отсутствующие параметры TimeStart, TimeEnd, или различие у грузов только в то, что значение load1>load2;
  17. Одинаковый или отсутствующий параметр Note;
  18. Одинаковые параметры ставки Payment.RateSum, Payment.SumWithNDS, Payment.SumWithoutNDS и Payment.CurrencyID. Если различие у грузов только в значении перечисленных полей, груз будет дубликатом;
  19. Одинаковые параметры оплаты Torg, PrepayPercentEnabled, InFuel, DirectContract, OnUnloading, PayDaysEnabled или различие у грузов только в то, что значение у load1=true, у load2= false;
  20. Любой параметр AcceptPaymentTypes в параметре “Запрос ставки”;
  21. Любой параметр структуры LoadFile и любой параметр OrderNumber.

Под любым параметром понимается, что изменение только этого параметра приведет к дубликату груза. Например:

  • load1 и load2 отличаются только тем, что у груза load2 нет сцепки - ошибка дубликата груза
  • load1 и load2 отличаются только размером ставки - ошибка дубликата груза
  • load1 и load2 отличаются размером ставки и городом загрузки - добавится новый груз
  • load1 и load2 отличаются только городом загрузки - добавится новый груз

Если груз оказался дубликатом, то новый груз не добавится и будет отправлена ошибка 409 Conflict.

{
    "Error": "load_conflict_error",
    "Reason": "Найден дубликат в грузах",
    "ConflictLoadId": "e87584af-1bed-457b-9ee3-a595b715c550"
}

Объединение

Объединение происходит, если в системе уже имеется груз load1, который отличается от load2, одним или несколькими из перечисленных параметров:

  1. Параметр PackType у load1 = 0, у load2 = значение из словаря;
  2. Параметры PalletCount, BeltCount у load1 ≥ 0, у load2 > 0;
  3. Параметры Transport.CarType, LoadingType, UnloadingType load1 < load2;
  4. Параметры Stsepka, Pnevmohod, Koniki, TIR, CMR, T1, SanPassport у load1 = false, у load2 = true;
  5. Параметры TimeStart, TimeEnd load1 < load2;
  6. Параметры Torg, PrepayPercentEnabled, InFuel, DirectContract, OnUnloading, PayDaysEnabled у load1 = false, у load2 = true.

Эффект при объединении

Новый груз не добавляется, а редактируется уже имеющийся. Например, уже имеющийся груз получает CarType от обоих грузов.

После объединения грузов будет отправлено сообщение с кодом ответа сервера 202, содержащее json с обновленным грузом.

Пользовательские ошибки в API грузов

В API грузов может произойти достаточно много пользовательских ошибок, и для идентификации конкретной ошибки не всегда достаточно http кода ошибки. Поэтому при возникновении ошибки в теле ответа всегда будет присутствовать объект ошибки, содержащий 2 поля: Error с кодом ошибки в виде строки и 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 Невозможно зарезервировать груз. Груз уже зарезервирован, либо не поддерживает резервирование