> 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/nachalo-raboty.md).
# Начало работы
Добро пожаловать в документацию платформы НПЦК. Здесь вы найдёте всё необходимое для успешной интеграции — от первого запроса до production.
{% hint style="info" %}
**Оперативные уведомления** — плановые работы и обновления API публикуются в Telegram: [t.me/npckconnect](https://t.me/npckconnect)
{% endhint %}
### Сервисы платформы
### Быстрый старт
### Сервисы ЦОИД
{% tabs %}
{% tab title="🧪 Тестовая среда" %}
{% stepper %}
{% step %}
**Шаг 1 - Предоставление данных ЮЛ/ФЛ**
Вход в личный кабинет Портала НПК осуществляется посредством биометрической верификации с использованием цифрового сканирования лица пользователя - данные сотрудников должны быть предоставлены заранее.
Направьте письмо на соответствующий адрес:
| Проект | Email |
| ------------------------------------------------ | -------------- |
| ЦОИД, Облачная ЭЦП и агрегация счетов (Open API) | |
В письме укажите для каждого сотрудника:
1. Фотографию (формат как на удостоверение личности)
2. ФИО
3. ИИН
4. Номер телефона
5. БИН и наименование организации
6. Кто будет выступать руководителем на тестовом стенде
7. Систему, к которой планируете подключиться (ЦОИД, Open Banking/Open API)
{% hint style="warning" %}
В тестовой среде регистрация **первого руководителя организации не требуется** - руководителем может быть любой уполномоченный сотрудник.
{% endhint %}
{% endstep %}
{% step %}
**Шаг 2 - Регистрация и авторизация в Портале НПК**
Портал НПК (тестовая среда): [cabinet.stage.npck.kz](https://cabinet.stage.npck.kz)
Регистрацию выполняет сотрудник, назначенный руководителем:
1. Заполните форму авторизации и нажмите **Войти**
2. На форме подтверждения ИИН убедитесь, что введён корректный ИИН, и нажмите **Продолжить**
3. При положительном ответе от ГБД ФЛ проводится биометрическая верификация физического лица с использованием цифрового сканирования лица
{% hint style="warning" %}
Перед прохождением биометрической верификации убедитесь, что лицо полностью в кадре, взгляд направлен в камеру, глаза открыты, фон однородный, освещение равномерное без теней. При превышении количества неуспешных попыток система временно блокирует пользователя.
{% endhint %}
4. Введите одноразовый SMS-код
{% hint style="info" %}
На тестовом стенде SMS не отправляется - вводите код **`0000`**. Если код не пришёл - нажмите **Отправить код повторно**.
{% endhint %}
5. Введите **БИН** организации
6. Нажмите **Разрешить**
{% hint style="success" %}
Регистрация завершена! Руководителю открывается Личный кабинет участника.
{% endhint %}
{% endstep %}
{% step %}
**Шаг 3 - Добавление сотрудников**
**Сотрудники → Добавить сотрудника**:
1. Введите ИИН, ФИО и должность сотрудника
2. Выберите доступы по роли:
* Менеджеры / аналитики - все функции
* Технические специалисты - «Управление услугами» и «Управление заявками»
3. При необходимости - установите галочку «Право подписания юридических документов»
4. Нажмите **Добавить**
{% hint style="info" %}
Можно загрузить список сотрудников в формате CSV. Шаблон: [employees\_example.csv](https://cabinet.stage.npck.kz/assets/documents/employees_example.csv)
{% endhint %}
{% endstep %}
{% step %}
**Шаг 4 - Подача заявки на подключение к сервису**
{% tabs %}
{% tab title="🔐 FinID / ЦОИД и ✍️ Облачная ЭЦП" %}
1. Перейдите в раздел **Подключиться к ЦОИД**
2. Нажмите **Подать заявку**
3. Выберите тип сервиса
4. Прикрепите необходимые документы (перечень - в правилах функционирования ЦОИД на [npck.kz](https://npck.kz))
5. Нажмите **Отправить**
Статусы заявки: `черновик` → `в работе` → `одобрена` / `отказ`
{% hint style="info" %}
Если заявка отклонена - причина указана в деталях. Подайте новую заявку с исправлениями.
{% endhint %}
{% endtab %}
{% tab title="🏦 Open API" %}
1. Перейдите в раздел **Подключиться к Open Banking**
2. Нажмите **Подать заявку**
3. Выберите роль:
* **Поставщик API** - для обмена информацией по счетам
* **Пользователь API (чтение и запись)** - для агрегации счетов
4. Прикрепите документы (для тестовой среды достаточно лицензии на проведение банковских операций)
5. Нажмите **Отправить**
Статусы заявки: `черновик` → `в работе` → `одобрена` / `отказ`
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
**Шаг 5 - Регистрация приложения**
После одобрения заявки: **Услуги → Мои приложения → Добавить приложение**
* **Название** - наименование приложения
* **Redirect URL** - адрес для перенаправления после аутентификации (можно несколько)
* **Логотип** - PNG, 100×100 px (необязательно)
Нажмите **Сохранить**. Система сгенерирует `client_id` и `client_secret`.
{% hint style="danger" %}
`client_secret` - строго конфиденциально. Сохраните сразу - повторно просмотреть нельзя. При необходимости можно сгенерировать новый через **Сгенерировать новый client secret**.
{% endhint %}
{% endstep %}
{% step %}
**Шаг 6 - Настройка и тестирование API**
{% hint style="info" %}
Сервис сопоставления фотоизображений (IDEC/Photomatch) подключается отдельно от остальных сервисов ЦОИД - не через Портал НПК (cabinet.npck.kz), а через собственный контур регистрации Удостоверяющего центра. См. вкладку **«📷 Сопоставление фотоизображений»**.
{% endhint %}
{% tabs %}
{% tab title="🔐 FinID / ЦОИД" %}
**Реализуйте на своей стороне:**
1. Получение URL для перенаправления клиента - `POST /v1/auth/generate-user-url`
2. Перенаправление клиента на полученный URL через SafariWebView (iOS) или WebView (Android)
3. Перехват редиректа с кодом авторизации `code` на `redirectUri`
4. Обмен `code` на `access_token` - `POST /oauth2/token`
5. Проверка и анализ токена - `POST /oauth2/introspect`
{% hint style="warning" %}
**iOS:** только `SafariWebView`, `WKWebView` не поддерживается. Редирект перехватывать через deeplink.
**Android WebView:** если не отображается изображение с камеры при прохождении биометрической верификации:
```kotlin
webView.settings.allowContentAccess = true
webView.settings.mediaPlaybackRequiresUserGesture = false
webView.settings.domStorageEnabled = true
```
{% endhint %}
{% hint style="info" %}
На тестовом стенде SMS не отправляется - клиент вводит код **`0000`**.
Срок жизни URL - **15 минут**, кода авторизации - **300 секунд** (одноразовый).
Срок жизни `access_token` - **12 часов** для FinID scopes.
{% endhint %}
→ Спецификация: [auth-openapi.npck.kz](https://auth-openapi.npck.kz/#tag/Auth/operation/generateUserUrl)
→ Клиентский сценарий: [Описание клиентского пути FinID](https://docs.npck.kz/servisy-coid/servis-autentifikacii-lichnosti-klienta-finid/opisanie-klientskogo-puti)
{% endtab %}
{% tab title="✍️ Облачная ЭЦП" %}
**Реализуйте на своей стороне:**
1. Загрузите документы для подписания через API Esign до начала сессии
2. Получите URL для перенаправления клиента со scope `esign` (физлица) или `organization_esign` (юрлица)
3. Перенаправьте клиента через SafariWebView / WebView
4. Перехватите редирект с `code` и обменяйте на `access_token`
5. Получите подписанные документы
{% hint style="info" %}
Срок жизни `access_token` для scope `esign` / `organization_esign` - **5 минут**.
Если у клиента нет облачной ЭЦП - система предложит выпустить её прямо в flow. ЭЦП выпускается на **1 год**.
На тестовом стенде SMS - код **`0000`**.
{% endhint %}
{% hint style="warning" %}
Пароль от ЭЦП не хранится в системах ЦОИД - только его хэш в HSM. Клиент может сбросить пароль через «Не помню пароль» - при этом выпускается новая ЭЦП.
{% endhint %}
→ Спецификация: [esign-openapi.npck.kz](https://esign-openapi.npck.kz)
→ Клиентский сценарий: [Описание клиентского пути Esign](/servisy-coid/servis-upravleniya-oblachnoi-ecp-esign/opisanie-klientskogo-puti.md)
{% endtab %}
{% tab title="🏦 Open API" %}
**1. Настройка API (для Поставщика API)**
**Услуги → Мои API → Настройки API:**
* Введите URL-адрес, по которому будут доступны ваши API
* Заполните основную информацию о поставщике
* Нажмите **Перейти к публикации API**
{% hint style="warning" %}
Токен доступа (JWT) действует **1 год**. Хранить только на серверной стороне.
{% endhint %}
**2. Публикация API**
В разделе **Мои API** выберите нужный API из списка и нажмите **Активировать услугу**.
**3. Запуск автотестов**
После публикации API нажмите **Запустить проверку** рядом с нужным API.
Система запустит автоматические тесты и отобразит результат. Если выявлены ошибки - они будут показаны с описанием, исправьте согласно технической документации и запустите проверку повторно.
{% hint style="success" %}
Кнопка **Опубликовать** становится доступна только после успешного прохождения всех проверок.
{% endhint %}
**4. Тестирование (для Пользователя API)**
Реализуйте на своей стороне полный OAuth2 flow:
1. `POST /v1/auth/generate-user-url` со scopes `accounts`, `account_balance`, `account_transactions`
2. Перенаправление клиента → аутентификация (подтверждение ИИН + биометрическая верификация + SMS-код `0000`) → согласие
3. Получение `code` → обмен на `access_token` (срок жизни **30 дней**)
4. Запрос данных счетов: `GET /accounts`, `GET /accounts/{id}/balance`, `GET /accounts/{id}/transactions`
{% hint style="info" %}
API v2 устарел - используйте **API v3**.
{% endhint %}
→ Спецификация: [accounts-openapi.npck.kz](https://accounts-openapi.npck.kz)
→ [Рекомендации для Пользователя API](https://docs.npck.kz/open-banking/poluchenie-informacii-o-bankovskikh-schetakh-klienta-pilotnyi-proekt/rekomendacii-po-realizacii-integracii-dlya-polzovatelya-api)
→ [Рекомендации для Поставщика API](https://docs.npck.kz/open-banking/poluchenie-informacii-o-bankovskikh-schetakh-klienta-pilotnyi-proekt/rekomendacii-po-realizacii-integracii-dlya-postavshika-api)
{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}
{% endtab %}
{% tab title="🚀 Промышленная среда" %}
{% hint style="info" %}
Переходите в промышленную среду только после успешного тестирования и подписания протокола с АО «НПК».
{% endhint %}
{% stepper %}
{% step %}
**Шаг 1 - Регистрация и авторизация в Портале НПК**
Портал НПК (промышленная среда): [cabinet.npck.kz](https://cabinet.npck.kz)
В промышленной среде **предоставление данных сотрудников заранее не требуется** - верификация через ГБД ФЛ и ГБД ЮЛ автоматическая.
Регистрацию выполняет **первый руководитель** организации:
1. Откройте форму авторизации и нажмите **Войти**
2. Введите ИИН и нажмите **Продолжить**
3. Пройдите биометрическую верификацию
4. Введите SMS-код (отправляется реально на телефон)
5. Введите **БИН** организации
6. Нажмите **Разрешить**
{% hint style="success" %}
Регистрация завершена!
{% endhint %}
{% endstep %}
{% step %}
**Шаг 2 - Добавление сотрудников**
**Сотрудники → Добавить сотрудника** - те же шаги, что и в тестовой среде.
{% hint style="warning" %}
В промышленной среде один сотрудник может быть добавлен в личный кабинет только **одного** участника.
{% endhint %}
{% endstep %}
{% step %}
**Шаг 3 - Подача заявки на подключение**
{% tabs %}
{% tab title="🔐 FinID / ЦОИД и ✍️ Облачная ЭЦП" %}
1. **Подключиться к ЦОИД** → **Подать заявку**
2. Выберите тип сервиса, прикрепите документы, нажмите **Отправить**
{% hint style="warning" %}
`client_id` и `client_secret` в промышленной среде **отличаются** от тестовых.
{% endhint %}
{% endtab %}
{% tab title="🏦 Open API" %}
1. **Подключиться к Open Banking** → **Подать заявку**
2. Выберите роль, прикрепите документы, нажмите **Отправить**
{% hint style="warning" %}
`client_id` и `client_secret` в промышленной среде **отличаются** от тестовых.
{% endhint %}
{% endtab %}
{% endtabs %}
{% endstep %}
{% step %}
**Шаг 4 - Регистрация приложения**
**Услуги → Мои приложения → Добавить приложение**
* **Название**, **Redirect URL** (production-домен), **Логотип** (необязательно)
* Нажмите **Сохранить** → получите промышленные `client_id` и `client_secret`
{% hint style="danger" %}
`client_secret` отображается только один раз. Сохраните сразу.
{% endhint %}
{% endstep %}
{% step %}
**Шаг 5 - Настройка подключения и публикация API**
{% tabs %}
{% tab title="🔐 FinID / ЦОИД и ✍️ Облачная ЭЦП" %}
Клиентский сценарий идентичен тестовому - SMS отправляется реально.
1. Выполните smoke-тест с промышленными `client_id` / `client_secret`
2. Проверьте логирование и мониторинг на своей стороне
→ [Результаты биометрической аутентификации](https://docs.npck.kz/servisy-coid/rezultaty-biometricheskoi-autentifikacii)
→ [Матрица полномочий (для юрлиц, Esign)](https://docs.npck.kz/servisy-coid/servis-upravleniya-oblachnoi-ecp-esign/dlya-podpisaniya-dokumentov-yuridicheskimi-licami/matrica-polnomochii)
{% endtab %}
{% tab title="🏦 Open API" %}
**1. Настройка и публикация API**
**Услуги → Мои API → Настройки API** → укажите production endpoint → **Перейти к публикации API**.
Подайте заявку на публикацию - требуется **подписанный протокол тестирования**. Срок рассмотрения - **3 рабочих дня**.
**2. Smoke-тест**
Выполните smoke-тест с промышленными ключами, проверьте логирование и мониторинг.
→ [Статус API участников](https://docs.npck.kz/open-banking/poluchenie-informacii-o-bankovskikh-schetakh-klienta-pilotnyi-proekt/servis-polucheniya-statusa-api-uchastnikov)
{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}
***
### Сервис сопоставления фотоизображений
Сервис предназначен для дистанционной идентификации физических лиц путем сопоставления фотоизображения клиента с эталонным из государственных источников данных.
{% hint style="warning" %}
Аутентификацию могут пройти люди, у которых имеется как минимум один из следующих документов:
* удостоверение личности гражданина РК
* паспорт гражданина РК
* вид на жительство иностранца в РК
* удостоверение лица без гражданства (казахстанского образца)
{% endhint %}
{% hint style="info" %}
Для использования сервиса Участник должен:
1. Пройти процедуру регистрации на Портале АО «НПК» (см. [Регистрация и авторизация в Портале НПК](https://docs.npck.kz/rabota-s-testovym-okruzheniem-is-npk/rabota-s-testovym-portalom-npk/registraciya-i-avtorizaciya-v-portale-npk))
2. Подать заявку на подключение к ЦОИД (см. 5.1 Подключение к ЦОИД)
3. Зарегистрировать приложение Участника (см. [Пользователям API (добавление и использование приложения)](https://docs.npck.kz/rabota-s-testovym-okruzheniem-is-npk/rabota-s-testovymi-servisami/polzovatelyam-api-dobavlenie-i-ispolzovanie-prilozheniya))
{% endhint %}
***
{% tabs %}
{% tab title="🧪 Тестовая среда" %}
{% stepper %}
{% step %}
**Шаг 1 - Получение криптографических ключей**
Перейдите на портал УЦ: [betacms.npck.kz/info](https://betaca.kisc.kz/downloads/res-open/primer.zip), скачайте шаблон заявки и направьте заполненную заявку согласно инструкции на портале.
→ Подробнее: [Выпуск ключей ГОСТ 2015](https://docs.npck.kz/servisy-coid/servis-sopostavleniya-fotoizobrazhenii/vypusk-klyuchei-gost-2015)
{% hint style="info" %}
По вопросам получения ключей: [**supportca@npck.kz**](mailto:supportca@npck.kz) или **+7 (727) 250-66-75**
{% endhint %}
{% endstep %}
{% step %}
**Шаг 2 - Выполните первый запрос**
Авторизация по схеме Basic Auth:
```
Authorization: Basic
```
{% tabs %}
{% tab title="Синхронный метод" %}
Используется для моментальной верификации личности с заранее определённым типом согласия. Согласие **собирается Участником** перед началом процедуры идентификации и **подписывается ЭЦП организации** (JWS, алгоритм ГОСТ 34.10-2012/2015).
→ Подробнее о формировании подписи: [Формирование ЭЦП JWS](https://docs.npck.kz/servisy-coid/servis-sopostavleniya-fotoizobrazhenii/formirovanie-ecp-jws)
```bash
curl -X POST https://api.stage.npck.kz/v2/identity/sync/verify \
-H "Authorization: Basic " \
-H "Content-Type: application/json" \
-H "x-jws-signature: " \
-d '{
"iin": "123456789012",
"photo": "",
"vendor": "VISIONLABS",
"consentType": "BIOMETRY",
"serviceCode": "ACCOUNT_OPEN",
"dataScope": ["iin"],
"consentTypes": ["CT_01"],
"consentGivenAt": "2019-08-24T14:15:22Z",
"consentExpiresAt": "2019-08-24T14:15:22Z",
"dataRetentionPeriod": 1
}'
```
В ответ возвращается результат сопоставления в процентах (%).
**Получение электронного документа по результатам:**
```bash
curl -X GET https://api.stage.npck.kz/v1/identity/report/{verificationId}/download \
-H "Authorization: Basic "
```
→ Спецификация: [identity-openapi.npck.kz](https://identity-openapi.npck.kz/#tag/Identity/operation/syncVerifyV2)
{% endtab %}
{% tab title="Асинхронный метод" %}
Используется для запуска процесса верификации, который требует подтверждения от физического лица посредством **SMS с номера 1414**. Номер телефона берётся из базы мобильных граждан (БМГ).
{% hint style="info" %}
В тестовой среде SMS не отправляется - согласие имитируется через Telegram-бот [@NPCK\_TestControl\_bot](https://t.me/NPCK_TestControl_bot): нажмите **/start**, введите ИИН.
{% endhint %}
```bash
curl -X POST https://api.stage.npck.kz/v1/identity/async/verify \
-H "Authorization: Basic " \
-H "Content-Type: application/json" \
-H "x-jws-signature: " \
-d '{
"iin": "123456789012",
"photo": "",
"vendor": "VISIONLABS"
}'
```
{% hint style="danger" %}
Если клиент отклонил согласие - сопоставление не производится. Участник получает соответствующий статус в ответе.
{% endhint %}
→ Спецификация: [identity-openapi.npck.kz](https://identity-openapi.npck.kz/#tag/Identity/operation/asyncVerify)
{% endtab %}
{% endtabs %}
{% endstep %}
{% endstepper %}
{% endtab %}
{% tab title="🚀 Промышленная среда" %}
{% hint style="info" %}
Переходите в промышленную среду только после успешного тестирования.
{% endhint %}
{% stepper %}
{% step %}
**Шаг 1 - Заключение договора**
Заключите «Договор с Участником (сопоставление фотоизображений)».
Шаблон: [npck.kz - Типовые договора](https://npck.kz/tipovye-dogovory-coid/) - вкладка «Типовые договора» - «Договор с Участником (сопоставление фотоизображений)»
{% hint style="success" %}
Регистрация участника в ИС ЦОИД произойдёт **автоматически** после заключения договора.
{% endhint %}
По вопросам заключения договора: [**coid@npck.kz**](mailto:coid@npck.kz) или **+7 (727) 297-91-44**
{% endstep %}
{% step %}
**Шаг 2 - Получение криптографических ключей**
Заполните Приложение №1 к Заявлению/Соглашению к Договору о предоставлении услуг УЦ и направьте в Удостоверяющий центр.
Портал УЦ: [cms.npck.kz/auth](https://cms.npck.kz/auth)
{% hint style="warning" %}
Первичные ключи действуют **14 дней** и требуют ежегодного переоформления.
{% endhint %}
По вопросам: [**supportca@npck.kz**](mailto:supportca@npck.kz) или **+7 (727) 250-66-75**
{% endstep %}
{% step %}
**Шаг 3 - Настройка сетевого доступа**
Доступ к промышленной среде осуществляется через выделенный канал **IP VPN** или **IPSec**.
Сканированный вариант заполненного шаблона необходимо направить на [**info@npck.kz**](mailto:info@npck.kz):
* IP VPN - [шаблон письма](https://npck.kz/wp-content/uploads/2025/06/shablon-dlya-podcluc-kanala-ip-vpn-rus-1.docx)
* IPSec - [шаблон письма](https://npck.kz/wp-content/uploads/2025/06/shablon-ipsec-rus-1.docx)
{% endstep %}
{% step %}
**Шаг 4 - Выполните первый запрос**
Используйте те же методы, что и в тестовой среде, с промышленными ключами:
* **Sync V2:** `https://api.npck.kz/v2/identity/sync/verify`
* **Async V1:** `https://api.npck.kz/v1/identity/async/verify`
{% hint style="success" %}
Интеграция завершена! По вопросам: [**coid@npck.kz**](mailto:coid@npck.kz) или **+7 (727) 297-91-44**
{% endhint %}
{% endstep %}
{% endstepper %}
{% endtab %}
{% endtabs %}
### Спецификации
| Сервис | Ссылка |
| --------------------------- | -------------------------------------------------------------------------- |
| Auth (FinID, OAuth2, Esign) | [auth-openapi.npck.kz](https://auth-openapi.npck.kz/) |
| Esign | [esign-openapi.npck.kz](https://esign-openapi.npck.kz/) |
| Open Banking ID | [obid-openapi.npck.kz](https://obid-openapi.npck.kz/) |
| Accounts | [accounts-openapi.npck.kz](https://accounts-openapi.npck.kz/) |
| Identity | [identity-openapi.npck.kz](https://identity-openapi.npck.kz/#tag/Identity) |