Получения сведений по налоговой декларации КГД

Общая схема взаимодействия

Сервис обмена банковской информацией для предзаполнения налоговой декларации по форме 910.00.

Общий процесс получения информации о банковских счетах

Процесс включает следующие основные шаги:

1. Запрос OAuth-ссылки

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

• Пользователь API формирует и направляет запрос в Систему открытого банкинга на получение OAuth-ссылки (POST /v1/auth/generate-user-url), передавая требуемые параметры.

• Система осуществляет получение данных клиента, выполняет валидацию провайдеров и доступности API, после чего возвращает Пользователю API URL для перенаправления Клиента.

Пользователь API самостоятельно осуществляет проверку полномочий Клиента в соответствии с его статусом (индивидуальный предприниматель и/или юридическое лицо), а также проверяет допустимость предоставления запрашиваемых данных.

2. Двухфакторная аутентификация клиента

• Пользователь API осуществляет перенаправление клиента на полученный URL.

• Клиент проходит процедуру двухфакторной аутентификации в Системе.

3. Регистрация согласия и выдача токена доступа

• Система отображает Клиенту экран согласия на доступ к данным.

• В случае подтверждения Клиентом согласия - Пользователь API получает токен доступа.

• В случае отказа Клиента от согласия - сессия считается неуспешной.

4. Инициация запроса на доступ к информации о банковских счетах

• С использованием полученного токена доступа Пользователь API обращается в Систему для получения информации об имеющихся банковских счетах в других банках.

• Система осуществляет маршрутизацию запросов к Поставщикам API по каждому providerIds из токена.

• Поставщик(-и) API принимает запрос асинхронно (202 Accepted), готовит данные и передаёт результат callback-запросом в Систему.

• После получения callback-ов от всех Поставщиков API либо по истечении T_max Система устанавливает статус COMPLETED.

5. Polling результата

Пользователь API получает результат периодическими polling-запросами по aggregationId.

---

Детальная схема взаимодействия

Получение access-token

Используется стандартный OAuth 2.0 Authorization Code Flow.

Отличия для tax-income:

• scopes = [tax-income]

• В POST /v1/auth/generate-user-url дополнительно передаётся:

{
  "scopes": ["tax-income"],
  "taxIncomeScopeData": {
    "providerIds": ["..."]
  },
  "iin": "...",
  "bin": "... (для ЮЛ/ИП)"
}

iin и bin передаются в полях верхнего уровня запроса, а перечень банков — в taxIncomeScopeData.providerIds.

---

1. Инициация агрегации (async)

Шаг 1 — Пользователь API → Платформа ОБ

POST /v1/tax-income/aggregations
Authorization: Bearer {access_token}

{
  "dateFrom": "...",
  "dateTo": "..."
}

iin и bin подставляются автоматически из токена.

Шаг 2 — Платформа ОБ → Пользователь API

200 OK
{
  "aggregationId": "...",
  "status": "IN_PROGRESS",
  "dateFrom": "...",
  "dateTo": "..."
}

Шаги 3-6 — Платформа ОБ → Поставщики API (фоновый сбор)

Платформа ОБ запускает фоновый сбор данных (async, T_max = 12 ч). По каждому providerId из scope:

POST /v1/tax-income
Authorization: Bearer {access_token}

{
  "aggregationId": "...",
  "dateFrom": "...",
  "dateTo": "..."
}

Поставщик API отвечает 202 Accepted и готовит данные асинхронно. После готовности передаёт результат callback-запросом:

POST /v1/tax-income/aggregations/{aggregationId}/callback
Authorization: Bearer {provider_token}

{
  "bankStatus": "SUCCESS",
  "accounts": [...]
}

По истечении T_max статус принудительно становится COMPLETED:

• Банкам, не приславшим callback — bankStatus = NO_RESPONSE

• Банкам, вернувшим ошибку 4xx/5xx — bankStatus = ERROR

---

2. Polling результата

GET /v1/tax-income/aggregations/{aggregationId}
Authorization: Bearer {access_token}

Интервал между запросами — не менее 30 секунд. При превышении частоты возвращается 429 Too Many Requests с заголовком Retry-After.

Сбор ещё идёт:

200 OK
{
  "status": "IN_PROGRESS"
}

Сбор завершён или истёк T_max:

200 OK
{
  "status": "COMPLETED",
  "iin": "...",
  "bin": "... (если передавался)",
  "data": [
    {
      "bankBIN": "...",
      "bankBIC": "...",
      "bankName": "...",
      "bankStatus": "...",
      "accounts": [
        {
          "accountId": "...",
          "accountType": "...",
          "currency": "...",
          "total_card_mobile": "..."
        }
      ]
    }
  ]
}

---

Краткое описание методов

Метод	Эндпоинт	Описание
POST	/v1/tax-income/aggregations	Инициация агрегации
GET	/v1/tax-income/aggregations/{aggregationId}	Polling результата
POST	/v1/tax-income	Запрос данных у банка (реализует банк)
POST	/v1/tax-income/aggregations/{aggregationId}/callback	Callback от банка (реализует Платформа ОБ)