Создать верификацию

Назначение

Метод workflow-instances регистрирует верификацию по настроенному сценарию (workflow) и позволяет запустить одну или несколько проверок в одном запросе.

Сервис принимает запрос синхронно, валидирует входные данные и возвращает статус постановки задания в обработку. Итоговый результат получают отдельно через POST /api/v2/verifications/results или через callback.

Эндпоинт

Боевой контур:

POST https://api.mts.ru/ID-KYC-Verification-API-Prod/2.0/api/v2/verifications/workflow-instances

Prodlike:

POST https://api.mts.ru/ID-KYC-Verification-API-Prodlike/2.0/api/v2/verifications/workflow-instances

Авторизация

В запросе передается JWT-токен:

Authorization: Bearer <JWT>

Пример получения токена:

curl --location "https://api.mts.ru/token" \
  --header "Content-Type: application/x-www-form-urlencoded" \
  --header "Authorization: Basic <base64(ID клиента:Секрет клиента)>" \
  --data-urlencode "grant_type=client_credentials"

Тело запроса

Тело запроса содержит:

идентификатор сценария workflowId;
массив данных заявителей personalData;
версию сценария workflowVersion (опционально);
параметры callback.

Пример запроса

{
  "workflowId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "personalData": [
    {
      "verificationExternalId": "122222222009090003109000005",
      "applicantExternalId": "ivanov1999",
      "document": {
        "documentType": "passport",
        "countryCode": "RU",
        "series": "4939",
        "number": "200399",
        "firstName": "Андрей",
        "surname": "Семьянов",
        "middleName": "Владимирович",
        "birthdate": "1989-10-21",
        "sex": "male"
      },
      "userData": {
        "phone": "79276984837",
        "email": "test@mts.ru",
        "snils": "145-723-212 11"
      }
    }
  ],
  "callbackEnabled": true,
  "callbackUrl": "https://your-system.example.com/verification/callback"
}

Входные параметры

Атрибут	Тип	Описание	Комментарий
`workflowId`	string (UUID)	Идентификатор сценария верификаций	Обязательное. Предоставляется администратором.
`workflowVersion`	string (UUID)	Версия сценария	Опционально. Если не указано, используется последняя активная версия.
`personalData`	array	Массив данных заявителей	Обязательное. Минимум один элемент.
`verificationExternalId`	string	Внешний идентификатор верификации	Рекомендуется указывать для связки с вашей системой.
`applicantExternalId`	string	Внешний идентификатор заявителя	Генерируется на стороне клиента.
`document`	object	Данные документа	Обязательное.
`document.documentType`	enum	Тип документа	`passport`, `id`, `drvlic`, `foreign`, и др.
`document.countryCode`	string	Страна документа	Код страны, например `RU`.
`document.series`	string	Серия документа	Рекомендуется.
`document.number`	string	Номер документа	Рекомендуется.
`document.firstName`	string	Имя	Обязательное.
`document.surname`	string	Фамилия	Обязательное.
`document.middleName`	string	Отчество	При наличии.
`document.birthdate`	date	Дата рождения	Формат `YYYY-MM-DD`.
`document.sex`	enum	Пол	`male` / `female`.
`userData`	object	Данные клиента	Для ЕСИА и других проверок.
`userData.phone`	string	Номер телефона	Формат `7XXXXXXXXXX` (11 цифр).
`userData.email`	string	Email	Может использоваться для ЕСИА.
`userData.snils`	string	СНИЛС	Формат с дефисами.
`userData.inn`	string	ИНН	Без пробелов и дефисов.
`callbackEnabled`	boolean	Включение callback	Опционально. Если не указано, используется настройка из сценария.
`callbackUrl`	string	URL для callback	Опционально. Если не указан, используется URL из сценария.

Ответ

Метод возвращает результат приема заданий в обработку:

{
  "jobResults": [
    {
      "verificationExternalId": "1111111111",
      "verificationId": "b6c2f8a1-9e3d-4c5f-9a7b-1234567890ab",
      "jobStatus": "accepted",
      "errors": null
    },
    {
      "verificationExternalId": "222222222",
      "jobStatus": "notValid",
      "errors": {
        "document.firstName": [
          "'firstName' must not be empty."
        ]
      }
    }
  ]
}

Атрибут	Описание
`jobResults`	Массив результатов приема заданий.
`verificationExternalId`	Внешний идентификатор верификации (если был передан).
`verificationId`	Внутренний UUID верификации, сгенерированный системой.
`jobStatus`	Статус: `accepted` – принята в работу, `notValid` – ошибка валидации.
`errors`	Описание ошибок валидации (ключ – путь к полю, значение – массив ошибок).

Коды ответов

Код	Статус	Описание
`200`	`OK`	Запрос создан успешно.
`400`	Validation error	Невалидный запрос (отсутствует workflowId, некорректный формат даты, недопустимый тип документа).
`401`	Unauthorized	Недействительный или отсутствующий токен.
`404`	Not Found	Сценарий с указанным workflowId не найден или неактивен.

Что смотреть дальше

Получить результат – получить итог по verificationExternalId.
Callback – получить результат асинхронно.
CompletionStrategy – настроить момент завершения проверки.