⛽ Розрахунок витрат пального

Fuel Consumption API — універсальний сервіс розрахунку нормативної витрати ПММ для транспортних засобів за подорожнім листом. Розрахунок виконується згідно з методикою, що враховує лінійну норму, сезонні надбавки, умови експлуатації, вагу причепів, спецроботи та інші фактори.

API-ключ передається у заголовку кожного запиту:

X-API-Key: <YOUR_API_KEY>

API-ключ видається при реєстрації клієнта в особистому кабінеті.

Коди відповідей

Верхній рівень

Загальний множник надбавок

Середньозважена надбавка на умови роботи

Нерозподілений пробіг (поза завданнями) отримує надбавку з поля defaultWorkConditionSurcharge шапки ПЛ.

ТЗ зі спідометром (hasSpeedometer = true)

ТЗ без спідометра (hasSpeedometer = false)

Позначення змінних

Автоматичний температурний коефіцієнт

Якщо options.temperatureCoefficient не задано — визначається за таблицею (перший рядок де поріг > temperature):

Загальна витрата

Результат округлюється до кількості знаків, заданих у options.precision (за замовч. 3).

Верхній рівень

NormItem — Складова норми

Можливі значення code

Surcharges — Застосовані надбавки

Приклад 1: Вантажівка з причепом, зимовий період

МАЗ-5340, стандартний причіп 5500 кг, температура −12°C, 250 км пробігу, 1800 т·км транспортної роботи.

Запит

{
  "vehicle": {
    "id": "truck-001",
    "modelName": "МАЗ-5340",
    "hasSpeedometer": true,
    "vehicleSurcharge": 5
  },
  "fuel": { "id": "diesel", "name": "ДП" },
  "tripSheet": {
    "date": "2026-01-15",
    "temperature": -12,
    "heaterWorkTimeSeconds": 3600,
    "defaultWorkConditionSurcharge": 0,
    "performance": [
      { "vehicleId": "truck-001", "parameter": "totalMileage", "value": 250 },
      { "vehicleId": "truck-001", "parameter": "tonKm",        "value": 1800 },
      { "vehicleId": "truck-001", "parameter": "tripCount",    "value": 3 },
      { "vehicleId": "trailer-01","parameter": "totalMileage", "value": 250 }
    ],
    "tasks": [
      { "completed": true, "loadedKm": 120, "emptyKm": 80, "workConditionSurcharge": 10 },
      { "completed": true, "loadedKm": 30,  "emptyKm": 20, "workConditionSurcharge": 0 }
    ],
    "idlePeriods": [
      { "durationSeconds": 1800, "engineRunning": true }
    ]
  },
  "consumptionNorms": {
    "linearNorm": 22.0,
    "seasonalSurcharge": 10,
    "idleNormAsSpeed": 5,
    "weightChangeNorm": 1.3,
    "transportWorkNorm": 1.3,
    "heaterNorm": 2.5
  },
  "trailers": [
    { "id": "trailer-01", "isVehicle": true, "ownWeight": 5500, "hasFuelTank": false, "type": "standard" }
  ],
  "options": { "precision": 3, "isLpg": false }
}

Відповідь 200

{
  "totalConsumption": 127.905,
  "breakdown": [
    { "name": "На пробіг",                  "code": "mileage",       "value": 70.950 },
    { "name": "На простій з вкл. двигуном", "code": "idle",          "value": 1.210  },
    { "name": "На зміну власної ваги",      "code": "weightChange",  "value": 23.059 },
    { "name": "На транспортну роботу",      "code": "transportWork", "value": 30.186 },
    { "name": "На опалювач",                "code": "heater",        "value": 2.500  }
  ],
  "appliedSurcharges": {
    "seasonal": 10.0, "temperature": 6.0, "workCondition": 8.0,
    "vehicleSpecific": 5.0, "totalMultiplier": 1.29
  }
}

Приклад 2: Спецтехніка без спідометра (кран)

КС-3577, 8 годин роботи (28800 сек), 45 операцій, tripType=special, літо.

Запит

{
  "vehicle": {
    "id": "crane-005",
    "modelName": "КС-3577",
    "hasSpeedometer": false,
    "vehicleSurcharge": 0
  },
  "fuel": { "id": "diesel", "name": "ДП" },
  "tripSheet": {
    "date": "2026-07-10",
    "temperature": 28,
    "tripType": "special",
    "performance": [
      { "vehicleId": "crane-005", "parameter": "workTimeSeconds", "value": 28800 },
      { "vehicleId": "crane-005", "parameter": "operationCount",  "value": 45 }
    ]
  },
  "consumptionNorms": {
    "linearNorm": 14.0,
    "seasonalSurcharge": 0,
    "specialNormPerHour": 8.5,
    "operationNorm": 0.2
  },
  "options": { "precision": 3 }
}

Відповідь 200

{
  "totalConsumption": 77.000,
  "breakdown": [
    { "name": "На роботу спецобладнання", "code": "engineHours",  "value": 68.000 },
    { "name": "На операції",              "code": "operations",   "value": 9.000  }
  ],
  "appliedSurcharges": {
    "seasonal": 0, "temperature": 0, "workCondition": 0,
    "vehicleSpecific": 0, "totalMultiplier": 1.0
  }
}

Приклад 3: Авто з ГБО (газ + бензин)

ГАЗ-3302, двопаливний режим. Розрахунок витрати бензину (АІ-92) — лише норма на запуск двигуна, якщо залишку основного (газу) не вистачає.

Запит

{
  "vehicle": {
    "id": "car-010",
    "modelName": "ГАЗ-3302",
    "hasSpeedometer": true,
    "vehicleSurcharge": 0,
    "dualFuel": true,
    "lpgModel": {
      "primaryFuelId": "lpg",
      "primaryFuelRemaining": 30,
      "mainFuelRemaining": 5,
      "secondaryFuelRemaining": 12
    }
  },
  "fuel": { "id": "ai92", "name": "АІ-92" },
  "tripSheet": {
    "date": "2026-02-03",
    "temperature": -5,
    "performance": [
      { "vehicleId": "car-010", "parameter": "totalMileage", "value": 180 }
    ]
  },
  "consumptionNorms": {
    "linearNorm": 16.5,
    "seasonalSurcharge": 8,
    "startupNorm": 1.5
  },
  "options": { "precision": 3, "isLpg": true }
}

Відповідь 200

{
  "totalConsumption": 5.000,
  "breakdown": [
    { "name": "На запуск двигуна", "code": "startup", "value": 5.000 }
  ],
  "appliedSurcharges": {
    "seasonal": 8.0, "temperature": 3.0, "workCondition": 0,
    "vehicleSpecific": 0, "totalMultiplier": 1.11
  }
}

Формат помилки

{
  "error": {
    "code": "NORMS_NOT_FOUND",
    "message": "Лінійна норма витрат не задана для ТЗ truck-001, пальне ДП"
  }
}

Застосовується при isLpg = true та наявності vehicle.lpgModel. Основний пробіг завжди списується на газ (ГБО). На поточне паливо нараховується лише норма на запуск двигуна.

Крок 1. Розрахунок базової НормаНаЗапуск

Крок 2. Розподіл між видами пального

💡 Рекомендації щодо інтеграції

• Норми передаються у запиті — API не зберігає довідники. Це дозволяє інтегруватись із будь-якою обліковою системою: 1С, SAP, Oracle, власна БД.
• Температурний коефіцієнт визначається автоматично, якщо не переданий явно в options.temperatureCoefficient.
• Нульові складові у breakdown не повертаються — масив містить тільки ненульові компоненти.