Вопросы
bss@qiwi.com
NAV Navbar
Примеры

IDENTIFICATION API

Общие сведения

API предназначен для проведения идентификации физических лиц. Подробности см. в разделе «Руководства по интеграции» → «Идентификация».

Используемые в тексте термины описаны в разделе «Руководства по интеграции» → «Термины и бизнес-сущности».

Доступ к API

Для успешного вызова методов API необходимы:

Авторизация

Авторизация должна передаваться во всех запросах в заголовке Authorization:

Authorization: Bearer {token}

Для получения токенов обратитесь к вашему сопровождающему менеджеру.

Шифрование запросов с персональными данными

Для запросов, в которых передаются персональные данные, нужно использовать HTTPS-протокол со специально настроенным шифрованием в соответствии с ГОСТ Р 34.10-2012 и 34.11-2012. Такие запросы нужно отправлять на соответствующие URL-адреса.

Формирование URL запроса

URL-адрес любого запроса к API складывается из двух компонент: server URL и путь конкретного запроса.

Значения server URL перечислены далее. Эндпоинты запросов указаны в их описании.

Запросы, в которых передаются персональные данные

К ним относятся запросы разделов Упрощенная онлайн-идентификация и Получение персональных данных клиента.

Адреса server URL:

Запросы, в которых не передаются персональные данные

Адреса server URL:

Упрощенная онлайн-идентификация

Процесс упрощённой идентификации описан в разделе «Руководства по интеграции» → «Идентификация» → «Сценарии» → «Упрощённая идентификация».

Создание заявки

Запрос → POST

Атрибуты тела запроса

Создание заявки (тело запроса)

{
  "firstName" : "Имя",
  "lastName" : "Фамилия",
  "middleName" : "Отчество",
  "birthDate" : "11.01.1996",
  "citizenshipCountryId" : "RU",
  "contacts" : {
    "mobilePhoneNumber" : "+79271234567",
    "email" : "email@email.com"
  },
  "identifyingDocument" : {
    "type" : "RUSSIAN_INNER_PASSPORT",
    "series" : "9208",
    "number" : "556900"
  },
  "secondaryDocuments" : [ {
    "type" : "INN",
    "number" : "33701000015"
  } ],
  "clientDeviceFingerprint" : {
    "IPv4" : "10.12.11.290"
  }
}
Имя Тип Описание
birthDate String Дата рождения. Формат: ДД.ММ.ГГГГ. Допустимый диапазон: от 14 до 100 лет включительно
citizenshipCountryId String Гражданство. Всегда значение RU
clientDeviceFingerprint object Сведения о клиентском устройстве, с которого поступил запрос
clientDeviceFingerprint.IPv4 String IP-адрес клиентского устройства, с которого поступил запрос
contacts object Контактные данные клиента
contacts.email String e-mail
contacts.mobilePhoneNumber String Номер мобильного телефона в международном формате
firstName String Имя. Минимум две буквы, допустимо использование тире
lastName String Фамилия. Минимум две буквы, допустимо использование тире
middleName String Отчество. Минимум две буквы, допустимо использование тире
identifyingDocument object Сведения о документе, удостоверяющем личность
identifyingDocument.type String Тип документа. Всегда значение RUSSIAN_INNER_PASSPORT
identifyingDocument.number String Номер документа. Формат: 6 цифр
identifyingDocument.series String Серия документа. Формат: 4 цифры
secondaryDocuments array Дополнительные документы. В массиве можно передавать объекты ИНН или СНИЛС

Атрибуты ответа

Ответ на создание заявки

{
  "firstName" : "Имя",
  "lastName" : "Фамилия",
  "middleName" : "Отчество",
  "birthDate" : "11.01.1996",
  "citizenshipCountryId" : "RU",
  "contacts" : {
    "mobilePhoneNumber" : "+79271234567",
    "email" : "email@email.com"
  },
  "identifyingDocument" : {
    "type" : "RUSSIAN_INNER_PASSPORT",
    "series" : "9208",
    "number" : "556900"
  },
  "secondaryDocuments": [
    {
      "type" : "INN",
      "number" : "500100732259"
    }
  ],
  "id" : "1234ABCD4321",
  "creationDateTime" : "2019-01-11T17:16:05.743+03:00",
  "applicationStatus" : "IN_PROGRESS",
  "identificationLevel" : "NOT_VERIFIED",
  "productId" : "111222",
  "personId" : "1"
}
Имя Тип Описание
applicationStatus String Статус (состояние) заявки. Возможные значения
birthDate String Дата рождения. Формат см. в описании запроса
citizenshipCountryId String Гражданство. ID из справочника стран
contacts object Контактные данные клиента
contacts.email String e-mail
contacts.mobilePhoneNumber String Номер мобильного телефона
creationDateTime String Дата создания заявки
firstName String Имя
lastName String Фамилия
middleName String Отчество
id String ID заявки
identificationLevel String Текущий уровень идентификации. Возможные значения
identificationLevelReasonCode String Код причины полученного уровня идентификации
identifyingDocument object Сведения о документе, удостоверяющем личность
identifyingDocument.number String Номер документа
identifyingDocument.series String Серия документа
identifyingDocument.type String Тип документа
personId String ID клиента
productId String ID продукта
secondaryDocuments array Массив дополнительных документов

Получение статуса заявки

Запрос → GET

Структура тела ответа идентична структуре ответа на запрос «Создание заявки».

Получение статуса всех заявок

Запрос → GET

Тело ответа — json-массив объектов-заявок. Структура каждого объекта-заявки идентична структуре ответа на запрос «Создание заявки».

Полная идентификация

Процесс полной идентификации описан в разделе «Руководства по интеграции» → «Идентификация» → «Сценарии» → «Полная идентификация».

Поиск заявок на идентификацию

Запрос → GET

Атрибуты объекта-заявки

Запрос поиска

GET /v1/full-identification/applications/search?
productId=agent-ident&flowType=AGENT_FILLED_ONLY_FULL_IDENTIFICATION&mobilePhoneNumber=%2B79071234567 HTTP/1.1
Accept: application/json
Authorization: Bearer YUu2qw048gtdsvlk3iu
Host: <server URL>

В ответе возвращается json-массив объектов-заявок.

Объект-заявка

{
  "id" : "A171EB8417CE11E99124DD04D7207C6E",
  "creationDateTime" : "2019-01-13T11:29:44.943+03:00",
  "applicationStatus" : "AWAITING_PASSPORT_CONFIRMATION",
  "identificationLevel" : "NOT_VERIFIED",
  "maximumPossibleIdentificationLevel" : "FULL",
  "productId" : "111222",
  "identificationDataSource" : {
    "identificationAgentName" : "Евросеть",
    "identificationEndpoint" : {
      "fullAddress" : "г. Москва, ул. Гранатная, 1, оф. 2"
    }
  },
  "firstName" : "И***",
  "lastName" : "Ф***",
  "middleName" : "О***",
  "citizenshipCountryId" : "RU",
  "contacts" : {
    "mobilePhoneNumber" : "+79271234567",
    "email" : null
  }
}
Имя Тип Описание
applicationStatus String Статус (состояние) заявки. Возможные значения
citizenshipCountryId String Гражданство. ID из справочника стран
contacts object Контактные данные клиента
contacts.email String e-mail
contacts.mobilePhoneNumber String Номер мобильного телефона в международном формате
creationDateTime String Дата создания заявки
id String ID заявки
identificationLevel String Текущий уровень идентификации. Возможные значения
firstName String Имя
lastName String Фамилия
middleName String Отчество
maximumPossibleIdentificationLevel String Максимально допустимый уровень идентификации. Возможные значения
personId String ID клиента
productId String ID продукта
identificationDataSource object Источник идентификационных данных
identificationDataSource.
identificationAgentName
String Название агента идентификации
identificationDataSource.
identificationEndpoint
object Точка идентификации
identificationDataSource.
identificationEndpoint.fullAddress
String Адрес точки идентификации, в которой клиент оставил заявку

Создание сессии подтверждения SIM-карты

Запрос инициирует отправку SMS-сообщения с OTP (One Time Password, одноразовый пароль) клиенту на указанный номер телефона.

Запрос → PUT

Атрибуты тела запроса

Тело запроса

{
  "personId" : "1",
  "mobilePhoneNumber" : "+79271234567",
  "clientDeviceFingerprint" : {
    "IPv4" : "10.12.11.290"
  }
}
Имя Тип Описание
clientDeviceFingerprint object Сведения о клиентском устройстве, с которого поступил запрос
clientDeviceFingerprint.IPv4 String IP-адрес клиентского устройства, с которого поступил запрос
mobilePhoneNumber String Номер мобильного телефона в международном формате
personId String ID клиента

Атрибуты ответа

Тело ответа

{
  "resendDelay" : "PT3M",
  "resendAttemptsLeft" : 3
}
Имя Тип Описание
resendAttemptsLeft integer Количество оставшихся попыток повторного запроса OTP
resendDelay String Интервал времени, через который можно повторно запросить OTP

Повторная отправка SMS-сообщения с OTP

Запрос → POST

Атрибуты тела запроса

Тело запроса повторной высылки SMS

{
  "personId" : "1",
  "clientDeviceFingerprint" : {
    "IPv4" : "10.12.11.290"
  }
}
Имя Тип Описание
clientDeviceFingerprint object Сведения о клиентском устройстве, с которого поступил запрос
clientDeviceFingerprint.IPv4 String IP-адрес клиентского устройства, с которого поступил запрос
personId String ID клиента

Атрибуты ответа

Тело ответа

{
  "resendDelay" : "PT3M",
  "resendAttemptsLeft" : 3
}
Имя Тип Описание
resendAttemptsLeft integer Количество оставшихся попыток повторного запроса OTP
resendDelay String Интервал времени, через который можно повторно запросить OTP

Подтверждение SIM-карты с OTP

Запрос → PUT

Атрибуты тела запроса

Тело запроса подтверждения SIM-карты

{
  "personId" : "1",
  "confirmationCode" : "233210",
  "clientDeviceFingerprint" : {
    "IPv4" : "10.12.11.290"
  }
}
Имя Тип Описание
clientDeviceFingerprint object Сведения о клиентском устройстве, с которого поступил запрос
clientDeviceFingerprint.IPv4 String IP-адрес клиентского устройства, с которого поступил запрос
confirmationCode String OTP (One Time Password, одноразовый пароль)
personId String ID клиента

Атрибуты ответа

Тело ответа

{
  "applicationStatus" : "AWAITING_PASSPORT_CONFIRMATION"
}
Имя Тип Описание
applicationStatus String Статус (состояние) заявки. Возможные значения

Подтверждение заявки по 4 знакам документа

Запрос → PUT

Атрибуты тела запроса

Тело запроса подтверждения заявки

{
  "personId" : "1",
  "passportNumberLast4Characters" : "4300",
  "clientDeviceFingerprint" : {
    "IPv4" : "10.12.11.290"
  }
}
Имя Тип Описание
clientDeviceFingerprint object Сведения о клиентском устройстве, с которого поступил запрос
clientDeviceFingerprint.IPv4 String IP-адрес клиентского устройства, с которого поступил запрос
passportNumberLast4Characters String Последние 4 знака номера документа, удостоверяющего личность
personId String ID клиента

Атрибуты ответа

Тело ответа

{
  "applicationStatus" : "IN_PROGRESS"
}
Имя Тип Описание
applicationStatus String Статус (состояние) заявки. Возможные значения

Получение персональных данных клиента

По умолчанию персональные данные будут маскированными. Если по какой-то причине вам нужны немаскированные данные, обратитесь к вашему сопровождающему менеджеру.

Запрос → GET

Ответ

[
  {
    "productId": "1",
    "personId": "8",
    "productIdentificationLevel": "SIMPLIFIED",
    "bankAlias": "QIWI_BANK",
    "firstName": "и***",
    "lastName": "и***",
    "middleName": "и***",
    "citizenshipCountryId": "RU",
    "contacts": {
        "mobilePhoneNumber": "+7***",
        "email": null
    },
    "identifyingDocument": {
        "type": "RUSSIAN_INNER_PASSPORT",
        "series": "3***",
        "number": "1***"
    }
  }
]

JSON-массив объектов с персональными данными.

Атрибуты объекта:

Имя Тип Описание
productId String ID продукта
personId String ID клиента
productIdentificationLevel String Текущий уровень идентификации у партнера. Возможные значения
productIdentificationLevelReason String Код причины полученного уровня идентификации
bankAlias String Акроним системы, в которой клиент получил идентификацию
firstName String Имя
lastName String Фамилия
middleName String Отчество
birthDate String Дата рождения клиента (в формате ГГГГ-ММ-ДД)
birthPlace String Место рождения клиента
contacts object Контактные данные клиента
contacts.email String e-mail
contacts.mobilePhoneNumber String Номер мобильного телефона в международном формате
citizenshipCountryId String Гражданство. ID из справочника стран
identifyingDocument object Информация о документе, удостоверяющем личность
identifyingDocument.number String Номер документа. Формат: 6 цифр
identifyingDocument.series String Серия документа. Только для граждан РФ. Формат: 4 цифры
identifyingDocument.issueDate String Дата выдачи документа (в формате ДД.ММ.ГГГГ)
identifyingDocument.issuingAuthorityCode String Код подразделения, выдавшего документ
identifyingDocument.issuingAuthorityName String Название подразделения, выдавшего документ
identifyingDocument.expiryDate String Срок действия документа (в формате ДД.ММ.ГГГГ)
identifyingDocument.type String Тип документа. Возможные значения
identifyingDocument.
otherDocumentTypeName
String Название документа, если выбран тип документа OTHER
isPassportExpired Bool Признак просроченного паспорта (если true)
isClientActive Bool Признак активности клиента: true — клиент активен; false — клиент неактивен
registrationType String Тип регистрации: PERMANENT — постоянная, TEMPORARY — временная
registrationAddress object Сведения об адресе регистрации
registrationAddress.countryId String ID из справочника стран
registrationAddress.zipCode String Почтовый индекс
registrationAddress.okatoRegionCode String Код субъекта РФ по ОКАТО. Значение из справочника регионов
registrationAddress.district String Район
registrationAddress.cityType String Тип населенного пункта
registrationAddress.city String Наименование населенного пункта
registrationAddress.street String Улица
registrationAddress.house String Номер дома (владения)
registrationAddress.building String Номер корпуса (строения)
registrationAddress.flat String Номер квартиры (офиса)
livingAddressIsIdenticalToRegistrationAddress Bool Признак того, что адрес проживания совпадает с адресом регистрации
livingAddress object Сведения об адресе фактического проживания. Структура объекта совпадает с registrationAddress
secondaryDocuments array Массив дополнительных документов
hasInterestOwner Bool Признак выгодоприобретателя
hasBeneficialOwner Bool Признак того, что лицо является бенефициарным владельцем
publicOfficial Bool Признак публичного должностного лица
publicOfficialType String Тип публичного должностного лица: RUSSIAN — российское, FOREIGN — иностранное, INTERNATIONAL — международное
publicOfficialPost String Занимаемая должность публичного должностного лица
financialPosition String Сведения о финансовом положении: GOOD — хорошее, SUFFICIENT — удовлетворительное, BAD — плохое
businessReputation String Сведения о деловой репутации: GOOD — положительная, BAD — негативная
fundingSources String Сведения об источниках происхождения денежных средств и (или) иного имущества клиента: OWN_FUNDS — собственные средства, BORROWED_FUNDS — заемные средства, OTHER — иное

Деактивация клиента

Сценарий деактивации описан в разделе «Руководства по интеграции» → «Идентификация» → «Сценарии» → «Деактивация».

Запрос → POST

Атрибуты тела запроса

Тело запроса

{
    "deactivationDateTime": "2018-09-24T10:00:00+03:00",
    "deactivationReason": "Здесь причина деактивации клиента"
}
Имя Тип Описание
deactivationDateTime String Дата/время деактивации клиента (по стандарту ISO 8601)
deactivationReason String Причина деактивации клиента

Тело ответа отсутствует.

В случае успешного выполнения возвращается код ответа сервера 204. При повторной деактивации уже неактивного клиента возвращается код ответа сервера 400.

Дополнительные документы

ИНН

Атрибуты

ИНН

{
  "type" : "INN",
  "number" : "500100732259"
}
Имя Тип Описание
number String ИНН
type String Тип документа. Передавать значение INN

СНИЛС

Атрибуты

СНИЛС

{
  "type" : "SNILS",
  "number" : "112-233-445 95"
}
Имя Тип Описание
number String СНИЛС
type String Тип документа. Передавать значение SNILS

Разрешение на проживание

Атрибуты

Разрешение на проживание

{
  "type" : "RESIDENCE_PERMIT",
  "residencePermitType" : "VISA",
  "number" : "N4321",
  "dateFrom" : "11.09.2015",
  "dateTo" : "11.09.2021",
  "issuingAuthorityName" : "МИД РФ"
}
Имя Тип Описание
dateFrom String Дата выдачи
dateTo String Дата окончания действия документа
issuingAuthorityName String Орган, выдавший документ, подтверждающий право на пребывание в РФ
number String Номер документа
residencePermitType String Вид разрешения на пребывание. Значения: VISA, PERMANENT_RESIDENCE_PERMIT, TEMPORARY_RESIDENCE_PERMIT
type String Тип документа. Передавать значение RESIDENCE_PERMIT

Миграционная карта

Атрибуты

Миграционная карта

{
  "type" : "MIGRATION_CARD",
  "serial" : "4321",
  "number" : "43211234",
  "dateFrom" : "11.09.2015",
  "dateTo" : "11.09.2021"
}
Имя Тип Описание
dateFrom String Дата начала срока пребывания
dateTo String Дата окончания срока пребывания
number String Номер
serial String Серия
type String Тип документа. Передавать значение MIGRATION_CARD

Патент на работу

Атрибуты

Патент на работу

{
  "type" : "WORKING_PATENT",
  "series" : "77",
  "number" : "8843211234",
  "issuingAuthorityName" : "ФМС",
  "issueDate" : "11.09.2015",
  "documentSeries" : "РА",
  "documentNumber" : "4000123"
}
Имя Тип Описание
documentNumber String Номер бланка документа
documentSeries String Серия бланка документа
issueDate String Дата выдачи
issuingAuthorityName String Орган, выдавший патент
number String Номер
series String Серия
type String Тип документа. Передавать значение WORKING_PATENT

Справочники

Справочник стран (гражданств)

Запрос → GET

Справочник стран (фрагмент)

[
  {
    "id": "AF",
    "name": "АФГАНИСТАН"
  },
  {
    "id": "AL",
    "name": "АЛБАНИЯ"
  }
]

В ответе приходит json-массив со списком стран.

Имя Тип Описание
id String ID страны
name String Название страны

Справочник регионов России

Запрос → GET

В ответе приходит json-массив со списком регионов РФ.

Справочник регионов России (фрагмент)

[
  {
    "okatoRegionCode": "79",
    "name": "Республика Адыгея"
  },
  {
    "okatoRegionCode": "84",
    "name": "Республика Алтай"
  }
]
Имя Тип Описание
name String Название региона
okatoRegionCode String Код субъекта РФ по ОКАТО

HTTP-статусы и формат ответов

Код Описание Тело ответа
200 OK (запрос успешно выполнен) Тело успешного ответа
201 Created (запрос успешно выполнен, ресурс создан) Тело успешного ответа
204 No Content (запрос успешно выполнен) Тело ответа отсутствует
400 Bad Request (некорректный запрос) Стандартный json ошибки
401 Unauthorized (в запросе отсутствует корректная авторизация) Пустое тело, либо стандартный json ошибки
403 Forbidden (операция запрещена) Стандартный json ошибки
404 Not Found (ресурс не найден) Пустое тело, либо стандартный json ошибки
422 Unprocessable Entity (ошибка валидации запроса) Стандартный json ошибки
423 Locked (временно заблокирован) Стандартный json ошибки
500 Internal Server Error (внутренняя ошибка сервера) Пустое тело, либо стандартный json ошибки

Атрибуты описания ошибки

Стандартный json ошибки

{
    "serviceName": "openapi-identification",
    "errorCode": "internal.error",
    "description": "Undefined error. Please try to make operation later.",
    "userMessage": "Undefined error. Please try to make operation later.",
    "dateTime": "2018-09-03T18:41:27.016+03:00",
    "traceId": "4a3c694ca580a5e0"
}
Имя Тип Описание
serviceName String Название сервиса, возвратившего ошибку
errorCode String Код ошибки (см. далее)
description String Описание ошибки
userMessage String Пользовательское описание ошибки
dateTime String Дата и время формирование ответа
traceId String Параметр, необходимый для анализа логов. Его значение также всегда присутствует в заголовке ответа X-B3-TraceId

При возвращении ошибки валидации запроса в JSON-объекте может присутствовать объект cause. В объекте дополнительно описывается, какие ошибки и для каких полей были допущены.

Ошибка с полем cause

{
    "serviceName": "openapi-identification",
    "errorCode": "validation.error",
    "description": "Данные некорректны",
    "userMessage": "Данные некорректны",
    "dateTime": "2018-09-05T13:55:57.897+03:00",
    "traceId": "c8d2b66274672789",
    "cause": {
        "birthDate": [
            "may not be null"
            ]
    }
}

Возможные коды ошибок (атрибут errorCode):

Код Описание
internal.error Внутренняя ошибка сервиса
http.message.conversion.failed Ошибка десериализации сообщения
validation.error Ошибка валидации (некорректное тело запроса)
forbidden.operation Операция запрещена
data.not.found Данные не найдены
inapplicable.operation Операция не применима для сущности в ее текущем состоянии
secondary.document.invalid Некорректный второй документ
application.in.progress.already.exists В данный момент есть незавершенная заявка, которая находится в обработке, или ожидании получения всех данных
invalid.confirmation.factor.value Неверное значение фактора подтверждения
passport.confirmation.attempts.exceeded Превышено количество попыток подтверждения паспорта
sim.confirmation.attempts.exceeded Превышено количество попыток подтверждения sim-карты
confirmation.session.expired Время жизни сессии подтверждения истекло
incorrect.confirmation.code.error Неверный OTP (One Time Password, одноразовый пароль)
confirmation.attempts.limit.exceeded.error Попытки подтверждения исчерпаны
operation.inapplicable Операция не применима
incorrect.request.parameter Неверный параметр запроса
invalid.confirmation.data Неверные данные подтверждения

Значения перечислимых атрибутов

Статусы заявки

Статус Описание
PROCESSING_FINISHED Обработка завершена
IN_PROGRESS В процессе обработки
AWAITING_PRODUCT_CHECKS Ожидается завершение проверок
AWAITING_SIM_CONFIRMATION Ожидается подтверждение сим-карты
AWAITING_PASSPORT_CONFIRMATION Ожидается подтверждение идентификации
AWAITING_AGENT_VERIFICATION Ожидается верификация заявки у агента (для заявок на сайте)

Типы документов, удостоверяющих личность

Тип Описание
RUSSIAN_INNER_PASSPORT Внутренний паспорт РФ
FOREIGN_COUNTRY_IDENTIFYING_DOCUMENT Документ, удостоверяющий личность иностранного гражданина, выданный его государством
TEMPORARY_RESIDENCE_PERMIT Разрешение на временное проживание
PERMANENT_RESIDENCE_PERMIT Вид на жительство
REFUGEE_CERTIFICATE Удостоверение беженца
OTHER Иной документ

Код причины полученного уровня идентификации

Список значений полей identificationLevelReasonCode, productIdentificationLevelReason.

Код Описание
smev.personal.data.not.found Данные клиента не найдены в СМЭВ
smev.personal.data.invalid Данные клиента не прошли проверку в СМЭВ
simplified.secondary.documents.constraints.validation.failed Упрощенная идентификация: невалидный второй документ
simplified.secondary.documents.missing Упрощенная идентификация: отсутствует второй документ
general.constraints.validation.failed Ошибка валидации
person.is.unreliable Переданные персональные данные обнаружены в списках ограничений
passport.expired Паспорт просрочен
full.identification.exists У клиента уже есть полная идентификация
one.passport.accounts.limit.exceeded Превышено ограничение на максимальное количество аккаунтов на один паспорт
person.account.is.deactivated Аккаунт клиента уже закрыт
personal.data.not.accepted Клиенту нельзя предоставить идентификацию согласно текущим правилам
identification.application.is.expired Срок жизни незаполненной заявки истек
passport.confirmation.attempts.exceeded Превышено количество попыток подтверждения паспорта
sim.confirmation.attempts.exceeded Превышено количество попыток подтверждения sim-карты
personal.data.and.level.cannot.be.updated.by.submitted.application Заявка нарушает правила обновления существующего клиента при повышении уровня или повторном прохождении идентификации

Уровень идентификации

Список значений полей identificationLevel, productIdentificationLevel.

Уровень Описание
SIMPLIFIED Упрощенная
FULL Полная
NOT_VERIFIED Не идентифицирован