> For the complete documentation index, see [llms.txt](https://docs.npck.kz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.npck.kz/open-banking/poluchenie-svedenii-po-nalogovoi-deklaracii-kgd.md). # Получение сведений по налоговой декларации КГД ## Получение сведений по налоговой декларации КГД ### Общая схема взаимодействия Сервис обмена банковской информацией для предзаполнения налоговой декларации по форме 910.00. #### Общий процесс получения информации о банковских счетах Процесс включает следующие основные шаги: **1. Запрос OAuth-ссылки** * Клиент в приложении Пользователя API инициирует запрос на получение данных по открытым банковским счетам в других банках. * Пользователь API формирует и направляет запрос в Систему открытого банкинга на получение OAuth-ссылки (`POST /v1/auth/generate-user-url`), передавая требуемые параметры. * Система осуществляет получение данных клиента, выполняет валидацию провайдеров и доступности API, после чего возвращает Пользователю API URL для перенаправления Клиента. {% hint style="warning" %} Пользователь API самостоятельно осуществляет проверку полномочий Клиента в соответствии с его статусом (индивидуальный предприниматель и/или юридическое лицо), а также проверяет допустимость предоставления запрашиваемых данных. {% endhint %} **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. ``` POST /v1/auth/generate-user-url Authorization: Basic {base64(client_id:client_secret)} Content-Type: application/json ``` **Юридическое лицо:** ```json { "scopes": ["tax_income"], "redirectUri": "https://client.example.kz/callback", "state": "a1b2c3d4e5", "iin": "123456789012", "bin": "000000000000", "taxIncomeScopeData": { "providerIds": [ "6h7j8k2e-4d4d-3d3d-4444-9k0l3x6vbb6c", "7a5g770d-1f1f-9n9n-5555-886f7j2s4s4f" ], "periodYear": 2026, "periodHalfYear": 1 } } ``` **Индивидуальный предприниматель (`bin` не передаётся):** ```json { "scopes": ["tax_income"], "redirectUri": "https://client.example.kz/callback", "state": "a1b2c3d4e5", "iin": "123456789012", "taxIncomeScopeData": { "providerIds": ["7a5g770d-1f1f-9n9n-5555-886f7j2s4s4f"], "periodYear": 2026, "periodHalfYear": 2 } } ``` **Ответ:** ``` HTTP/1.1 200 OK { "url": "https://auth.npck.kz/..." } ``` **Параметры запроса:** | Параметр | Обязательный | Описание | | ----------------------------------- | ------------- | ---------------------------------------------- | | `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. Инициация агрегации** Тело запроса не передаётся. Период, ИИН и БИН берутся из согласия, зафиксированного в токене доступа. ``` POST /v1/tax-income/aggregations Authorization: Bearer {access_token} ``` *** **Пример 3. Ответ на инициацию агрегации** ``` HTTP/1.1 201 Created Location: /v1/tax-income/aggregations/8126j88k-9999-4a3e-9d6a-2f2f6f1b4d2s Content-Type: application/json ``` ```json { "aggregationId": "8126j88k-9999-4a3e-9d6a-2f2f6f1b4d2s", "consentIds": [ "3fa9c1e5-d02b-4e6c-8f4d-7b2d1a5c4f3e", "a7e2d5c6-f30b-41ae-9d8f-4d6b2e5a3f4c" ], "status": "IN_PROGRESS" } ``` *** **Пример 4. Запрос платформы к банку (реализует банк)** ``` POST {provider_url}/v1/tax-income Authorization: Bearer {bearerToken} Content-Type: application/json ``` ```json { "aggregationId": "8126j88k-9999-4a3e-9d6a-2f2f6f1b4d2s", "dateFrom": "2026-01-01T00:00:00+05:00", "dateTo": "2026-06-30T23:59:59+05:00" } ``` **Ожидаемый ответ банка (тело не требуется):** ``` HTTP/1.1 202 Accepted ``` | Параметр | Описание | | -------------------- | -------------------------------------------------------------------------------------------------------------------- | | `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 от банка (реализует платформа)** ``` POST /v1/tax-income/aggregations/8126j88k-9999-4a3e-9d6a-2f2f6f1b4d2s/callback Authorization: Bearer {provider_token} Content-Type: application/json ``` **Данные получены:** ```json { "bankStatus": "SUCCESS", "accounts": [ { "accountId": "d43b6x4k-9d6h-4c3e-0d47-j82l4vb6k3d4", "accountType": "CURRENT", "currency": "KZT", "total_card_mobile": 100000.50 }, { "accountId": "f57n2a9s-4g15-7f8d-5n06-s7f9j541f785", "accountType": "CURRENT", "currency": "USD", "total_card_mobile": 100.00 } ] } ``` **У клиента нет счетов в банке:** ```json { "bankStatus": "SUCCESS", "accounts": [] } ``` **Банк не смог обработать запрос:** ```json { "bankStatus": "ERROR", "accounts": [] } ``` **Ответ платформы:** ``` HTTP/1.1 200 OK ``` | Поле | Тип | Описание | | ------------------------------ | ------ | ----------------------------------------------------------- | | `bankStatus` | string | `SUCCESS` или `ERROR` | | `accounts[].accountId` | UUID | Идентификатор счёта (OBID) | | `accounts[].accountType` | string | Пока только `CURRENT` | | `accounts[].currency` | string | Код валюты | | `accounts[].total_card_mobile` | number | Сумма поступлений картами и мобильными переводами за период | {% hint style="info" %} `provider_token` - токен, который банк получил при подключении к платформе. Callback, пришедший позже `T_max` (12 ч), не принимается. {% endhint %} *** **Пример 6. Polling, сбор идёт** ``` GET /v1/tax-income/aggregations/8126j88k-9999-4a3e-9d6a-2f2f6f1b4d2s Authorization: Bearer {access_token} HTTP/1.1 202 Accepted Retry-After: 30 Content-Type: application/json ``` ```json { "aggregationId": "8126j88k-9999-4a3e-9d6a-2f2f6f1b4d2s", "status": "IN_PROGRESS", "consentIds": ["3fa9c1e5-d02b-4e6c-8f4d-7b2d1a5c4f3e", "a7e2d5c6-f30b-41ae-9d8f-4d6b2e5a3f4c"], "iinBin": "123456789012", "periodYear": 2026, "periodHalfYear": 1, "data": [ { "bankBIN": "000000000001", "bankBIC": "AAAAKZKA", "bankName": "Банк А", "bankStatus": "SUCCESS", "accounts": [ { "accountId": "d43b6x4k-9d6h-4c3e-0d47-j82l4vb6k3d4", "accountType": "CURRENT", "currency": "KZT", "total_card_mobile": 100000.50 } ] }, { "bankBIN": "000000000002", "bankBIC": "BBBBKZKB", "bankName": "Банк Б", "bankStatus": "NO_RESPONSE", "accounts": [] } ] } ``` **Если запрашивать чаще, чем раз в 30 секунд:** ``` HTTP/1.1 429 Too Many Requests Retry-After: 12 ``` {% hint style="info" %} Пока сбор идёт, `NO_RESPONSE` означает, что банк ещё не ответил. Окончательным этот статус становится только после завершения агрегации. {% endhint %} *** **Пример 7. Polling, сбор завершён** ``` HTTP/1.1 200 OK Content-Type: application/json ``` ```json { "aggregationId": "8126j88k-9999-4a3e-9d6a-2f2f6f1b4d2s", "status": "COMPLETED", "consentIds": ["3fa9c1e5-d02b-4e6c-8f4d-7b2d1a5c4f3e", "a7e2d5c6-f30b-41ae-9d8f-4d6b2e5a3f4c"], "iinBin": "123456789012", "periodYear": 2026, "periodHalfYear": 1, "data": [ { "bankBIN": "000000000001", "bankBIC": "AAAAKZKA", "bankName": "Банк А", "bankStatus": "SUCCESS", "accounts": [ { "accountId": "d43b6x4k-9d6h-4c3e-0d47-j82l4vb6k3d4", "accountType": "CURRENT", "currency": "KZT", "total_card_mobile": 100000.50 }, { "accountId": "f57n2a9s-4g15-7f8d-5n06-s7f9j541f785", "accountType": "CURRENT", "currency": "USD", "total_card_mobile": 100.00 } ] }, { "bankBIN": "000000000002", "bankBIC": "BBBBKZKB", "bankName": "Банк Б", "bankStatus": "NO_RESPONSE", "accounts": [] } ] } ``` **Описание полей ответа:** | Поле | Тип | Описание | | ------------------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | | `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 | {% hint style="danger" %} **Важно.** * Результат со статусом `COMPLETED` выдаётся **один раз**: после ответа агрегация удаляется, и повторный запрос вернёт `404`. Сохраните результат на своей стороне. * Если результат не забрали, агрегация удаляется через 1 час после истечения `T_max` (примерно через 13 часов после создания). {% endhint %} *** #### Краткое описание методов | Метод | Эндпоинт | Описание | | ------ | ------------------------------------------------------ | ------------------------------------------ | | `POST` | `/v1/tax-income/aggregations` | Инициация агрегации | | `GET` | `/v1/tax-income/aggregations/{aggregationId}` | Polling результата | | `POST` | `/v1/tax-income` | Запрос данных у банка (реализует банк) | | `POST` | `/v1/tax-income/aggregations/{aggregationId}/callback` | Callback от банка (реализует Платформа ОБ) |