# TenderLex API: очередь задач

## Когда использовать

Прямые методы `/api/v1/mcp/suppliers/search`, `/products/exact-analogs` и
`/procurements/analyze` подходят для небольшого текстового запроса и отвечают
сразу. Для загружаемых файлов, мониторинга цен, поиска с городом и радиусом,
либо выбора отдельных строк ТЗ используйте очередь `/api/v1/mcp/jobs`.

Очередной API доступен только активному ключу, который привязан к активному
лицевому счёту клиента. Все задачи, файлы, резерв и результат принадлежат этому
счёту; другой ключ чужого клиента не может увидеть задачу или скачать файл.

## Авторизация

Во все запросы передавайте один из заголовков:

```text
Authorization: Bearer tl_live_...
# или
X-API-Key: tl_live_...
```

Для создания рекомендуем также `Idempotency-Key`: повтор одинакового запроса с
тем же ключом не создаст вторую рыночную задачу. Если операция уже принята,
сервер вернёт `409`, `operation_id`, `job_id` и список `job_ids`.
Запрос `GET /api/v1/mcp/operations/{operation_id}` восстанавливает состояние
операции без повторного поиска. Не подставляйте новый ключ при сетевом повторе.

## Создать задачу

`POST /api/v1/mcp/jobs` принимает `multipart/form-data`.

| Поле | Значение |
|---|---|
| `mode` | `supplier_search`, `procurement_report`, `analysis_and_suppliers`, `exact_product`, `price_monitoring` |
| `text` | Текст ТЗ или документации |
| `source_urls` | номера извещений или URL, по одному на строку |
| `files` | один или несколько документов |
| `delivery_city` + `geo_radius_km` | город и радиус доставки для поддерживаемых режимов |
| `supplier_search_policy` | `normal`, `minprom_registry_priority`, `minprom_registry_only` |
| `multi_item_mode` | `balanced` либо `per_item` |

География — приоритет, а не строгое исключение: подтверждённые поставщики
в радиусе идут первыми, поставщики вне радиуса и с неизвестным адресом
помечаются отдельно. Расстояние ориентировочное, между центрами городов;
склад и условия доставки нужно уточнить. Радиус — целое число 10–5000 км,
город и радиус указываются вместе для supplier_search, analysis_and_suppliers
и price_monitoring. Для exact_product и procurement_report география не применяется.

География не является косметическим параметром: если клиенту не предоставлен
доступ к радиусу доставки, запрос будет отклонён до запуска и списания.

Пример:

```bash
curl -X POST https://tenderlex.ru/api/v1/mcp/jobs \
  -H 'Authorization: Bearer tl_live_...' \
  -H 'Idempotency-Key: erp-req-1042' \
  -F 'mode=price_monitoring' \
  -F 'delivery_city=Казань' \
  -F 'geo_radius_km=250' \
  -F 'files=@./specification.xlsx'
```

Ответ содержит `job.id`. Опрос состояния: `GET /api/v1/mcp/jobs/{job_id}`.
Список собственных задач: `GET /api/v1/mcp/jobs?limit=30&offset=0`.

## Следующие шаги задачи

После разбора ТЗ сервер может вернуть `position_selection`. Тогда подтвердите
только нужные строки:

```json
POST /api/v1/mcp/jobs/{job_id}/position-selection
{"revision":"...","selected_item_ids":["..."]}
```

Для многострочного поиска поставщиков, ожидающего решения по стратегии:

```json
POST /api/v1/mcp/jobs/{job_id}/choose-strategy
{"revision":"...","multi_item_mode":"per_item","selected_item_ids":["..."]}
```

Передавайте актуальную `multi_item_details.revision` из состояния задачи и ID
исходных строк. Стратегии `balanced` и `per_item` доступны для
`supplier_search` и `analysis_and_suppliers`; обе учитывают явный состав
выбранных позиций. Устаревшая revision отклоняется до запуска и резервирования;
получите состояние заново и повторно подтвердите выбор.

Доступны также `POST /{job_id}/cancel`, `POST /{job_id}/accept` и
`POST /{job_id}/decline`. Результаты описываются в `result_files`; скачать их
можно через `GET /{job_id}/download` или
`GET /{job_id}/files/{file_kind}` с тем же заголовком авторизации.

## Права и оплата

Ключ должен иметь разрешение на выбранный режим; доступ аккаунта проверяется
по тем же правилам тарифа и баланса, что в кабинете. Для
`analysis_and_suppliers` требуются оба права: анализ документации и поиск
поставщиков. Для `price_monitoring` требуется отдельное право мониторинга на
ключе и лицевом счёте. Запуск использует тот же резерв и расчёт, что личный
кабинет; результат и возврат резерва обрабатываются очередным процессом.

У прямого API пока остаются три коротких текстовых метода. Очередной API
добавляет все пять режимов, документы, географию и явный выбор позиций. Это
разные интерфейсы одного процессинга, а не отдельный источник рыночных данных.

## MCP

Автономный скрипт `tenderlex_mcp.py` поддерживает запуск и просмотр очередной
задачи, выбор позиций, отмену и `tenderlex_update_queued_job`: стратегия
`balanced`/`per_item`, принятие (`accept`) или отказ (`decline`) от неполного
результата. Решение об оплате/выборе принимает пользователь. ID позиций и
revision возвращаются в состоянии задачи. Для загрузки локального файла
задайте разрешённую папку `TENDERLEX_MCP_UPLOAD_DIR` и явно выберите файл.

Новый автономный ключ администратора по умолчанию имеет лимиты 20/10/10
для поиска/подбора/анализа и срок 30 дней. Это тестовая квота без баланса
клиента; очередь файлов и мониторинга требует привязки к клиенту.
Секрет ключа показывается один раз; в базе хранится только хэш. Подписанные
ссылки прямого подбора действуют 15 минут и прекращают работать после
отзыва или истечения срока ключа.
