Быстрый старт

Эта статья поможет вам получить первый отчёт.

Подготовка

Чтобы начать работать с SpectrumData, вам нужно получить учётную запись. Для этого свяжитесь с нами через форму заявки на сайте.

Шаг 1. Сформируйте токен

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

Сгенерируйте токен по алгоритму base64(user:stamp:age:salted_hash), используя следующие параметры:

  • user — UID пользователя в формате name@domain,
  • stamp:age — метка времени:
    • stamp — дата начала действия токена с точностью до секунды (UTC + 0 в Unix-time),
    • age — время жизни токена в секундах,
  • salted_hash — солёный хеш пароля base64(md5(salt:pass_hash)):
    • pass_hash = base64(md5(pass)) — хешированный пароль pass пользователя,
    • salt — метка времени stamp:age.

При отправке запроса передавайте в нём HTTP-заголовок Authorization со значением AR-REST <token>:

Authorization: AR-REST dGVzdF91c2VyQHRlc3RfZG9tYWluOjE0ODM2MzQ3MjM6OTk5OTk5OTk5OjN3ZzgyRXVUd2VjMjkvT3ZRN215eUE9PQ==

Чтобы проверить валидность созданного токена, отправьте GET-запрос к /user:

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

Если API обработал запрос без ошибки и вернул в ответе сведения о вашей учётной записи, значит, токен сформирован корректно.

Шаг 2. Проверьте наличие предоплаченных отчётов на балансе

Каждому типу отчёта устанавливаются квоты (лимит отчётов, которые вы можете генерировать): дневная, месячная и общая.

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

Пример запроса для проверки квот

curl -X GET \
--header 'Accept: application/json' \
--header 'Authorization: AR-REST dGVzdF91c2VyQHRlc3RfZG9tYWluOjE0ODM2MzQ3MjM6OTk5OTk5OTk5OjN3ZzgyRXVUd2VjMjkvT3ZRN215eUE9PQ==' \
'https://b2b-api.spectrumdata.ru/b2b/api/v1/user/balance/test_report_type@test_domain'

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

{
  "state": "ok",
  "size": 3,
  "stamp": "2021-09-06T12:52:21.370Z",
  "data": [
    {
      "report_type_uid": "test_report_type@test_domain",
      "balance_type": "DAY",
      "quote_init": 2,
      "quote_up": 0,
      "quote_use": 1,
      "created_at": "2021-09-06T09:45:23.630Z",
      "updated_at": "2021-09-06T09:45:23.630Z",
      "balance_date": "2021-09-06T09:45:23.645Z"
    },
    {
      "report_type_uid": "test_report_type@test_domain",
      "balance_type": "MONTH",
      "quote_init": 0,
      "quote_up": 0,
      "quote_use": 3,
      "created_at": "2021-09-03T12:27:24.405Z",
      "updated_at": "2021-09-03T12:27:24.405Z",
      "balance_date": "2021-09-03T12:27:24.431Z"
    },
    {
      "report_type_uid": "test_report_type@test_domain",
      "balance_type": "TOTAL",
      "quote_init": 100,
      "quote_up": 0,
      "quote_use": 3,
      "created_at": "2021-09-03T12:27:24.405Z",
      "updated_at": "2021-09-03T12:27:24.405Z",
      "balance_date": "2021-09-03T12:27:24.417Z"
    }
  ]
}

Тип квоты указывается в переменной data[].balance_type. Баланс вычисляется по формуле
data[].quote_init + data[].quote_up - data[].quote_use.

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

Шаг 3. Отправьте запрос на генерацию отчёта

Запустите процесс создания отчёта, выполнив 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://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"
  }
}

После отправки запроса формируется отчёт с уникальным идентификатором, который API отправляет в теле ответа в переменной data[].uid.

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

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

Шаг 4. Получите отчёт

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

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

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": "source_inn",
            "state": "OK",
            "data": {}
          }
        ],
        "data": {}
      },
      "requested_at": "2021-07-07T07:42:27.008Z",
      "content": {
        "check_person": {
          "inn": {
            "status": "FOUND",
            "value": "504724045776"
          }
        }
      },
      "last_generation_stat": {
        "duration": 2121,
        "start_time": "2021-07-07T07:42:27.008Z",
        "complete_time": "2021-07-07T07:42:29.129Z"
      },
      "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"
    }
  ]
}

Как определить, что генерация отчёта завершена?

Отчёт доступен в любой момент после его генерации, но наполняется данными по мере получения ответов от источников информации. Количество источников, ответ от которых ещё не получен, указывается в переменной data[].progress_wait. Генерация отчёта считается завершённой, если значение этой переменной равно 0.