Page tree

Citypoint - контроль и аналитика автопарка

Skip to end of metadata
Go to start of metadata

Получение расхода топлива на ТС за период. В отличии от метода v2.1 Сводная информация по ТС (который возвращает расход только при наличии датчика расхода топлива) может работать при наличии только ДУЖ датчиков.

Как рассчитывался расход (по датчику расхода или по ДУЖ) дополнительно выводится в meta.

Внимание!  Расход топлива зависит в том числе от заправок и сливов, которые считаются дискретно с частотой раз в 60 минут. Это связано с тем, что:

  • данные с блока могут прийти с задержкой (архив) при плохом сигнале GSM сотового оператора
  • при поступлении архива с блока события "заправки" и "сливы" могут быть уточнены и пересчитаны
  • заправки на АЗС для больших баков могут занимать длительное время (от 5 минут и более)
  • Встроенные датчики уровня топлива автомобиля (CAN) могут "залипать" и выдавать данные с задержкой даже после выезда с АЗС (до 5 минут)

В связи с этим данные по расходу (например, для путевого листа) необходимо запрашивать с задержкой не менее +120 минут от запрашиваемого периода. 

В случае, если данные по расходу, заправкам и сливам еще не рассчитаны - то метод вернет ответ со статусом 202 и заголовком Retry-After содержащим информацию через сколько времени следует повторить запрос. 

Запрос:

URL:

GET https://api.url/v2.1/user/<user_id>/cars/<car_id>/history/fuel-consumption/<date_from>/<date_to>

Доп. Заголовки:

Accept - для указания формата ответа. Должен быть "application/vnd.api+json", для совместимости принимается также "application/json".

Authorization - для передачи токена. Передается в формате: Bearer <access_token>.

Доп. Параметры запроса:

ПараметрЗначение по умолчаниюОписание
require-fillings-drainsfalse

По умолчанию если расход может быть посчитать по датчикам расхода топлива и данные по сливам заправкам ещё не готовы, то сервер отвечает статусом 200 и отдаёт расход, но в полях TotalDrain, TotalFuelingDrainByGroup, FuelingByGroup будут null.

Данным флагом можно отключить это поведение. Тогда API будет проверять готовность данных по сливам заправкам и отвечать 202 если не может немедленно предоставить результат.

Если на ТС вообще нет ДУЖ датчиков топлива, то включение параметра никак не повлияет на ответ.


Ответ:

ПолеОписание
links

Поле links содержит ссылку на текущий ресурс (self)

meta

Содержит иноформацию по способу расчета расхода топлива для TotalConsuption и ConsuptionByGroup.

Поля:

TotalCalculationType - как было расчитано потребление топлива для TotalConsuption.

GroupCalculationType - как было расчитано потребление топлива для ConsuptionByGroup.

Возможные значения:

by_sensor - расход расчитан по датчику расхода.

calculated - расход расчитан по показаниям ДУЖ с учетом сливов и заправок.

data
ПолеТипОписание
Idstringидентификатор строка состоит из
fuelCons + date_from + date_to
typestringТип ресурса (всегда "fuelConsuption")
attributesobjectДанные истории (см. Описание атрибутов)

Описание атрибутов истории:

Описание объекта состояния ТС в истории (histState).
ПолеТипNullableОписание
TotalConsuptiondoubleда

Суммарный расход по всем топливным группам.

Если на ТС есть топливные группы то выводится сумма расходов из поля ConsuptionByGroup.

Если на ТС нет топливных групп но есть датчики расхода топлива то выводится сумма расходов по датчикам.

В данном поле передаётся расход топлива потраченный только на работу ТС. Если требуется получить всё убывшее топливо (включая то которое было слито), то к данному параметру нужно прибавить значение из TotalDrains.

Будет заполнен даже если на ТС нет топливных групп но есть датчик расхода.

NULL если на ТС нет датчиков топлива и датчиков расхода топлива.

ConsuptionByGroupobjectда

Расход топлива по отдельным группам.

В данном поле передаётся расход топлива потраченный только на работу ТС. Если требуется получить всё убывшее топливо (включая то которое было слито), то к данному параметру нужно прибавить значение из соотвутвующе группы топлива из поля DrainsByGroup.

Если на ТС в группе датчиков есть датчик расхода топлива то расход считается по нему.

Если подсчет расхода идёт на основе ДУЖ датчиков топлива (calculated) то в данный показатель также будут включены все сливы топлива. Если нужно получить расход только на работу механизмов то сливы нужно дополнительно вычесть значение соответствующей группы топлива из поля DrainsByGroup.

NULL если на ТС нет ДУЖ датчиков топлива и датчиков расхода топлива или они не объединены в группы.

TotalDrainsdoubleда

Всего слито топлива.

NULL если на ТС нет ДУЖ датчиков топлива или они не объединены в группы или данные по сливам пока не готовы но расход можно выдать по датчику расхода топлива.

DrainsByGroupobjectда

Слито топлива по отдельным группам.

Если на ТС только 1 топливная группа и есть датчик расхода топлива то расход выводится по датчику расхода (даже если он не привязан).

NULL если на ТС нет ДУЖ датчиков топлива или они не объединены в группы или данные по сливам пока не готовы но расход можно выдать по датчику расхода топлива.

TotalFuelingdoubleда

Всего заправлено топлива.

NULL если на ТС нет ДУЖ датчиков топлива или они не объединены в группы или данные по сливам пока не готовы но расход можно выдать по датчику расхода топлива.

FuelingByGroupobjectда

Заправлено топлива по отдельным группам.

NULL если на ТС нет ДУЖ датчиков топлива или они не объединены в группы или данные по сливам пока не готовы но расход можно выдать по датчику расхода топлива.

Коды ответов:

200 ОК - Сервер обработал запрос. В теле ответа  содержится объект истории.

202 Accepted - Сервер принял запрос но данные по сливам и заправкам за указанный период пока не готовы, запрос нужно повторить через некоторое время. В ответе будут переданы заголовки Location и Retry-After для указания через сколько времени стоит пробовать повторить запрос.

401 Unauthorized - не передан заголовок Authorization, либо токен невалидный или окончилась валидация.

403 Forbidden - нет прав на просмотр (id пользователя не соответствует токену).

404 Not Found - ТС не найдена или принадлежит другому пользователю либо нет истории по ТС (ни разу не выходила на связь  либо история удалена).

400 Bad Request - Переданы не поддерживаемые параметры, запрошен слишком большой период, либо сервер не понял запрос (описание ошибки в теле ответа).

Также возможны другие ошибки.

Пример:

На ТС есть только ДУЖ датчики топлива, и сервер пока не может предоставить данные по расходам по расходам по ним.

GET https://api.url/v2.1/user/1/cars/1/history/fuel-consumption/2021-01-01T08:00:00Z/2021-01-01T18:00:00Z HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <auth token>

HTTP/1.1 202 Accepted
Content-Type: application/vnd.api+json
Location: https://api.url/v2.1/user/1/cars/1/history/fuel-consumption/2021-01-01T08:00:00Z/2021-01-01T18:00:00Z
Retry-After: 1800


Расход топлива получен по датчику расхода топлива.

GET https://api.url/v2.1/user/1/cars/1/history/fuel-consumption/2021-01-01T08:00:00Z/20210101T18:00:00Z HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <auth token>

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Allow: GET				
	
{
    "links": {
        "self": "https://api.url/v2.1/user/1/cars/1/history/fuel-consumption/2021-01-01T08:00:00Z/2021-01-01T18:00:00Z",
    },
    "meta": {
        "TotalCalculationType": "by_sensor",
        "GroupCalculationType": null
    },
    "data": {
        "type": "fuelConsuption",
        "id": "fuelCons.20210101000000.202102001000000",
        "attributes": {
            "TotalConsuption": 100,
            "ConsuptionByGroup": null,
            "TotalDrains": null,
            "DrainsByGroup": null,
            "TotalFueling": null,
            "FuelingByGroup": null,
        }
        "relationships": {
             "Car": { "data": {"type": "car", "id": 1} }
        }
    },
}

Есть 2 рабочих механизма (прим: двигатель и бетоно-мешалка) каждый со своим баком, расход по первому механизму получен через датчик расхода, расход по второму через ДУЖ.

GET https://api.url/v2.1/user/1/cars/1/history/fuel-consumption/2021-01-01T08:00:00Z/20210101T18:00:00Z HTTP/1.1
Accept: application/vnd.api+json
Authorization: Bearer <auth token>

HTTP/1.1 200 OK
Content-Type: application/vnd.api+json
Allow: GET				

{
    "links": {
        "self": "https://api.url/v2.1/user/1/cars/1/history/fuel-consumption/2021-01-01T08:00:00Z/2021-01-01T18:00:00Z",
    },
    "meta": {
        "TotalCalculationType": "calculated",
        "GroupCalculationType": {
            "1": "by_sensor",
            "2": "calculated",
        }
    },
    
    "data": {
        "type": "fuelConsuption",
        "id": "fuelCons.20210101000000.202102001000000",
        "attributes": {
            "TotalConsuption": 150,
            "ConsuptionByGroup": {
                "1": 100,
                "2": 50,
            },
            "TotalDrains": 17,
            "DrainsByGroup": {
                "1": 10,
                "2": 7                
            },
            "TotalFueling": 110,
            "FuelingByGroup": {
                "1": 70,
                "2": 40
            },
        }
        "relationships": {
             "Car": { "data": {"type": "car", "id": 1} }
        }
    },
}
  • No labels

1 Comment

  1. fuel-consuption
    неверное описание метода