Получение сведений по налоговой декларации КГД
Получение сведений по налоговой декларации КГД
Общая схема взаимодействия
Сервис обмена банковской информацией для предзаполнения налоговой декларации по форме 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
Сумма поступлений картами и мобильными переводами за период
Пример 6. Polling, сбор идёт
Если запрашивать чаще, чем раз в 30 секунд:
Пример 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