> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Верификация через цифровой ID-кошелёк: API

> Didit позволяет верифицировать личность через цифровой ID-кошелёк из вашего приложения, без создания сценария верификации.

Используйте специальный эндпоинт кошельков, чтобы верифицировать человека из вашего приложения.
Создавать или публиковать сценарий и передавать `workflow_id` не нужно.
Ваш бэкенд запускает верификацию и получает её результат, а ваш интерфейс проводит человека через обязательную аутентификацию в кошельке.

> [!NOTE]
>
> Интеграция через API по-прежнему требует, чтобы человек прошёл аутентификацию и подтвердил передачу своих данных личности.
> Без этого взаимодействия верифицировать человека, отправив только его личный идентификатор, нельзя.

## Как работает верификация

1. Ваш бэкенд проверяет [каталог кошельков](https://docs.didit.me/ru/standalone-apis/digital-id-wallet-catalog.md), затем вызывает эндпоинт запуска доступного кошелька, используя API-ключ вашего приложения.
2. Didit возвращает справочный номер верификации и действие, которое должен выполнить человек.
3. Ваше приложение открывает страницу аутентификации или показывает инструкции кошелька по подтверждению.
4. Человек проходит аутентификацию в своём кошельке.
5. Ваш бэкенд получает подтверждённый результат и обрабатывает уведомления о завершении.

Аутентификация в кошельке выполняется асинхронно.
Успешный запрос на запуск означает, что аутентификация начата, но не означает, что личность подтверждена.
Всегда проверяйте итоговый результат, прежде чем считать человека верифицированным.

## Интеграция на стороне бэкенда

Используйте [Список цифровых ID-кошельков](https://docs.didit.me/ru/standalone-apis/digital-id-wallet-catalog.md), чтобы получить актуальные эндпоинты, обязательные поля и доступность кошельков для вашего приложения.

Храните `x-api-key` на своём бэкенде.
Не размещайте его в браузерном бандле или мобильном приложении.
Для каждой новой попытки верификации используйте отдельный `Idempotency-Key`, а при повторе того же запроса на запуск передавайте этот же ключ.
Изменение запроса при повторном использовании ключа считается конфликтом, а не новой попыткой верификации.

У каждого кошелька есть собственный URL запуска, например `/v3/id-verification/wallets/ftn/` для Finnish Trust Network.
`request_id` идентифицирует автономную верификацию для последующих операций.
Используйте `vendor_data` для собственной ссылки или идентификации, до 2 000 байт в UTF-8, а `metadata` для необязательного JSON-объекта.
Оба поля возвращаются вместе с результатом и webhook о завершении.

| Операция | Эндпоинт |
| - | - |
| Получить статус и результат | `GET /v3/id-verification/wallets/verifications/{request_id}/` |
| Проверить подтверждение по телефону | `POST /v3/id-verification/wallets/verifications/{request_id}/poll/` |
| Отправить ответ кошелька Digital Credentials | `POST /v3/id-verification/wallets/verifications/{request_id}/response/` |
| Отменить ожидающую верификацию | `POST /v3/id-verification/wallets/verifications/{request_id}/cancel/` |

Эти операции используют API-ключ приложения, которое запустило верификацию.
Опрос и доступность аутентификации зависят от выбранного кошелька.

Отмена отклоняет ожидающую верификацию без оплаты и возвращает завершённую верификацию без изменений.
Для Smart-ID и Mobile-ID отмена, поступившая во время проверки подтверждения, ожидает завершения этого опроса несколько секунд.
Затем верификация отклоняется или возвращается со статусом `verified`, если человек уже подтвердил её.
Верификацию, которую человек завершает в этот момент, отменить нельзя: ответ будет `409` с `error: "verification_in_progress"` и заголовком `Retry-After`.
Повторите запрос через указанное в заголовке количество секунд, чтобы получить завершённый результат.

## Регистрация адреса возврата

Кошельки с перенаправлением возвращают человека в ваше приложение после аутентификации.
Зарегистрируйте точное имя хоста до запуска верификации:

```bash theme={null}
curl --request PATCH \
  --url https://verification.didit.me/v3/webhook/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"allowed_return_hosts": ["app.example.com"]}'
```

Затем передайте в запросе на запуск HTTPS-`return_url`, например `https://app.example.com/identity/complete`.
В `allowed_return_hosts` указывайте только имена хостов, без схемы, пути и подстановочных знаков.
Регистрируйте каждый используемый поддомен отдельно, до 20 хостов.
Обновление `allowed_return_hosts` заменяет зарегистрированный список, поэтому включите все имена хостов, которые хотите сохранить.
`GET /v3/webhook/` возвращает текущий список; см. [Конфигурация webhook](https://docs.didit.me/ru/sessions-api/management-api.md#настройка-webhook).
Для регистрации адреса возврата не нужны ни сценарий, ни домен White label.
Адресом возврата служит страница возврата в браузере, а webhook о завершении настраивайте отдельно для вашего бэкенда.

## Пример: Finnish Trust Network

После регистрации имени хоста для возврата запустите верификацию Finnish Trust Network:

```bash theme={null}
curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/ftn/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "FIN",
    "return_url": "https://app.example.com/identity/complete",
    "vendor_data": "your-customer-reference"
  }'
```

Сохраните возвращённый `request_id` и перенаправьте браузер человека на `wallet_verification.next_action.url`, когда его `type` равен `redirect`.
После возврата человека получите результат с вашего бэкенда:

```bash theme={null}
curl --request GET \
  --url https://verification.didit.me/v3/id-verification/wallets/verifications/REQUEST_ID/ \
  --header 'x-api-key: YOUR_API_KEY'
```

Проверьте `wallet_verification.outcome`:

| Исход | Значение |
| - | - |
| `pending` | Аутентификация ещё выполняется. |
| `verified` | Аутентификация завершена, а возвращённые данные личности подтверждены. |
| `cancelled` | Человек или ваше приложение отменили попытку. |
| `timeout` | Время на аутентификацию истекло. |
| `failed` | Аутентификация или проверка данных личности не удалась. |

Используйте данные личности только тогда, когда исход равен `verified`, а `simulated` равен `false` для реальной проверки личности.
Ответ в статусе ожидания может содержать следующее действие; в итоговых ответах нет следующего действия.

## Варианты аутентификации

**Кошельки с перенаправлением** возвращают URL аутентификации.
Откройте этот URL в браузере пользователя, дайте ему пройти процесс аутентификации в кошельке и вернуть его на зарегистрированный адрес назначения.
Результат читайте на своём бэкенде, а не доверяйте параметру возвратного URL как доказательству личности.

**Smart-ID и Mobile-ID** используют запрос на подтверждение на телефоне пользователя.
Ваш интерфейс собирает нужный персональный идентификатор; Mobile-ID также требует связанный номер телефона.
Покажите код сравнения и попросите пользователя подтвердить вход только в том случае, если он совпадает с кодом на его телефоне.
PIN-код вводится в окне кошелька или телефона, но никогда не вводится в вашей форме и не передаётся в API-запросе.
Опрашивайте статус со своего бэкенда с интервалом, указанным в возвращённом `poll_interval_seconds`, чтобы получать обновления о запросе.
Didit также в фоновом режиме проверяет ожидающие подтверждения на телефоне, поэтому уведомление о завершении может поступить на ваш webhook уже после того, как пользователь закроет вашу страницу.

**Google Wallet** запрашивается с вашей страницы или из вашего приложения через Digital Credentials API, без перенаправления; см. [Кошельки Digital Credentials (Google Wallet)](#кошельки-digital-credentials-google-wallet).

Доступный способ взаимодействия зависит от выбранного кошелька.
Не предполагайте, что каждый кошелёк поддерживает встроенную форму, QR-код или аутентификацию без браузера.

## Кошельки Digital Credentials (Google Wallet)

Google Wallet запрашивается непосредственно с вашей веб-страницы или из Android-приложения с помощью W3C Digital Credentials API.
Перенаправления нет, страницы, размещённой Didit, нет, и QR-кода Didit нет.
Кошелёк доступен в продакшн-среде и в песочнице.
Приложениям в песочнице регистрация не нужна. Каждое продакшн-приложение регистрируется один раз в консоли (шаг «Верификация личности», строка Google Wallet, **Зарегистрироваться в Google**), прежде чем сможет использовать Google Wallet.
Актуальный список того, что ваше приложение может запустить прямо сейчас, см. в [Список цифровых ID-кошельков](https://docs.didit.me/ru/standalone-apis/digital-id-wallet-catalog.md).

**1. Начните с вашего origin**

Ваш бэкенд вызывает `POST /v3/id-verification/wallets/google-wallet/` с `country` пользователя (`USA`, `GBR`, `BRA`, `SGP` или `TWN`) и `origin`, с которого будет запрашиваться кошелёк.
Параметр `origin` представляет собой HTTPS-origin вашей страницы, например `https://app.example.com`, хост которого должен быть одним из ваших [зарегистрированных имён хостов для возврата](#регистрация-адреса-возврата) или доменом вашего White label.
Для Android-приложения это `android:apk-key-hash:`, после которого идёт base64-представление SHA-256 сертификата подписи вашего приложения, без символов заполнения.
Кошелёк отклоняет запрос, сделанный с любого другого origin.
Параметра `return_url` нет.

```bash theme={null}
curl --request POST \
  --url https://verification.didit.me/v3/id-verification/wallets/google-wallet/ \
  --header 'x-api-key: YOUR_API_KEY' \
  --header 'Idempotency-Key: your-unique-attempt-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "country": "USA",
    "origin": "https://app.example.com",
    "vendor_data": "your-customer-reference"
  }'
```

**2. Запросите кошелёк в рамках действия пользователя**

Ответ содержит `wallet_verification.interaction = "digital_credentials"` и `next_action.type = "request_digital_credential"`.
Передайте `next_action.digital_credentials.request` браузеру или Android Credential Manager по нажатию или клику на том `origin`, с которого вы начали.
В десктопном браузере, если кошелёк находится на другом устройстве, браузер показывает собственный QR-код.

**3. Отправьте то, что вернул кошелёк**

Передайте полученные `{protocol, data}` на свой бэкенд, а оттуда отправьте их в `POST /v3/id-verification/wallets/verifications/{request_id}/response/` в виде `{"response": {...}}`.
Запрос можно отправить только один раз; повторная отправка возвращает уже принятое решение по верификации.

**4. Получите результат**

Ответ на отправку содержит принятое решение по верификации.
Прочитать его можно также через `GET /v3/id-verification/wallets/verifications/{request_id}/` или получить в webhook о завершении.

В браузере запрашивайте кошелёк из обработчика клика:

```javascript theme={null}
// start = the JSON your backend returned from the start request
const request = start.wallet_verification.next_action.digital_credentials.request;

button.addEventListener("click", async () => {
  try {
    const credential = await navigator.credentials.get({ digital: request });
    // Send {protocol, data} to your backend, which calls POST .../response/ with your API key.
    await fetch("/api/wallet-response", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        request_id: start.request_id,
        response: { protocol: credential.protocol, data: credential.data },
      }),
    });
  } catch (error) {
    // NotAllowedError or AbortError: the person cancelled. NotSupportedError: this browser cannot ask the wallet.
    console.error(error.name);
  }
});
```

Предлагайте этот способ только там, где браузер его поддерживает, например когда `"DigitalCredential" in window` возвращает true.
`navigator.credentials.get` должен вызываться в рамках действия пользователя, поэтому вызывайте его из обработчика клика, а не после асинхронного шага.

На Android используйте Jetpack Credential Manager (`androidx.credentials` версии 1.5.0 или новее) с тем же запросом:

```kotlin theme={null}
val option = GetDigitalCredentialOption(
    requestJson = JSONObject(request).toString(), // next_action.digital_credentials.request
)
val result = credentialManager.getCredential(activity, GetCredentialRequest(listOf(option)))
val credentialJson = (result.credential as DigitalCredential).credentialJson // {"protocol": ..., "data": {...}}
// Send credentialJson, parsed as JSON, to your backend as the "response" body.
```

Ошибки, которые нужно обработать:

| Ошибка | Где | Значение |
| - | - | - |
| `origin_invalid` | Начало, `400` | `origin` не является HTTPS-origin или origin Android-приложения. |
| `origin_not_allowed` | Начало, `400` | Хост origin не зарегистрирован для вашего приложения. Добавьте его в `allowed_return_hosts`. |
| `not_a_digital_credentials_wallet` | Отправка, `409` | Эта верификация не принимает ответ от кошелька. |

Верификация учётных данных, не прошедших проверку, является принятым решением с результатом `failed`, а не ответом с ошибкой.
Из кошелька передаются только те поля, которые запросила верификация, а результат содержит атрибуты личности, которые вернул кошелёк.
ID-пропуск Google Wallet и мобильное водительское удостоверение штата США не возвращают портретное фото.

В приложении в песочнице процесс имитируется с теми же шагами, и в ответе возвращается `simulated: true`.
Любой отправленный ответ принимает решение по верификации в соответствии с `sandbox_scenario`, поэтому вы можете реализовать полный сценарий в браузере или приложении без настоящего учётного документа.

## Webhook-уведомления о завершении

Настройте адрес назначения webhook на уровне приложения для события `status.updated` по [руководству по интеграции webhook](https://docs.didit.me/ru/integration/webhooks.md).
Для описанной здесь структуры решения используйте `webhook_version: "v3"`.
Проверяйте подпись webhook на своём бэкенде, прежде чем его обрабатывать.
`session_id` в webhook совпадает с `request_id`, который возвращает API кошельков.
Завершённая идентификация через кошелёк появляется в массиве `decision.id_verifications` webhook с `verification_method: "wallet"`.
Тот же идентификатор можно использовать, чтобы получить результат через специализированный API кошельков.

Обрабатывайте уведомления об одобрении и отклонении, включая уведомления об отменённых и истёкших верификациях.
Делайте обработчик webhook идемпотентным, потому что для неудачных доставок выполняются повторные попытки.
Возврат из браузера не является webhook о завершении, а параметры его строки запроса не служат доказательством личности.

## Возвращаемые данные идентификации

Используйте нормализованные поля идентификационных данных для имён и дат рождения, если эти поля возвращаются.
Атрибуты, специфичные для кошелька, описывают сведения о личности, которые передаёт выбранный кошелёк.
Доступные атрибуты зависят от кошелька и страны.
Успешная аутентификация личности не означает, что портрет, адрес или любой другой запрошенный атрибут доступен.

## Тестирование в песочнице

Приложение в режиме песочницы Didit имитирует верификацию через кошелёк без обращения к провайдеру кошелька и без списания кредитов.
В ответе такие запросы помечаются `wallet_verification.simulated: true`.
Имитированное одобрение содержит тестовые данные, а не подтверждённую реальную личность.

Для кошелька с перенаправлением перейдите по возвращённому URL, чтобы проверить обратный вызов и возврат в ваше приложение.
Для Smart-ID или Mobile-ID используйте endpoint опроса, чтобы завершить имитированное одобрение; уведомление на телефон не отправляется.
Чтобы проверить обработку ошибок, при создании запроса задайте `sandbox_scenario` со значением `wallet_cancelled`, `wallet_timeout` или `wallet_provider_error`.
Боевые приложения отклоняют `sandbox_scenario`.

Имитация в песочнице Didit отделена от тестирования в собственной тестовой среде провайдера.
Успешная имитация не подтверждает доступ к боевому провайдеру и доступность в продакшене.

### Песочница провайдера ConnectID

Песочница провайдера ConnectID использует тестовые банки и отделена от имитации в песочнице Didit.
Если для вашей интеграции настроен доступ к песочнице провайдера, передайте `authorisation_server_id` выбранного банка в [начальный endpoint ConnectID](https://docs.didit.me/ru/api-reference/digital-id-wallets/connectid.md).
Используйте ID, который возвращает селектор банков ConnectID; не отправляйте URL банка или произвольного эмитента.
Если поле не указано, выбирается тестовый банк по умолчанию.
Это поле относится только к ConnectID и не меняет запрашиваемые атрибуты личности.

Начальный набор запрашивает имя, фамилию и дату рождения.
Следуйте возвращённому `next_action`, чтобы пройти аутентификацию, затем получите или опросите результат верификации.
Только завершённый результат со статусом «одобрена» подтверждает успешную верификацию; возврат в ваше приложение этого не подтверждает.
ConnectID остаётся в статусе **Скоро** в продакшене, пока завершаются онбординг и сертификация.

## Доступность и цены

Покрытие endpoint'ов и активация кошелька в продакшене не связаны между собой.
Страница справочника API для кошелька может существовать, при этом аутентификация в продакшн-среде через него недоступна.
Перед внедрением боевого сценария проверьте покрытие кошелька по странам и его статус в продакшене.

Опубликованные тарифы и доступность см. в разделе [цены на цифровые ID-кошельки](https://docs.didit.me/ru/getting-started/pricing.md#цены-на-цифровые-кошельки-удостоверений-личности).
Верификация через кошелёк тарифицируется отдельно от захвата документов.

## Выбор интеграции

Используйте эти API, если хотите сами управлять интерфейсом и логикой приложения.
Используйте [Sessions API](https://docs.didit.me/ru/sessions-api/create-session.md), если нужны размещённый сценарий верификации Didit, правила сценария и настроенные резервные шаги.
Оба подхода всё равно требуют процесса аутентификации и согласия, предусмотренного кошельком.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.