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

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

Отчёт — основная сущность сервиса SpectrumData. Он используется для предоставления клиенту информации по запрошенному объекту (человеку, автомобилю, компании или недвижимости).

Получив запрос на генерацию отчёта, 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://b2b-api.spectrumdata.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 укажите нужный тип отчёта, в теле запроса передайте тип запроса и значение идентификаторов объекта, по которому должен формироваться отчёт. Структура тела запроса зависит от объекта поиска:

• для отчёта по транспортному средству используется простой запрос: в поле queryType указывается вид идентификатора, а в query — его значение.
• для отчётов по объектам, которые описываются несколькими параметрами, используется сложный запрос: в поле queryType указывается значение MULTIPART, в поле query передаётся пробел, а идентифкаторы объекта поиска перечисляются в объекте data.

Подробнее о типах запросов

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

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

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

{
  "queryType": "MULTIPART",
  "query": " ",
  "data": {
    "last_name": "Корнейчук",
    "first_name": "Семен",
    "patronymic": "Дмитриевич",
    "birth": "16.01.1995",
    "passport": "4218127156",
    "passport_date": "30.05.2018"
  }
}

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

{ 
 "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
  }
}

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

{
  "queryType": "MULTIPART",
  "query": " ",
  "data": {
    "last_name": "Корнейчук",
    "first_name": "Семен",
    "patronymic": "Дмитриевич",
    "birth": "16.01.1995",
    "passport": "4218127156",
    "passport_date": "30.05.2018"
  },
  "options": {
    "FORCE": true
  }
}

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

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

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

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

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

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

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

{
  "queryType": "MULTIPART",
  "query": " ",
  "data": {
    "last_name": "Корнейчук",
    "first_name": "Семен",
    "patronymic": "Дмитриевич",
    "birth": "16.01.1995",
    "passport": "4218127156",
    "passport_date": "30.05.2018"
  },
  "idempotenceKey": "any_key"
}

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

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

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

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

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

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

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

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

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

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

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

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

{
  "queryType": "MULTIPART",
  "query": " ",
  "data": {
    "last_name": "Корнейчук",
    "first_name": "Семен",
    "patronymic": "Дмитриевич",
    "birth": "16.01.1995",
    "passport": "4218127156",
    "passport_date": "30.05.2018"
  },
  "options": {
    "webhook": {
      "on_update": "http://example.com/2",
      "on_complete": "http://example.com/3"
    }
  }
}

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

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

{
  "report_uid": "report_2_1628749485392@test_domain",
  "timestamp": 1630921842742,
  "state": {
    "sources": [
      {
        "_id": "check_person/person_inn_2",
        "state": "PROGRESS",
        "extended_state": "NONE"
      },
      {
        "_id": "check_person/person_inn",
        "state": "OK",
        "extended_state": "OK"
      }
    ]
  },
  "event": "on_update",
  "status": "process"
}

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

{
  "report_uid": "report_2_1628749485392@test_domain",
  "timestamp": 1630923487628,
  "state": {
    "sources": [
      {
        "_id": "check_person/person_inn",
        "state": "OK",
        "extended_state": "OK"
      },
      {
        "_id": "check_person/person_inn_2",
        "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://b2b-api.spectrumdata.ru/b2b/api/v1/user/reports/report_2_1628749485392@test_domain?_content=true'

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

{
  "state": "ok",
  "size": 1,
  "stamp": "2021-07-09T14:25:58.561Z",
  "data": [
    {
      "domain_uid": "test_domain",
      "report_type_uid": "test_report_type@test_domain",
      "query": {
        "type": "MULTIPART",
        "body": " ",
        "data": {
          "last_name": "Корнейчук",
          "first_name": "Семен",
          "patronymic": "Дмитриевич",
          "birth": "16.01.1995",
          "passport": "4218127156",
          "passport_date": "30.05.2018"
        }
      },
      "progress_ok": 1,
      "progress_wait": 0,
      "progress_error": 0,
      "state": {
        "sources": [
          {
            "_id": "check_person/person_inn",
            "state": "OK",
            "data": {}
          }
        ]
      },
      "requested_at": "2021-07-07T07:42:27.008Z",
      "content": {
        "check_person": {
          "inn": {
            "status": "FOUND",
            "value": "504724045776"
          }
        }
      },
      "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.type:!"MULTIPART"
_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://b2b-api.spectrumdata.ru/b2b/api/v1/user/reports'

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

{
  "state": "ok",
  "size": 2,
  "stamp": "2021-09-14T10:20:22.312Z",
  "data": [
    {
      "domain_uid": "test_domain",
      "report_type_uid": "test_report_type@test_domain",
      "query": {
        "type": "MULTIPART",
        "body": " ",
        "data": {
          "last_name": "Корнейчук",
          "first_name": "Семен",
          "patronymic": "Дмитриевич",
          "birth": "16.01.1995",
          "passport": "4218127156",
          "passport_date": "30.05.2018"
        }
      },
      "progress_ok": 1,
      "progress_wait": 0,
      "progress_error": 0,
      "state": {
        "sources": [
          {
            "_id": "check_person/person_inn",
            "state": "OK",
            "data": {}
          }
        ]
      },
      "requested_at": "2021-07-07T07:42:27.008Z",
      "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"
    },
    {
      "domain_uid": "test_domain",
      "report_type_uid": "test_report_type@test_domain",
      "query": {
        "type": "MULTIPART",
        "body": " ",
        "data": {
          "last_name": "Корнейчук",
          "first_name": "Дмитрий",
          "patronymic": "Дмитриевич",
          "birth": "16.01.1995",
          "passport": "4218127157",
          "passport_date": "30.05.2018"
        }
      },
      "progress_ok": 1,
      "progress_wait": 0,
      "progress_error": 0,
      "state": {
        "sources": [
          {
            "_id": "check_person/person_inn",
            "state": "OK",
            "data": {}
          }
        ]
      },
      "requested_at": "2021-09-13T11:51:26.595Z",
      "last_generation_stat": {
        "start_time": "2021-09-13T11:51:28.000Z",
        "complete_time": "2021-09-13T11:52:28.000Z",
        "duration": 60000
      },
      "uid": "report_2_1628749485392@test_domain",
      "name": "NONAME",
      "comment": "",
      "tags": "",
      "created_at": "2021-09-13T11:51:26.459Z",
      "created_by": "system",
      "updated_at": "2021-09-13T11:51:27.782Z",
      "updated_by": "system",
      "active_from": "1900-01-01T00:00:00.000Z",
      "active_to": "3000-01-01T00:00:00.000Z"
    }
  ]
}