> 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`.

***

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

Агрегация доходов клиента по банкам-участникам Open Banking.

Контракт разделён на две стороны:

| Сторона              | Метод                                                       | Назначение                                                    |
| -------------------- | ----------------------------------------------------------- | ------------------------------------------------------------- |
| Пользователь API     | `POST /v1/tax-income/aggregations`                          | Запустить агрегацию по согласиям пользователя                 |
| Пользователь API     | `GET /v1/tax-income/aggregations/{aggregationId}`           | Получить текущее состояние агрегации и собранные данные       |
| Поставщик API (банк) | `POST /v1/tax-income`                                       | Принять запрос на агрегацию доходов за период. Реализует банк |
| Поставщик API (банк) | `POST /v1/tax-income/aggregations/{aggregationId}/callback` | Передать результат в НПК. Реализует НПК, вызывает банк        |

***

### Порядок взаимодействия

1. Пользователь API вызывает `POST /v1/tax-income/aggregations`. Период агрегации берётся из согласия пользователя, в ответе приходят `aggregationId`, список `consentIds` и статус `IN_PROGRESS`.
2. НПК асинхронно вызывает `POST /v1/tax-income` у каждого банка, попавшего в согласия, передавая `aggregationId` и границы периода `dateFrom` / `dateTo`.
3. Банк отвечает `202 Accepted` и обрабатывает запрос у себя.
4. Завершив обработку, банк вызывает `POST /v1/tax-income/aggregations/{aggregationId}/callback` и передаёт `bankStatus` и список счетов с суммами.
5. Пользователь API опрашивает `GET /v1/tax-income/aggregations/{aggregationId}`, пока статус не станет `COMPLETED`.

***

### Аутентификация

| Схема                  | Где применяется                          | Кто выпускает токен                                           |
| ---------------------- | ---------------------------------------- | ------------------------------------------------------------- |
| `OauthAccessTokenAuth` | Методы агрегации и `POST /v1/tax-income` | Выдаётся клиенту Open Banking по стандартному OAuth 2.0       |
| `ProviderTokenAuth`    | Только callback                          | Выдаётся банку при онбординге, идентифицирует вызывающий банк |

Обе схемы - Bearer JWT в заголовке `Authorization`.

***

### Пользователь API

**Базовые URL:**

| Среда        | URL                         |
| ------------ | --------------------------- |
| Продуктивная | `https://api.npck.kz`       |
| Тестовая     | `https://api.stage.npck.kz` |

{% hint style="warning" %}
Клиенты должны игнорировать неизвестные поля в ответах API. Новые необязательные поля могут добавляться в запросы и ответы без изменения версии API.
{% endhint %}

#### `POST /v1/tax-income/aggregations` - Запустить агрегацию

Запускает асинхронную агрегацию доходов пользователя по всем банкам, указанным в согласии. Период агрегации берётся из согласия пользователя. Агрегация выполняется в фоне, результат получается опросом ресурса агрегации.

**Авторизация:** `OauthAccessTokenAuth`

**Тело запроса:** не передаётся.

```bash
curl --location --request POST 'https://api.npck.kz/v1/tax-income/aggregations' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{bearerToken}}'
```

**Ответ `201 Created`** - агрегация создана и запущена.

Заголовок `Location` - URL созданной агрегации для опроса результата, например `/v1/tax-income/aggregations/8532b64d-9c4f-4a3e-9d6a-2f2f6f1b7c3e`.

| Поле            | Тип                    | Обязательное | Описание                                                         |
| --------------- | ---------------------- | ------------ | ---------------------------------------------------------------- |
| `aggregationId` | string (uuid)          | Да           | Идентификатор созданной агрегации                                |
| `consentIds`    | array of string (uuid) | Да           | Идентификаторы согласий по банкам, на которых основана агрегация |
| `status`        | string                 | Да           | Статус агрегации                                                 |

***

#### `GET /v1/tax-income/aggregations/{aggregationId}` - Получить состояние агрегации

Возвращает текущее состояние агрегации, включая статусы по банкам и собранные на данный момент данные.

**Авторизация:** `OauthAccessTokenAuth`

**Path-параметры:**

| Параметр        | Тип           | Описание                |
| --------------- | ------------- | ----------------------- |
| `aggregationId` | string (uuid) | Идентификатор агрегации |

```bash
curl --location 'https://api.npck.kz/v1/tax-income/aggregations/<uuid>' \
--header 'Accept: application/json' \
--header 'Authorization: Bearer {{bearerToken}}'
```

**Ответы:**

| Код                     | Когда                                                                                                                                                                         |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `202 Accepted`          | Агрегация ещё выполняется. В теле - частичное состояние, собранное на данный момент. Заголовок `Retry-After` - рекомендуемое число секунд до следующего опроса, например `30` |
| `200 OK`                | Агрегация завершена. В теле - итоговый результат. Банки, не ответившие до истечения срока агрегации, возвращаются со статусом `NO_RESPONSE`                                   |
| `429 Too Many Requests` | Опрос чаще допустимого интервала. Возвращается с заголовком `Retry-After`                                                                                                     |

**Поля ответа (`200` и `202`):**

| Поле             | Тип                    | Обязательное | Описание                                                               |
| ---------------- | ---------------------- | ------------ | ---------------------------------------------------------------------- |
| `aggregationId`  | string (uuid)          | Да           | Идентификатор агрегации                                                |
| `status`         | string                 | Да           | Статус агрегации                                                       |
| `consentIds`     | array of string (uuid) | Да           | Идентификаторы согласий по банкам, на которых основана агрегация       |
| `iinBin`         | string (12 цифр)       | Да           | БИН юридического лица, если он есть в согласии, иначе ИИН пользователя |
| `periodYear`     | integer                | Да           | Год периода агрегации                                                  |
| `periodHalfYear` | integer (1-2)          | Да           | Полугодие периода агрегации                                            |
| `data`           | array                  | Да           | Результаты по банкам                                                   |
| `taxData`        | object                 |              | Данные КГД                                                             |

**`data[]` - результат по банку:**

| Поле         | Тип                      | Обязательное | Описание                                                         |
| ------------ | ------------------------ | ------------ | ---------------------------------------------------------------- |
| `bankBIN`    | string (12 цифр)         | Да           | БИН банка                                                        |
| `bankBIC`    | string (8 символов)      | Да           | БИК банка                                                        |
| `bankName`   | string (до 256 символов) | Да           | Наименование банка                                               |
| `bankStatus` | string                   | Да           | Статус обработки в банке                                         |
| `accounts`   | array                    | Да           | Счета пользователя с суммами. Пустой, пока банк не передал счета |

**`data[].accounts[]` - счёт:**

| Поле                | Тип              | Обязательное | Описание                                                       |
| ------------------- | ---------------- | ------------ | -------------------------------------------------------------- |
| `accountId`         | string (uuid)    | Да           | Идентификатор банковского счёта (OBID)                         |
| `accountType`       | string           | Да           | Тип счёта: `CURRENT`                                           |
| `currency`          | string           | Да           | Валюта счёта по ISO 4217, например `KZT`                       |
| `total_card_mobile` | number (decimal) | Да           | Общая сумма входящих карточных и мобильных переводов за период |

**`taxData` - данные КГД:**

Данные сервиса КГД `910_NPK` (ЭСФ и ККМ), передаются в том виде, в каком получены.

| Поле          | Тип              | Обязательное | Описание                                       |
| ------------- | ---------------- | ------------ | ---------------------------------------------- |
| `status`      | string           | Да           | Статус запроса в КГД                           |
| `code`        | string           |              | Код результата КГД, например `000`             |
| `message`     | string           |              | Сообщение КГД                                  |
| `totalEsf`    | number (decimal) |              | Общая сумма по ЭСФ (электронные счета-фактуры) |
| `totalEsfFl`  | number (decimal) |              | Сумма ЭСФ по операциям с физическими лицами    |
| `zReportCash` | number (decimal) |              | Сумма наличных по Z-отчётам ККМ                |

**Коды ответов:** `200`, `202`, `400`, `401`, `403`, `404`, `405`, `406`, `429`, `500`.

***

### Поставщик API (банк)

Для интеграции банк реализует у себя `POST /v1/tax-income` и вызывает callback НПК.

#### `POST /v1/tax-income` - Принять запрос на агрегацию

**Реализуется на стороне банка.** Принимает асинхронный запрос на агрегацию доходов пользователя за период. Банк отвечает `202`, а результат передаёт позже через callback.

**Авторизация:** `OauthAccessTokenAuth`

**Тело запроса:**

| Поле            | Тип                | Обязательное | Описание                                                     |
| --------------- | ------------------ | ------------ | ------------------------------------------------------------ |
| `aggregationId` | string (uuid)      | Да           | Идентификатор агрегации, по которой нужно передать результат |
| `dateFrom`      | string (date-time) | Да           | Начало периода агрегации, ISO 8601                           |
| `dateTo`        | string (date-time) | Да           | Конец периода агрегации, ISO 8601                            |

```bash
curl --location 'https://bank.example.kz/v1/tax-income' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{bearerToken}}' \
--data '{"aggregationId": "<uuid>", "dateFrom": "2026-01-01T00:00:00+05:00", "dateTo": "2026-06-30T23:59:59+05:00"}'
```

**Ответ `202 Accepted`** - запрос принят в асинхронную обработку.

**Коды ответов:** `202`, `400`, `401`, `403`, `405`, `406`, `500`.

**Коды ошибок:**

| HTTP  | Код                  | Описание                                             |
| ----- | -------------------- | ---------------------------------------------------- |
| `400` | `FIELD_MISSING`      | Не передано поле или тело запроса                    |
| `400` | `FIELD_INVALID`      | Неверные или некорректные входные данные             |
| `400` | `HEADER_MISSING`     | Не передан обязательный заголовок                    |
| `400` | `HEADER_INVALID`     | Некорректный заголовок                               |
| `400` | `RESOURCE_NOT_FOUND` | Не используется, оставлен для обратной совместимости |
| `500` | `INTERNAL_ERROR`     | Внутренняя ошибка сервера                            |

Тело ошибки `400` и `500`: `requestId` (необязательное), `code`, `description`. Тело ошибки `401`, `403`, `405`, `406`: `requestId`.

***

#### `POST /v1/tax-income/aggregations/{aggregationId}/callback` - Передать результат

**Реализуется на стороне НПК, вызывается банком.** Банк передаёт статус обработки и, при успехе, список счетов пользователя с суммами.

**Авторизация:** `ProviderTokenAuth`

**Path-параметры:**

| Параметр        | Тип           | Описание                |
| --------------- | ------------- | ----------------------- |
| `aggregationId` | string (uuid) | Идентификатор агрегации |

**Тело запроса:**

| Поле         | Тип    | Обязательное | Описание                                                                            |
| ------------ | ------ | ------------ | ----------------------------------------------------------------------------------- |
| `bankStatus` | string | Да           | Статус обработки: `SUCCESS`, `ERROR`                                                |
| `accounts`   | array  | Да           | Счета пользователя с суммами. Пустой массив, если у пользователя нет счетов в банке |

Структура `accounts[]` - такая же, как в ответе `GET /v1/tax-income/aggregations/{aggregationId}`: `accountId`, `accountType`, `currency`, `total_card_mobile`.

```bash
curl --location 'https://api.npck.kz/v1/tax-income/aggregations/<uuid>/callback' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer {{providerToken}}' \
--data '{"bankStatus": "SUCCESS", "accounts": [{"accountId": "<uuid>", "accountType": "CURRENT", "currency": "KZT", "total_card_mobile": 150000.50}]}'
```

**Ответ `200 OK`** - результат принят и применён к агрегации.

**Коды ответов:** `200`, `400`, `401`, `404`, `405`, `406`, `500`.

***

### Статусы

**`TaxIncomeAggregationStatus`** - состояние агрегации целиком:

| Значение      | Описание              |
| ------------- | --------------------- |
| `IN_PROGRESS` | Агрегация выполняется |
| `COMPLETED`   | Агрегация завершена   |

**`TaxIncomeBankStatus`** - результат по конкретному банку в ответе `GET`:

| Значение      |
| ------------- |
| `SUCCESS`     |
| `NO_RESPONSE` |
| `ERROR`       |

**`TaxIncomeTaxDataStatus`** - статус запроса в КГД в `taxData.status`:

| Значение      |
| ------------- |
| `SUCCESS`     |
| `NO_RESPONSE` |
| `ERROR`       |

**`TaxIncomeCallbackBankStatus`** - то, что банк сообщает в callback:

| Значение  |
| --------- |
| `SUCCESS` |
| `ERROR`   |

{% hint style="info" %}
`NO_RESPONSE` означает и «банк (КГД) ещё не ответил», и «банк (КГД) не ответил до истечения срока».
{% endhint %}
