Ревью (ручная проверка)

Раздел Ревью админ-панели предназначен для обработки верификационных сессий, направленных на ручную проверку. Операторы просматривают документы и данные аппликантов, выносят решения об одобрении или отклонении верификации, оставляют внутренние комментарии.

Интеграторы (server-to-server): та же очередь доступна в Tenant API: /tenant/v1/kyc/review-tasks и /tenant/v1/kyb/review-tasks (scopes reviews:* / kyb.reviews:*). См. Задачи ревью (Tenant API).

Пути ниже относятся к admin API (/admin/v1/...), не к Tenant API.

Очередь задачCopy Anchor Link

Очередь отображает список задач (сессий), ожидающих ручной проверки или находящихся в работе. Для каждой задачи указаны: идентификатор сессии, дата поступления, текущий статус и назначенный оператор.

ФильтрацияCopy Anchor Link

Для управления очередью доступны следующие фильтры:

• По статусу задачи — новая (ожидает назначения), в работе, одобрена, отклонена.
• По назначенному оператору — отображение задач конкретного оператора или нераспределённых задач.
• По дате — выбор временного диапазона поступления задач.

Статистика очередиCopy Anchor Link

В заголовке раздела отображаются сводные показатели:

• Количество задач, ожидающих назначения.
• Количество задач в работе.
• Общее число обработанных задач за текущий период.

Работа с задачейCopy Anchor Link

При открытии задачи оператор получает доступ к следующей информации:

Данные сессии и аппликантаCopy Anchor Link

• Идентификатор сессии и аппликанта.
• Данные, извлечённые из документа (ФИО, дата рождения, номер документа — при наличии OCR).
• Внешний идентификатор пользователя (external_user_id).

ДокументыCopy Anchor Link

• Загруженные изображения документов и селфи с возможностью просмотра в полном размере.
• Результаты автоматических проверок: подлинность документа, качество изображения, соответствие лица.

История проверокCopy Anchor Link

• Хронология прохождения шагов верификации.
• Результаты автоматических проверок (document check, liveness, face match, AML).

Действия оператораCopy Anchor Link

Назначение задачиCopy Anchor Link

• Назначить на себя — оператор берёт задачу в работу. Статус задачи изменяется на «В работе».
• Переназначить — передача задачи другому оператору (например, при необходимости привлечения специалиста с расширенными полномочиями).

Вынесение решенияCopy Anchor Link

• Одобрить — верификация считается пройденной. Сессия получает статус approved.
• Отклонить — верификация не пройдена. Сессия получает статус rejected. При отклонении необходимо:
  1. Выбрать причину отклонения из структурированного списка (GET /admin/v1/review/reject-reasons), например blurry_document, face_not_matching, suspected_fraud или expired_document.
  2. При необходимости ввести дополнительный комментарий с пояснением.

Канонические reject-коды совпадают с Tenant API (полный список: Задачи ревью).

Изменение приоритета задачиCopy Anchor Link

Через PATCH /admin/v1/review/tasks/{task_id}/priority оператор с соответствующими правами может изменить приоритет задачи (например, для срочных VIP-кейсов). Действие фиксируется в журнале аудита как review.priority_updated.

Делегирование задачиCopy Anchor Link

Через POST /admin/v1/review/tasks/{task_id}/delegate оператор может делегировать задачу команде OneKYC. Текущий статус делегирования: GET /admin/v1/review/tasks/{task_id}/delegation-status.

КомментарииCopy Anchor Link

Оператор может добавить внутренний комментарий через POST /admin/v1/review/tasks/{task_id}/comments. Комментарии доступны другим операторам и сохраняются в истории задачи для целей аудита и передачи контекста.

Доступ к загруженным документамCopy Anchor Link

Для просмотра конкретного документа аппликанта используется GET /admin/v1/review/tasks/{task_id}/documents/{document_id}/url — возвращается подписанная ссылка с ограниченным сроком действия.

Статистика по очередиCopy Anchor Link

Сводные показатели по задачам ревью доступны через GET /admin/v1/review/stats (или очередь GET /admin/v1/review/queue с scope kyc / kyb).

Запрос пересдачи (Resubmit Requests)Copy Anchor Link

Если автоматические проверки прошли, но при ручном просмотре оператор обнаруживает, что какое-то поле документа нечитаемо (блики, размытие, обрезанный кадр, не тот документ, просрочен и т. п.), он может запросить у пользователя повторную загрузку конкретного шага, не отклоняя сессию целиком. Это сохраняет конверсию и избавляет пользователя от повторного прохождения всей верификации с нуля.

Сценарий использованияCopy Anchor Link

1. Оператор открывает задачу в очереди ревью и видит, что фото лицевой стороны документа размыто.
2. Вместо отклонения оператор нажимает «Запросить пересдачу», выбирает шаг (например, document_capture) и код причины (blurry).
3. Сессия переходит в состояние awaiting_resubmit, выбранный шаг сбрасывается.
4. Пользователь получает уведомление и открывает flow повторно — он попадает сразу на сброшенный шаг с пояснением причины.
5. После успешной повторной загрузки сессия автоматически возвращается в очередь ревью.

Коды причин (reason_code)Copy Anchor Link

Доступные коды причин:

Эти же коды используются в webhook payload и в сообщении, которое видит пользователь.

Лимиты и TTLCopy Anchor Link

• По умолчанию не более 3 запросов на сессию. При попытке создать четвёртый возвращается 409 Conflict с кодом conflict.
• После развёртывания соответствующих версии backend и схемы утверждённым изменением БД можно задать flow_review_tasks.resubmit_limit_override от 4 до 10 для одной задачи. Изменение нужно зафиксировать в операционном аудите. NULL сохраняет лимит по умолчанию. История пересдач остаётся нетронутой; считаются запросы в любом статусе.
• TTL — 7 дней. По истечении этого срока запрос автоматически переводится в статус expired, а сессия закрывается с финальным статусом rejected (если других каналов завершения не было).
• Не более одного активного запроса на пару (session, step) одновременно. Повторная попытка возвращает 409 Conflict с кодом resubmit_already_pending.
• Сессия должна быть активна для resubmit в ручном ревью. Сессии в in_progress принимаются. Завершённая сессия также может быть принята, если она находится в сценарии ручного ревью/resubmit; backend атомарно переоткрывает её и сбрасывает выбранный шаг. Запросы к pending, paused, failed, cancelled или expired возвращают 409 Conflict с кодом session_not_in_progress.
• Повторно сдавать можно только шаги, где пользователь может выполнить действие. Текущий allowlist: document, selfie, phone_otp, email_otp, kyb_company_input, kyb_business_document, kyb_beneficiary_kyc.

EndpointsCopy Anchor Link

Создать запрос пересдачиCopy Anchor Link

POST /admin/v1/review/tasks/{task_id}/request-resubmit
Content-Type: application/json

{
  "step_id": "550e8400-e29b-41d4-a716-446655440000",
  "reason_code": "blurry",
  "client_message": "Пожалуйста, переснимите документ при дневном свете без бликов",
  "internal_notes": "Поле даты рождения нечитаемо из-за бликов"
}

• step_id — UUID конкретного шага flow, который нужно сбросить.
• reason_code — обязательное поле из канонического списка выше.
• client_message (опц.) — текст, который увидит пользователь.
• internal_notes (опц.) — внутренняя заметка для других операторов; не отображается пользователю.

Ответ (200 OK):

{
  "data": {
    "request_id": "550e8400-e29b-41d4-a716-446655440099",
    "task_id": "550e8400-e29b-41d4-a716-446655440010",
    "status": "pending",
    "reason_code": "blurry",
    "expires_at": "2026-05-04T10:00:00Z"
  }
}

Действие фиксируется в журнале аудита (review.decided + decision=request_resubmit + reason_code).

Получить список запросов на задачуCopy Anchor Link

GET /admin/v1/review/tasks/{task_id}/resubmits

Возвращает все запросы пересдачи на данную задачу (включая завершённые / истёкшие / отменённые), отсортированные по дате создания.

Жизненный цикл запросаCopy Anchor Link

Переход pending → fulfilled происходит автоматически после того, как пользователь повторно проходит запрошенный шаг.

Доставка уведомлений пользователюCopy Anchor Link

OneKYC доставляет уведомление о запросе пересдачи через доступные пользователю каналы:

1. WebSocket push — мгновенно, если у пользователя открыт флоу верификации.
2. Email / SMS — отправляется, когда пользователю нужна ссылка для возврата к сессии вне открытой страницы верификации.

Webhook-событияCopy Anchor Link

При создании / выполнении запроса OneKYC отправляет webhook-события:

• verification.resubmit_requested — оператор запросил повторную загрузку. Payload включает session_id, flow_id, applicant_id, step_id, step_type, reason_code, client_message, attempt_number, requested_by_id, requested_by_name, expires_at.
• verification.resubmit_fulfilled — пользователь выполнил повторную загрузку. Payload включает session_id, flow_id, applicant_id, step_id, reason_code, attempt_number, fulfilled_at.

Полные схемы payload — в разделе Вебхуки API.

Результат обработкиCopy Anchor Link

После вынесения решения:

• Сессия получает финальный статус (approved или rejected).
• Результат доступен через Tenant API и отправляется на настроенные вебхуки (события verification.approved / verification.declined).
• Решение, причина отклонения и комментарии фиксируются в журнале аудита.

Вебхуки комментариев ревьюCopy Anchor Link

Новый комментарий к задаче KYC создаёт событие verification.comment.created, к задаче KYB — kyb.review.comment.created. Одинаковый контракт действует для админки клиента, платформенной консоли ревью и клиентского API. Комментарий не меняет решение проверки и не завершает сессию.

Подпишитесь на нужный тип события. Существующие подписки * также получают новые события. Используются обычные подпись вебхука, фильтрация sandbox/production, повторные попытки и журнал доставок. Возможны повторные доставки: устраняйте дубли по id события или idempotency_key. Порядок получения не гарантирован.

Поле data содержит scope, task_id, session_id, flow_id, external_id и объект comment с полями id, content, created_at, author_type. Для KYC передаётся applicant_id, для KYB — business_id, если он задан. Типы авторов: admin_user, superadmin_user, api_key, system. Идентификаторы и имена сотрудников в вебхук не включаются.

Пример данных события для KYC:

{
  "scope": "kyc",
  "task_id": "550e8400-e29b-41d4-a716-446655440010",
  "session_id": "550e8400-e29b-41d4-a716-446655440001",
  "flow_id": "550e8400-e29b-41d4-a716-446655440002",
  "external_id": "customer_123",
  "applicant_id": "550e8400-e29b-41d4-a716-446655440099",
  "comment": {
    "id": "550e8400-e29b-41d4-a716-446655440011",
    "content": "Please provide a clearer document photo.",
    "created_at": "2026-10-16T08:00:00.123456Z",
    "author_type": "admin_user"
  }
}

Все комментарии задачи доступны клиенту-интегратору. Внутренние заметки решения internal_notes и сообщение повторной загрузки client_message — отдельные поля; они не создают события комментариев. События создаются только для новых комментариев; исторические комментарии не рассылаются.

Получение комментариев: GET /tenant/v1/kyc/review-tasks/{task_id}/comments с правом reviews:read или GET /tenant/v1/kyb/review-tasks/{task_id}/comments с правом kyb.reviews:read. Создание: POST по тому же пути с соответствующим правом записи. Успешный ответ создания дополнен comment_id и created_at, совпадающими с сохранённым комментарием и снимком в вебхуке. Каждый успешный POST создаёт новый комментарий; дедупликация вебхука не делает повторные запросы создания идемпотентными. При неопределённом результате запроса сверяйтесь с API комментариев до повторной отправки.

Комментарий, событие и запись outbox сохраняются одной транзакцией. Ошибка сохранения события откатывает создание комментария. HTTP-доставка выполняется асинхронно после фиксации транзакции: успешный ответ создания не подтверждает доставку вебхука клиенту; проверяйте журнал доставок.