TechPlans Search — начало работы

TechPlans Search отдаёт базу технических планов домов (6231 запись) с поиском по региону, серии, адресу и характеристикам здания. Полная машиночитаемая спецификация — на странице TechPlans Search API и в openapi.json. Здесь — краткий обзор и рабочие примеры для старта.

Среды

Среда	URL
Прод	https://techplans.techcon-ml.ru
Дев-стенд	https://techplans.dev.techcon-ml.ru
Локальная	http://localhost:8000

Аутентификация

Поиск, карточки объектов, выгрузка в XLSX и приём сообщений об ошибках — открытая поверхность без токена. Просмотр и обработка поступивших сообщений (GET /reports, PATCH /reports/{id}) и метрики (GET /metrics) — закрытый контур: нужен Bearer-токен административного контура, который выдаёт владелец сервиса.

Матрица защиты

Эндпоинт	Метод	Требуется токен
/health	GET	Нет
/	GET	Нет
/search	POST	Нет
/detail/{uid}	GET	Нет
/export	GET	Нет
/images/{filename}	GET	Нет
/reports	POST	Нет
/reports	GET	Да (Bearer)
/reports/{id}	PATCH	Да (Bearer)
/metrics	GET	Да (Bearer)

Общие ограничения

• POST /search: не чаще одного запроса в 150 мс на сессию.
• POST /reports: до 5 заявок за 5 минут с одного IP.
• Максимальный размер запроса и таймаут — не заданы отдельно от значений по умолчанию используемого HTTP-сервера.

Проверка состояния

curl -s https://techplans.dev.techcon-ml.ru/health

{
  "ok": true,
  "data": {
    "status": "ok",
    "total_records": 6231
  }
}

Поиск по фильтрам

POST /search принимает форму (application/x-www-form-urlencoded) и возвращает готовый HTML-фрагмент таблицы результатов — эндпоинт рассчитан на встраивание в собственный интерфейс через HTMX, а не на разбор JSON. Основные поля: region, material_walls, roof_type (множественные), floors_min/floors_max, entrances_min/entrances_max, apartments_min/apartments_max, area_min/area_max (диапазоны), series, address (текстовый поиск), sort_by, sort_desc, page.

curl -X POST https://techplans.techcon-ml.ru/search \
  -d "address=Ленина" \
  -d "page=1"

import httpx

resp = httpx.post(
    "https://techplans.techcon-ml.ru/search",
    data={"address": "Ленина", "page": "1"},
)
print(resp.status_code, len(resp.text))

Активные фильтры сохраняются в сессии пользователя, поэтому GET /export без параметров выгружает именно последний найденный набор в XLSX.

Сообщение об ошибке в данных

POST /reports принимает заявку на исправление конкретной записи — неверный адрес, лишний объект, ошибка в характеристиках. Ответ — 201 с обёрткой {"ok": true, "data": {"id": "<uuid>"}}.

curl -X POST https://techplans.techcon-ml.ru/reports \
  -H "Content-Type: application/json" \
  -d '{
    "record_id": "abc-123",
    "action_type": "edit",
    "description": "Неверный адрес здания в карточке",
    "user_info": "Иван Иванов"
  }'

import httpx

resp = httpx.post(
    "https://techplans.techcon-ml.ru/reports",
    json={
        "record_id": "abc-123",
        "action_type": "edit",
        "description": "Неверный адрес здания в карточке",
        "user_info": "Иван Иванов",
    },
)
print(resp.json())

action_type — одно из delete, edit, content_correction. description — не короче 10 символов, иначе 422.

Типовые коды ошибок

Код	HTTP	Описание
—	401	Нет токена или токен неверен (закрытый контур)
—	404	Запись или сообщение не найдены
—	422	Ошибка входных параметров
—	429	Превышено ограничение частоты

Типовой сквозной сценарий

1. Проверить доступность: GET /health.
2. Найти объекты по адресу: POST /search с полем address.
3. Открыть карточку конкретного объекта: GET /detail/{uid}.
4. Если в карточке ошибка — отправить POST /reports с record_id этого объекта.
5. При необходимости выгрузить найденный набор: GET /export.

Полный перечень полей, схем и кодов ответов — в автоматически собранной спецификации на странице TechPlans Search API.