Распознать документы и селфи из массива изображений

POST /kyc/process

Описание

Метод определяет, выбирает и распознаёт документы и селфи из массива изображений. Позволяет загружать несколько файлов, выполнять OCR и сохранять результаты в сессии. Для доступа нужен токен, см. раздел «Авторизация».

Формат запроса

HTTP метод: POST
URL: /kyc/process
Тип контента: multipart/form-data

Авторизация

Токен передаётся одним из способов:

заголовок token: <jwt-token> — временный JWT-токен, полученный методом user/login;
поле token в теле запроса — постоянный API-токен (UUID) из личного кабинета.

Без токена запрос вернёт 401 access denied.

Параметры запроса

Параметр	Тип	Где передаётся	Обязательный	Описание
token	string	form-data	—	Постоянный API-токен (UUID), если нет заголовка `token`
images	array	form-data	✅	Изображения (файлы), от 1 до 10 в одном запросе
sessionId	string (UUID)	form-data	❌	Сессия, в которую загружаются изображения. Если не указан — создаётся новая сессия по `schemaId`
schemaId	string (UUID)	form-data	✅ для новой сессии	Идентификатор сценария. Обязателен, если не передан `sessionId` существующей сессии
mode	string	form-data	❌	Режим выполнения: ‘async’ или ‘sync’ (по умолчанию ‘sync’)
clientKey	string	form-data	❌	Ваш идентификатор клиента, до 36 символов. Без `sessionId` сессия ищется по нему; если сессии нет, новая создаётся по `schemaId` с этим ключом
clientUser	string	form-data	❌	Ваш идентификатор оператора, до 36 символов. Сохраняется в сессии и возвращается в её статусе
stepIndex	string	form-data	❌	Номер шага сценария, для которого предназначено изображение, с нуля — позиция шага в `results` сессии. Без него шаг выбирается автоматически. При нескольких изображениях поле повторяется для каждого изображения в том же порядке: либо для всех, либо ни для одного
ocr	boolean	form-data	❌	Выполнять OCR документов (по умолчанию true)

stepIndex

Номер задаётся строкой из цифр.
При нескольких изображениях число значений должно совпадать с числом изображений, номера не должны повторяться. Иначе — 400 [rest.kycProcess]: invalid schema с details по полю stepIndex.
Номер, который шаг не может принять, даёт 400 [request] invalid stepIndex: <причина>:

Причина	Значение
`out of range`	В сценарии нет шага с таким номером
`step kind mismatch`	Шаг другого вида, чем изображение (например, селфи на шаг документа)
`step closed`	Шаг уже пройден, попытки исчерпаны или достигнут предел критических ошибок

Отклонённый запрос не обрабатывает ни одного изображения и не меняет сессию. У сессии связанных сценариев до выбора сценария (selectedSchemaId равен null) только один шаг: первый документ отправляйте без номера или с 0.

Пример запроса (cURL)

curl -X POST "https://api.neuro-vision.ru/v1/kyc/process" -H "token: <jwt-token>" -F "images=@/path/to/passport.jpg" -F "images=@/path/to/selfie.jpg" -F "schemaId=660e8400-e29b-41d4-a716-446655440000" -F "ocr=true" -F "mode=sync"

Примеры ответов

Успех (200 OK)

Поле checks в результатах шагов — проверки на подделку; их названия и статусы описаны в разделе «Проверки на подделку (checks)» на странице Статус сессии.

{
  "sessionId": "00000000-0000-0000-0000-000000000000",
  "clientId": "00000000-0000-0000-0000-000000000000",
  "status": "success",
  "spent": 136.945,
  "results": [
    {
      "spent": 8.779,
      "status": "success",
      "type": "document",
      "docName": "GBR — Passport(2006)",
      "images": ["url"],
      "imagesFull": ["url"],
      "checks": [
        {
          "caption": "fraud",
          "items": [
            {
              "caption": "isEdited",
              "status": "success"
            }
          ]
        }
      ],
      "ocr": {
        "fields": [
          {
            "conf": "high",
            "title": "Surname",
            "value": "DOE"
          }
        ],
        "status": "success"
      },
      "errors": [
        "[document] text fields not visible"
      ]
    }
  ],
  "createdAt": "2025-05-21T08:15:46.972Z",
  "isClientNew": false
}

Успех (selfie & doc)

{
  "sessionId": "10000000-0000-0000-0000-000000000000",
  "clientId": "00000000-0000-0000-0000-000000000000",
  "status": "success",
  "spent": 36.11,
  "results": [
    {
      "status": "success",
      "type": "document",
      "spent": 4.453,
      "errors": [],
      "docName": "GBR — Passport (2006)",
      "checks": [
        {
          "caption": "fraud",
          "items": [
            {
              "status": "success",
              "caption": "isEdited"
            },
            {
              "status": "success",
              "caption": "isDisplay"
            },
            {
              "status": "success",
              "caption": "isPrinted"
            }
          ]
        }
      ],
      "ocr": {
        "status": "success",
        "fields": [
          {
            "title": "Surname",
            "value": "DOE",
            "conf": "high"
          }
        ]
      },
      "images": ["url_to_passport_image"],
      "imagesFull": ["url_to_full_passport_image"]
    },
    {
      "status": "success",
      "type": "selfie",
      "spent": 4.664,
      "errors": [],
      "docName": "GBR — Passport (2006)",
      "checks": [
        {
          "caption": "fraud",
          "items": [
            {
              "status": "success",
              "caption": "isEdited"
            }
          ]
        }
      ],
      "faceSelfie": "url_to_selfie_image",
      "faceDoc": "url_to_face_document_image",
      "withDoc": "passport",
      "images": ["url_to_selfie_image"],
      "imagesFull": ["url_to_full_selfie_image"]
    },
    {
      "status": "success",
      "type": "faces",
      "spent": 0.004,
      "errors": [],
      "checks": [
        {
          "caption": "Face matching",
          "items": [
            {
              "status": "success",
              "index": 0,
              "caption": "document_0 & selfie_document_1",
              "images": [
                "url_to_selfie_with_passport_image",
                "url_to_passport_image"
              ]
            },
            {
              "status": "success",
              "index": 1,
              "caption": "document_0 & selfie_2",
              "images": [
                "url_to_selfie_image",
                "url_to_passport_image_for_selfie_comparison"
              ]
            }
          ]
        }
      ]
    }
  ],
  "createdAt": "2025-05-21T08:15:46.975Z",
  "isClientNew": false
}

Ошибка (400)

{
  "status": "error",
  "message": "[rest.kycProcess]: invalid schema"
}

Ответ	Причина
400 `at least 1 image is required`	В запросе нет ни одного изображения
400 `[rest.kycProcess]: invalid schema`	Параметры не соответствуют описанию (например, `clientKey` или `clientUser` длиннее 36 символов); подробности — в `details`
400 `Maximum supported image size N Mb`	Изображение больше допустимого размера; `N` — текущий предел в мегабайтах
400 `bad schemaId`	Запрос создаёт сессию, но `schemaId` не передан
400 `[rest.kycProcess] no schema for request, please create at least 1`	Сценарий с переданным `schemaId` не найден в вашей учётной записи
400 `[request] invalid stepIndex: <причина>`	Шаг с указанным номером не может принять изображение, см. «stepIndex»
400	Больше 10 изображений в одном запросе
401 `access denied`	Нет токена или токен недействителен

Ошибка (failed)

{
  "sessionId": "00000000-0000-0000-0000-000000000000",
  "clientId": "",
  "status": "failed",
  "spent": 261.569,
  "results": [
    {
      "status": "failed",
      "type": "document",
      "spent": 0,
      "errors": [
        "[system] exception"
      ],
      "ocr": {
        "status": "idle",
        "fields": []
      }
    }
  ],
  "createdAt": "2025-05-21T08:15:46.980Z",
  "isClientNew": true
}