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

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

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

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

• добавлять, обновлять, редактировать и удалять общедоступные грузы и грузы на Площадках;
• настраивать приоритетный показ груза;
• получать встречные предложения по грузу.

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

• узнавать о грузах компаний на Площадках (кроме Общей площадки ATI.SU);
• добавлять и редактировать встречные предложения;
• добавлять и редактировать комментарии к грузу.

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

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

Дубликаты

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

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хх ошибок