# Задачи ревью (manual review API)

Методы Tenant API для **серверного ручного ревью**: очередь, деталь задачи, assign на API-ключ, approve/reject, комментарии, приоритет, resubmit шага и presigned URL документов.

Эндпоинты рассчитаны на **интеграторов**, которые ведут ревью во внешней системе (свой back-office или автоматизация). Операторы админ-панели работают через UI — см. [Админ → Ревью](/ru/admin/review).

Базовые пути:

| Продукт | Base |
| --- | --- |
| KYC | `/tenant/v1/kyc/review-tasks` |
| KYB | `/tenant/v1/kyb/review-tasks` |

Аутентификация: HMAC-SHA256 с KYC или KYB API-ключом. См. [Аутентификация](/ru/api/authentication).

## Необходимые scopes [#необходимые-scopes]

| Scope | Доступ |
| --- | --- |
| `reviews:read` | KYC: очередь, stats, reject-reasons, деталь, комментарии, resubmits |
| `reviews:write` | KYC: assign, approve, reject, comment, priority, request-resubmit |
| `media:read` | KYC: URL документов (вместе с `reviews:read`) |
| `kyb.reviews:read` | KYB чтение |
| `kyb.reviews:write` | KYB запись |
| `kyb.media:read` | KYB URL документов (вместе с `kyb.reviews:read`) |

KYC-ключ не может вызывать `/kyb/review-tasks/*` (HTTP 403), и наоборот.

Мутации атрибутируются **API-ключу** (`actor_type=api_key`): assign, комментарии и финальные решения сохраняют id ключа и display name.

Поля ответа для идентичности актора (если заполнены):

| Ресурс | Поля |
| --- | --- |
| Очередь / деталь задачи | `assigned_to`, `assigned_to_type` (`admin_user` \| `superadmin_user` \| `api_key`), `assigned_display_name` |
| Деталь после решения | `decision_by`, `decision_by_type`, `decision_display_name` |
| Комментарий | `author_id`, `author_type`, `author_display_name` |

## Типовой сценарий [#типовой-сценарий]

1. Подписка на `verification.needs_review` — [Вебхуки](/ru/api/webhooks).
2. `GET .../review-tasks` — очередь (`status=pending` / `in_progress`).
3. `GET .../review-tasks/{task_id}` — деталь и `review_reasons`.
4. `POST .../assign` — взять задачу на текущий API-ключ.
5. При необходимости `GET .../documents/{document_id}/url`.
6. Решение:
   - `POST .../approve`
   - `POST .../reject` с **каноническим** `reason_code` из `GET .../reject-reasons`
   - или `POST .../request-resubmit` для одного шага

После финального решения уходят terminal webhook-события (`verification.approved` / `verification.declined`).

## Очередь [#очередь]

API operations:

- `GET /v1/kyc/review-tasks`

KYB: `GET /tenant/v1/kyb/review-tasks` (те же фильтры; поиск по company/external id).

### Алиасы status [#алиасы-status]

| Query | Внутренние статусы |
| --- | --- |
| `in_progress` | `assigned` |
| `completed` | `approved`, `rejected` |
| прочие | как есть (`pending`, `awaiting_resubmit`, …) |

### Приоритет [#приоритет]

| Значение | Число |
| --- | --- |
| `low` | 1 |
| `medium` | 2 |
| `high` | 3 |
| `urgent` | 4 |

## Stats и причины отклонения [#stats-и-причины-отклонения]

API operations:

- `GET /v1/kyc/review-tasks/stats`

API operations:

- `GET /v1/kyc/review-tasks/reject-reasons`

Канонические коды reject (только их принимает `POST .../reject`):

`blurry_document`, `expired_document`, `wrong_document_type`, `document_mismatch`, `unreadable_document`, `face_not_matching`, `poor_selfie_quality`, `liveness_failed`, `face_obscured`, `sanctions_match`, `pep_match`, `adverse_media`, `suspected_fraud`, `duplicate_account`, `incomplete_data`, `other`.

Неканонический `reason_code` → HTTP 400.

## Деталь, комментарии, документы [#деталь-комментарии-документы]

API operations:

- `GET /v1/kyc/review-tasks/{task_id}`

У неназначенных задач нет `assigned_to` / `assigned_to_type` / `assigned_display_name` (не подставляется `admin_user`). После assign/decision type — одно из `admin_user` | `superadmin_user` | `api_key`.

API operations:

- `GET /v1/kyc/review-tasks/{task_id}/comments`

API operations:

- `POST /v1/kyc/review-tasks/{task_id}/comments`

Поле текста комментария — **`content`** (не `body`). Пример: `{"content":"Нужно более чёткое фото паспорта"}`. В ответе: `author_id`, `author_type` (`api_key` для HMAC), `author_display_name`.

API operations:

- `GET /v1/kyc/review-tasks/{task_id}/documents/{document_id}/url`

## Мутации: assign, priority, decide [#мутации-assign-priority-decide]

API operations:

- `POST /v1/kyc/review-tasks/{task_id}/assign`

Assign возможен для `pending` и `awaiting_resubmit`. Задача назначается на **текущий API-ключ**.

API operations:

- `PATCH /v1/kyc/review-tasks/{task_id}/priority`

API operations:

- `POST /v1/kyc/review-tasks/{task_id}/approve`

API operations:

- `POST /v1/kyc/review-tasks/{task_id}/reject`

Опционально: `if_unmodified_since` (RFC3339) для optimistic concurrency.

## Resubmit [#resubmit]

API operations:

- `POST /v1/kyc/review-tasks/{task_id}/request-resubmit`

API operations:

- `GET /v1/kyc/review-tasks/{task_id}/resubmits`

Коды resubmit (качество шага), **не** путать с reject reasons: `illegible`, `blurry`, `cropped`, `glare`, `wrong_document`, `expired_document`, `partial`.

Лимиты: ≤ 3 на сессию, TTL 7 дней, один active request на пару `(session, step)`. Вебхуки: [Manual Review Resubmit](/ru/api/webhooks#sobytiya-manual-review-resubmit-verificationresubmit_).

## KYB [#kyb]

Зеркальные методы: `/tenant/v1/kyb/review-tasks` со scopes `kyb.reviews:*` и `kyb.media:read`. См. [KYB API — Справочник](/ru/kyb/api-reference) и [OpenAPI](/ru/api/api-reference).

## Только admin (не Tenant API) [#только-admin-не-tenant-api]

- reassign / unassign другому оператору
- delegate команде OneKYC
- cancel resubmit
- вспомогательные list resubmittable steps UI-эндпоинты консоли

## См. также [#см-также]

- [Вебхуки](/ru/api/webhooks)
- [Аутентификация](/ru/api/authentication)
- [Админ → Ревью](/ru/admin/review)
- [Справочник OpenAPI](/ru/api/api-reference)