Passports — начало работы

Passports принимает сканы технических паспортов зданий (PDF или изображения), извлекает из них структурированные данные через LLM и отдаёт результат в JSON, Excel или печатном PDF-отчёте. Полная машиночитаемая спецификация — на странице Passports API и в openapi.json. Здесь — краткий обзор и рабочие примеры для старта.

Среды

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

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

Текущий production и dev-контуры работают в открытом режиме — Bearer-токен не требуется ни на одном маршруте. Отдельно существует вспомогательный auth-enabled контур (только для CI и локальной проверки), где часть маршрутов требует Authorization: Bearer <token>, выдаваемый через POST /auth/token; для интеграции с прод/дев-контуром этот раздел не нужен.

Клиенту достаточно передавать cookie bti_session_id (сервис выставляет её сам при первом запросе) — она отделяет задачи одного пользователя от чужих в GET /api/tasks и GET /export/my.

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

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

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

Статусы задачи

Статус	Описание
`PENDING`	Задача создана и ждёт обработки
`PROCESSING`	Извлечение данных выполняется
`SUCCESS`	Результат готов и доступен в `GET /api/task/{id}/result`
`FAILED`	Ошибка обработки конкретного файла; доступен ручной повтор
`ERROR`	Системная ошибка или временная недоступность обработки; доступен ручной повтор
`PERMANENT_ERROR`	Превышен лимит автоматических повторов, повтор недоступен

Загрузка паспорта

POST /upload принимает один или несколько PDF-файлов (multipart/form-data, поле files) — максимум 20 файлов, до 50 МБ каждый. При повторной загрузке файла, уже обработанного ранее (совпадение по содержимому), результат возвращается сразу со статусом SUCCESS, без повторного обращения к LLM.

curl -X POST https://passports.dev.techcon-ml.ru/upload \
  -H "Accept: application/json" \
  -F "files=@passport.pdf"

{
  "ok": true,
  "data": {
    "tasks": [
      {"id": "3f1a2b4c-1234-5678-abcd-ef1234567890", "status": "PENDING"}
    ]
  }
}

import httpx

resp = httpx.post(
    "https://passports.dev.techcon-ml.ru/upload",
    headers={"Accept": "application/json"},
    files={"files": open("passport.pdf", "rb")},
)
task_id = resp.json()["data"]["tasks"][0]["id"]

Ожидание результата и чтение данных

Опрашивать статус короче и дешевле, чем сразу опрашивать результат:

import httpx, time

with httpx.Client(base_url="https://passports.dev.techcon-ml.ru") as client:
    while True:
        status = client.get(f"/api/task/{task_id}/status").json()["data"]["status"]
        if status in ("SUCCESS", "FAILED", "ERROR", "PERMANENT_ERROR"):
            break
        time.sleep(10)

result = client.get(f"/api/task/{task_id}/result").json()
print(result["data"]["data"]["object_info"])

GET /api/task/{task_id}/result при готовой задаче отдаёт распознанные поля паспорта двумя группами — object_info (общие сведения о здании: год постройки, этажность, тип конструкции и т. п.) и object_specs (количественные характеристики: площадь, объём, высота). Поле, которое не найдено в документе или не распознано, приходит как null; числа округлены до двух знаков.

Экспорт

Маршрут	Формат	Что отдаёт
`GET /export/{task_id}/excel`	XLSX	Одна задача, вертикальный формат «поле → значение»
`GET /export/{task_id}/pdf`	PDF	Одна задача, печатный отчёт
`GET /export/my`	XLSX	Все успешные задачи текущей сессии (сводная таблица)
`GET /export/all`	XLSX	Все успешные задачи (сводная таблица)

curl "https://passports.dev.techcon-ml.ru/export/$TASK_ID/excel" -o passport.xlsx

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

Код	HTTP	Описание
`TASK_NOT_FOUND`	404	Задача с указанным `task_id` не найдена
`VALIDATION_ERROR`	400	Ошибка входных данных (например, больше 20 файлов за раз)
`RETRY_CONFLICT`	409	Повтор недоступен для текущего статуса задачи
`INTERNAL_ERROR`	500	Внутренняя ошибка сервиса

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

Загрузить паспорт: POST /upload, получить task_id.
Опрашивать GET /api/task/{task_id}/status до терминального статуса.
Прочитать данные: GET /api/task/{task_id}/result.
При необходимости выгрузить отчёт: GET /export/{task_id}/excel или /pdf.
Если статус FAILED/ERROR — при необходимости повторить обработку через POST /api/task/{task_id}/retry.

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