Управление отчётами

• Типы отчётов
• Генерация отчёта
• Перегенерация отчёта
• Идемпотентность
• Ограничение количества запросов
• Уведомления о ходе построения отчёта
• Получение отчёта
• Получение списка отчётов

Отчёт — основная сущность сервиса Автокод. Он используется для предоставления клиенту информации по запрошенному ТС.

Получив запрос на генерацию отчёта, API создаёт пустой отчёт с уникальным идентификатором, который возвращает клиенту, и отправляет запрос к поставщикам данных. Для формирования отчётов используются данные из нескольких источников. После получения ответа от источника данные сразу добавляются в отчёт. Таким образом, все имеющиеся у сервиса сведения по транспортному средству доступны клиенту, даже если генерация отчёта ещё не завершена.

Отчёты уникальны относительно типа отчёта и идентификатора ТС. Запрос на генерацию отчёта с параметрами, которые уже передавались ранее пользователем домена, не создаёт новый отчёт, а возвращает идентификатор последнего сгенерированного по этим параметрам отчёта.

Операция перегенерации используется, чтобы принудительно обновить данные в отчёте. Уникальный идентификатор отчёта при этом не меняется, а имеющиеся данные не затираются.

Сгенерированный отчёт доступен клиенту в течение 6 месяцев. Просматривать отчёты может любой пользователь домена, имеющий права на доступ к используемому типу отчёта.

Изменение баланса происходит только при генерации и перегенерации отчёта. Операция запроса существующего отчёта бесплатна.

Типы отчётов

Тип отчёта определяет, какие данные будут содержаться в отчёте по транспортному средству.

Чтобы получить список доступных вам типов отчётов, используйте GET-запрос к /user/report_types. В запросе можно указать дополнительные параметры получения ответа.

Параметры строки запроса

Параметр	Тип	Описание
Необязательные
_can_generate	boolean	Отображение типов отчётов, доступных пользователю для генерации. Значение по умолчанию — false. Возможные значения: true — отображать только доступные для генерации типы отчётов. false — отображать все типы отчётов
_content	boolean	Наличие в теле ответа данных о составе отчёта (набор источников и полей). Значение по умолчанию — false. Возможные значения: true — указывать состав отчётов. false — не указывать состав отчётов
_query	string	Параметры фильтрации данных в ответе. Запрос представляет собой выражение, состоящее из одного или нескольких условий отбора, объединённых логическими операциями. Формат условия отбора: Ключ:[Префикс]Значение. Префикс указывает на отношение неравенства. Допустимые префиксы: !, <, >. При обращении к полям со строковыми значениями допускается использование только отношений «равно» и «не равно». Допустимые логические операции: ; (OR), , (AND). Строковые значения должны быть заключены в апострофы. Внутри них не допускается использование символов ;:,!<>'". Пример: _query=month_quote:<10,day_quote:>1
_size	integer	Количество отчётов на одной странице ответа. Допустимые значения: от 1 до 100. Значение по умолчанию — 100
_offset	integer	Количество объектов в ответе, которые необходимо пропустить. Значение по умолчанию — 0
_page	integer	Номер страницы ответа. Значение по умолчанию — 1
_sort	string	Порядок сортировки. Поля указываются через запятую, - перед названием поля указывает на сортировку по убыванию. Пример: -day_quote,name
_calc_total	boolean	Наличие в теле ответа переменной total  — количество доступных типов отчётов. Значение по умолчанию — false. Возможные значения: true — указывать количество доступных типов отчётов. false — не указывать количество доступных типов отчётов

Пример запроса на получение доступных типов отчёта

curl -X GET \
--header 'Accept: application/json' \
--header 'Authorization: AR-REST dGVzdF91c2VyQHRlc3RfZG9tYWluOjE0ODM2MzQ3MjM6OTk5OTk5OTk5OjN3ZzgyRXVUd2VjMjkvT3ZRN215eUE9PQ==' \
'https://b2bapi.avtocod.ru/b2b/api/v1/user/report_types'

Пример тела ответа

{
  "state": "ok",
  "size": 1,
  "stamp": "2021-07-08T13:57:44.386Z",
  "data": [
    {
      "state": "PUBLISHED",
      "day_quote": 0,
      "month_quote": 0,
      "total_quote": 2000,
      "domain_uid": "test_domain",
      "max_age": 0,
      "clean_options": {
        "Process_Response": 0,
        "Process_Request": 0,
        "ReportLog": 0,
        "Report": 0,
        "BizLog": 0
      },
      "min_priority": 1,
      "max_priority": 200,
      "max_request": 0,
      "period_priority": 0,
      "report_make_mode": "",
      "uid": "test_report_type@test_domain",
      "name": "Отчет по умолчанию",
      "comment": "",
      "tags": "",
      "created_at": "2021-07-07T07:38:48.343Z",
      "created_by": "system",
      "updated_at": "2021-07-07T07:38:48.343Z",
      "updated_by": "system",
      "active_from": "1900-01-01T00:00:00.000Z",
      "active_to": "3000-01-01T00:00:00.000Z"
    }
  ]
}

Генерация отчёта

Для запуска процесса генерации отчёта отправьте POST-запрос к /user/reports/{REPORT_TYPE_UID}/_make. В параметре REPORT_TYPE_UID укажите нужный тип отчёта; в теле запроса передайте тип и значение идентификатора транспортного средства, по которому должен формироваться отчёт.

Пример запроса на генерацию отчёта по ГРЗ

curl -X POST \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: AR-REST dGVzdF91c2VyQHRlc3RfZG9tYWluOjE0ODM2MzQ3MjM6OTk5OTk5OTk5OjN3ZzgyRXVUd2VjMjkvT3ZRN215eUE9PQ==' \
-d '{<тело запроса>}' \
'https://b2bapi.avtocod.ru/b2b/api/v1/user/reports/test_report_type@test_domain/_make'

Пример тела запроса на генерацию отчёта по ГРЗ

{
  "queryType": "GRZ",
  "query": "А111АА77"
}

После получения запроса API проверяет баланс пользователя, генерирует отчёт и отправляет пользователю уникальный идентификатор отчёта.

В общем случае сгенерированный отчёт хранится в системе в течение 6 месяцев. Для каждого типа отчёта может быть настроен свой срок хранения: в переменной max_age указывается период жизни отчёта в миллисекундах. По истечению срока хранения отчёта он удаляется, а отправка запроса на генерацию отчёта с теми же идентификаторами объекта создаст новый отчёт.

Если по транспортному средству уже существует отчёт, API вернёт уникальный идентификатор этого отчёта.

Ответ API включает массив data[], содержащий:

• уникальный идентификатор отчёта uid,
• признак создания нового отчёта isnew,
• уникальный идентификатор запроса process_request_uid,
• предполагаемый срок готовности отчёта suggest_get.

Пример ответа на запрос на генерацию отчёта

{
  "state": "ok",
  "size": 1,
  "version": "2.0",
  "stamp": "2021-08-12T05:39:23.640Z",
  "data": [
    {
      "uid": "report_2_1628749485392@test_domain",
      "isnew": true,
      "process_request_uid": "report_2_1628749485392_c0a18626e5df4a50b3e2a21e86c884bc@test_domain",
      "suggest_get": "2021-08-12T05:39:23.603Z"
    }
  ]
}

Перегенерация отчёта

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

{primary.fa-exclamation} Перегенерация является платной операцией.

Для повторной генерации отчёта добавьте ключ FORCE со значением true в поле options в теле запроса. Если по переданному идентификатору ещё не создавался отчёт, то запускается его генерация.

Пример тела запроса перегенерации отчёта по ГРЗ

{
  "queryType": "GRZ",
  "query": "А111АА77",
  "options": {
    "FORCE": true
  }
}

Идемпотентность

Идемпотентность при работе с API означает, что выполнение нескольких идентичных запросов не меняет состояние сервера и аналогично выполнению одного такого запроса.

Отправка идемпотентного запроса _make гарантирует получение результата исходного запроса (uid отчёта) без повторной генерации и, соответственно, изменения баланса. Такое поведение может использоваться, например, если API запустил процесс генерации отчёта, но пользователь по каким-либо причинам не получил идентификатор отчёта.

Для обеспечения идемпотентности используйте ключ идемпотентности idempotenceKey в теле отправляемых запросов. Значением ключа может быть строка длиной от 1 до 50 символов.

Пример тела запроса на генерацию отчёта с ключом идемпотентности

{
  "queryType": "GRZ",
  "query": "А111АА77",
  "idempotenceKey": "any_key"
}

Если API получает запрос на генерацию отчёта, содержащий ранее отправленные данные ТС и ключ идемпотентности, он обрабатывает его как повторный и возвращает пользователю uid существующего отчёта. Если данные ТС те же, но ключ идемпотентности новый, запрос считается новым. При его обработке API генерирует новый отчёт с новым uid и увеличивает счётчик заказанных отчётов.

Запрос с использованием ключа {"FORCE": true} не является идемпотентным независимо от наличия idempotenceKey, так как содержит явное указание на необходимость перегенерации отчёта.

Ограничение количества запросов

API ограничивает количество входящих запросов на генерацию и перегенерацию отчётов за единицу времени. Ограничения на частоту запросов могут отличаться для разных типов отчётов.

В случае превышения установленного лимита запросов API вернёт HTTP-код 429 с типом ошибки TooManyRequests. При получении такого сообщения рекомендуется увеличить интервалы между запросами. Более полные рекомендации вы можете получить у вашего менеджера.

Уведомления о ходе построения отчёта

Вы можете отслеживать изменения в состоянии отчёта, настроив отправку уведомлений о ходе построения отчёта.

API уведомляет о двух видах событий:

• обновление отчёта on_update — обновление статуса одного из источников;
• завершение генерации отчёта on_complete — обработаны ответы от всех источников.

Подробнее о статусах источников

Если вы хотите получать уведомления о событиях построения отчёта, добавьте их описание в поле webhook в разделе options тела запроса на генерацию отчёта. Для этого передайте событие, на которое хотите подписаться, и URL, на который будет отправляться уведомление.

Пример тела запроса на генерацию отчёта и получения уведомлений о ходе его построения

{
  "queryType": "GRZ",
  "query": "А111АА77",
  "options": {
    "webhook": {
      "on_update": "http://example.com/2",
      "on_complete": "http://example.com/3"
    }
  }
}

Уведомления представляют собой POST-запросы на адрес, указанный пользователем.

Пример уведомления об обновлении отчёта, отправленного пользователю

{
  "report_uid": "report_2_1628749485392@test_domain",
  "timestamp": 1630923487628,
  "state": {
    "sources": [
      {
        "_id": "references.base",
        "state": "PROGRESS",
        "extended_state": "NONE"
      },
      {
        "_id": "base",
        "state": "OK",
        "extended_state": "OK"
      }
    ]
  },
  "event": "on_update",
  "status": "process"
}

Пример уведомления о завершении генерации отчёта, отправленного пользователю

{
  "report_uid": "report_2_1628749485392@test_domain",
  "timestamp": 1630921842742,
  "state": {
    "sources": [
      {
        "_id": "base",
        "state": "OK",
        "extended_state": "OK"
      },
      {
        "_id": "references.base",
        "state": "OK",
        "extended_state": "OK"
      }
    ]
  },
  "event": "on_complete",
  "status": "finish"
}

Уведомления могут настраиваться для типа отчёта. Если запрос на генерацию не содержит описание уведомлений, то используются настройки для типа отчёта, указанные в объекте notification_desc.

Пример описания уведомлений в типе отчёта

{
  "notification_desc": {
    "on_update": "http://example.com/1",
    "on_complete": "http://example.com/0"
  }
}

Получение отчёта

Для того, чтобы обратиться к ранее сформированному отчёту, используйте GET-запрос к /user/reports/{REPORT_DESC}. В REPORT_DESC укажите уникальный идентификатор отчёта, который был получен при генерации отчёта.

Используйте параметр запроса _content = true, чтобы получить в ответе содержимое отчёта, или _content = false, если вам требуется только заголовочная часть отчёта (например, статусы генерации отчёта и ответа источников или информация о времени последней генерации отчёта).

{primary.fa-info} Запрос на получение сгенерированного отчёта не изменяет баланс. Вы можете обращаться к отчёту неограниченное количество раз.

Пример запроса на получение отчёта

curl -X GET \
--header 'Accept: application/json' \
--header 'Authorization: AR-REST dGVzdF91c2VyQHRlc3RfZG9tYWluOjE0ODM2MzQ3MjM6OTk5OTk5OTk5OjN3ZzgyRXVUd2VjMjkvT3ZRN215eUE9PQ==' \
'https://b2bapi.avtocod.ru/b2b/api/v1/user/reports/report_2_1628749485392@test_domain?_content=true'

Пример ответа

{
  "state": "ok",
  "size": 1,
  "version": "2.0",
  "stamp": "2021-09-06T13:01:35.467Z",
  "data": [
    {
      "domain_uid": "test_domain",
      "report_type_uid": "test_report_type@test_domain",
      "vehicle_id": "А111АА77",
      "query": {
        "type": "GRZ",
        "body": "А111АА77",
        "schema_version": "1.0",
        "storages": []
      },
      "progress_ok": 2,
      "progress_wait": 0,
      "progress_error": 0,
      "state": {
        "sources": [
          {
            "_id": "references.base",
            "state": "OK",
            "extended_state": "OK"
          },
          {
            "_id": "base",
            "state": "OK",
            "extended_state": "OK"
          }
        ]
      },
      "requested_at": "2021-07-07T07:42:27.008Z",
      "content": {
        "identifiers": {
          "vehicle": {
            "vin": "W1N4632761X366825",
            "reg_num": "А111АА77",
            "sts": "9931374070"
          }
        },
        "tech_data": {
          "brand": {
            "name": {
              "original": "МЕRСЕDЕS-ВЕNZ G-СLАSS АМG G 63",
              "normalized": "Mercedes-Benz"
            },
            "id": "ID_MARK_MERCEDES_BENZ",
            "logotype": {
              "uri": "https://vl.imgix.net/img/mercedes-benz-logo.png"
            }
          },
          "type": {
            "name": "Универсал"
          },
          "body": {
            "color": {
              "name": "Черный",
              "type": "Черный"
            }
          },
          "year": 2020,
          "engine": {
            "fuel": {
              "type": "Бензиновый",
              "type_id": "ID_ENGINE_TYPE_PETROL"
            },
            "volume": 3982,
            "power": {
              "hp": 585,
              "kw": 430
            }
          },
          "weight": {
            "netto": 2560,
            "max": 3200
          },
          "drive": {
            "type": "Полноприводной",
            "type_id": "ID_DRIVING_WHEELS_TYPE_ALL"
          },
          "wheel": {
            "position": "LEFT",
            "position_id": "ID_STEERING_WHEEL_TYPE_LEFT"
          },
          "model": {
            "id": "ID_MARK_MERCEDES_BENZ_MODEL_G_KLASS_AMG",
            "name": {
              "normalized": "G-Класс AMG"
            }
          }
        },
        "report_meta": []
      },
      "last_generation_stat": {
        "start_time": "2021-07-07T07:42:30.000Z",
        "complete_time": "2021-07-07T07:43:30.000Z",
        "duration": 60000
      },
      "uid": "report_2_1628749485392@test_domain",
      "name": "NONAME",
      "comment": "",
      "tags": "",
      "created_at": "2021-07-07T07:42:26.919Z",
      "created_by": "system",
      "updated_at": "2021-07-07T07:42:29.707Z",
      "updated_by": "system",
      "active_from": "1900-01-01T00:00:00.000Z",
      "active_to": "3000-01-01T00:00:00.000Z"
    }
  ]
}

Получение списка отчётов

Для получения списка сформированных ранее отчётов отправьте GET-запрос к /user/reports. В запросе можно указать дополнительные параметры получения ответа.

Параметры строки запроса

Параметр	Тип	Описание
Необязательные
_content	boolean	Наличие в теле ответа содержимого отчёта. Значение по умолчанию — false. Возможные значения: true — возвращать содержимое отчётов. false — не возвращать содержимое отчётов
_query	string	Параметры фильтрации данных в ответе. Запрос представляет собой выражение, состоящее из одного или нескольких условий отбора, объединённых логическими операциями. Формат условия отбора: Ключ:[Префикс]Значение. Префикс указывает на отношение неравенства. Допустимые префиксы: !, <, >. При обращении к полям со строковыми значениями допускается использование только отношений «равно» и «не равно». Допустимые логические операции: ; (OR), , (AND). Строковые значения должны быть заключены в апосторофы. Внутри них не допускается использование символов ;:,!<>'". Пример: _query=query.body:!"А111АА77"
_size	integer	Количество отчётов на одной странице ответа. Допустимые значения: от 1 до 100. Значение по умолчанию — 100
_offset	integer	Количество объектов в ответе, которые необходимо пропустить. Значение по умолчанию — 0
_page	integer	Номер страницы ответа. Значение по умолчанию — 1
_sort	string	Порядок сортировки. Поля указываются через запятую, - перед названием поля указывает на сортировку по убыванию. Пример: -created_at,uid
_calc_total	boolean	Наличие в теле ответа переменной total — количество заказанных отчётов. Значение по умолчанию — false. Возможные значения: true — указывать количество заказанных отчётов. false — не указывать количество заказанных отчётов

Пример запроса на получение списка отчётов

curl -X GET \
--header 'Accept: application/json' \
--header 'Authorization: AR-REST dGVzdF91c2VyQHRlc3RfZG9tYWluOjE0ODM2MzQ3MjM6OTk5OTk5OTk5OjN3ZzgyRXVUd2VjMjkvT3ZRN215eUE9PQ==' \
'https://b2bapi.avtocod.ru/b2b/api/v1/user/reports'

Пример тела ответа

{
  "state": "ok",
  "size": 2,
  "stamp": "2021-09-14T13:54:29.246Z",
  "data": [
    {
      "domain_uid": "test_domain",
      "report_type_uid": "test_report_type@test_domain",
      "vehicle_id": "А111АА77",
      "query": {
        "type": "GRZ",
        "body": "А111АА77",
        "idempotenceKey": "2007",
        "schema_version": "1.0",
        "storages": {}
      },
      "progress_ok": 2,
      "progress_wait": 0,
      "progress_error": 0,
      "state": {
        "sources": [
          {
            "_id": "base",
            "state": "OK",
            "extended_state": "OK"
          },
          {
            "_id": "references.base",
            "state": "OK",
            "extended_state": "OK"
          }
        ]
      },
      "requested_at": "2021-09-06T10:38:26.682Z",
      "last_generation_stat": {
        "start_time": "2021-09-06T10:38:27.000Z",
        "complete_time": "2021-09-06T10:39:27.000Z",
        "duration": 60000
      },
      "uid": "report_2_1628749481312@test_domain",
      "name": "NONAME",
      "comment": "",
      "tags": "",
      "created_at": "2021-09-06T10:38:26.637Z",
      "created_by": "system",
      "updated_at": "2021-09-06T10:38:28.226Z",
      "updated_by": "system",
      "active_from": "1900-01-01T00:00:00.000Z",
      "active_to": "3000-01-01T00:00:00.000Z"
    },
    {
      "domain_uid": "test_domain",
      "report_type_uid": "test_report_type@test_domain",
      "vehicle_id": "А111АА77",
      "query": {
        "type": "GRZ",
        "body": "А111АА77",
        "idempotenceKey": "1312",
        "schema_version": "1.0",
        "storages": {}
      },
      "progress_ok": 2,
      "progress_wait": 0,
      "progress_error": 0,
      "state": {
        "sources": [
          {
            "_id": "references.base",
            "state": "OK",
            "extended_state": "OK"
          },
          {
            "_id": "base",
            "state": "OK",
            "extended_state": "OK"
          }
        ]
      },
      "requested_at": "2021-08-12T05:36:02.879Z",
      "last_generation_stat": {
        "start_time": "2021-08-12T05:36:03.000Z",
        "complete_time": "2021-08-12T05:37:03.000Z",
        "duration": 60000
      },
      "uid": "report_2_1628749485392@test_domain",
      "name": "NONAME",
      "comment": "",
      "tags": "",
      "created_at": "2021-08-12T05:36:02.831Z",
      "created_by": "system",
      "updated_at": "2021-08-12T05:36:06.868Z",
      "updated_by": "system",
      "active_from": "1900-01-01T00:00:00.000Z",
      "active_to": "3000-01-01T00:00:00.000Z"
    }
  ]
}