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

• Подготовка
• Шаг 1. Сформируйте токен
• Шаг 2. Проверьте наличие предоплаченных отчётов на балансе
• Шаг 3. Сгенерируйте отчёт

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

Подготовка

Чтобы начать работать с 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://b2bsync.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://b2bsync.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": "2022-09-03T12:27:24.405Z",
      "updated_at": "2022-09-03T12:27:24.405Z",
      "balance_date": "2022-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": "2022-09-03T12:27:24.405Z",
      "updated_at": "2022-09-03T12:27:24.405Z",
      "balance_date": "2022-09-03T12:27:24.417Z"
    }
  ]
}

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

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

Шаг 3. Сгенерируйте отчёт

Запустите процесс создания отчёта, выполнив POST-запрос к /user/reports/{REPORT_TYPE_UID}/_syncmake.

В параметре REPORT_TYPE_UID укажите нужный тип отчёта.

Используйте параметр запроса _content = true, чтобы получить в ответе содержимое отчёта. Если параметр _content не указан или имеет значение false, ответ API будет содержать только заголовочную часть без данных отчёта.

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

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

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

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

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

Сгенерированный отчёт содержится в теле ответа.

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

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