For the complete documentation index, see llms.txt. This page is also available as Markdown.

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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


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

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

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

Юридическое лицо:

Индивидуальный предприниматель (bin не передаётся):

Ответ:

Параметры запроса:

Параметр
Обязательный
Описание

scopes

да

Должен содержать tax_income

redirectUri

да

Адрес возврата, зарегистрированный для клиента

state

да

Случайная строка

iin

да

ИИН клиента (руководителя ЮЛ или ИП)

bin

только для ЮЛ

БИН юрлица. Для ИП не передаётся

taxIncomeScopeData.providerIds

да

Идентификаторы банков-поставщиков

taxIncomeScopeData.periodYear

да

Год налогового периода, 2000-2099

taxIncomeScopeData.periodHalfYear

да

1 - январь-июнь, 2 - июль-декабрь

Затем клиент проходит 2FA и даёт согласие, а Пользователь API обменивает код авторизации на access_token через POST /oauth2/token по стандартной схеме Authorization Code.


Пример 2. Инициация агрегации

Тело запроса не передаётся. Период, ИИН и БИН берутся из согласия, зафиксированного в токене доступа.


Пример 3. Ответ на инициацию агрегации


Пример 4. Запрос платформы к банку (реализует банк)

Ожидаемый ответ банка (тело не требуется):

Параметр
Описание

Authorization

Токен клиента, выданный Системой

aggregationId

Идентификатор агрегации. Его нужно указать в URL callback-запроса

dateFrom, dateTo

Границы полугодия, ISO 8601 со смещением +05:00: 01-01 00:00:00 - 06-30 23:59:59 или 07-01 00:00:00 - 12-31 23:59:59


Пример 5. Callback от банка (реализует платформа)

Данные получены:

У клиента нет счетов в банке:

Банк не смог обработать запрос:

Ответ платформы:

Поле
Тип
Описание

bankStatus

string

SUCCESS или ERROR

accounts[].accountId

UUID

Идентификатор счёта (OBID)

accounts[].accountType

string

Пока только CURRENT

accounts[].currency

string

Код валюты

accounts[].total_card_mobile

number

Сумма поступлений картами и мобильными переводами за период

provider_token - токен, который банк получил при подключении к платформе. Callback, пришедший позже T_max (12 ч), не принимается.


Пример 6. Polling, сбор идёт

Если запрашивать чаще, чем раз в 30 секунд:

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


Пример 7. Polling, сбор завершён

Описание полей ответа:

Поле
Тип
Описание

aggregationId

UUID

Идентификатор агрегации

status

string

IN_PROGRESS или COMPLETED

consentIds

UUID[]

Идентификаторы согласий по каждому банку

iinBin

string, 12 цифр

БИН, если он был в согласии, иначе ИИН

periodYear

integer

Год периода

periodHalfYear

integer

1 или 2

data[].bankBIN / bankBIC / bankName

string

Реквизиты банка

data[].bankStatus

string

SUCCESS - данные получены; NO_RESPONSE - банк не ответил до истечения T_max; ERROR - банк недоступен, ответил ошибкой или прислал ERROR

data[].accounts

array

Счета клиента в банке, формат как в примере 5


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

Метод
Эндпоинт
Описание

POST

/v1/tax-income/aggregations

Инициация агрегации

GET

/v1/tax-income/aggregations/{aggregationId}

Polling результата

POST

/v1/tax-income

Запрос данных у банка (реализует банк)

POST

/v1/tax-income/aggregations/{aggregationId}/callback

Callback от банка (реализует Платформа ОБ)

Last updated