Начало работы для интеграторов

Этот раздел собирает правила, общие для всех сервисов на портале. Детали конкретного сервиса — в его отдельном гайде и в автоматически собранной спецификации /api/<сервис>/.

Сервисы портала

Сервис	Что делает	Гайд	Спецификация
Passports	Паспортизация объектов	—	Passports API
TechPlans Search	Поиск по базе техпланов домов	гайд	TechPlans Search API
Defectoscopy	Визуальная дефектоскопия изображений	гайд	Defectoscopy API
STT	Распознавание речи в аудио	гайд	STT API

Формат ответов

Бизнес-ответы всех сервисов оборачиваются одинаково:

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

{"ok": false, "error": {"code": "SCREAMING_SNAKE_CASE", "message": "..."}}

Исключения из этой обёртки: GET /health, бинарные файлы (изображения, XLSX-выгрузки) и 204 No Content.

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

Способ аутентификации задаёт каждый сервис отдельно — единого токена на всю экосистему нет. Общий принцип, где токен нужен:

Authorization: Bearer <токен>

Токен для конкретного сервиса выдаёт его владелец. Смотрите раздел «Матрица защиты» в гайде нужного сервиса — какие маршруты открыты, а какие требуют токен.

Асинхронные задачи

Defectoscopy и STT используют одинаковый паттерн постановки задачи в очередь и последующего опроса:

POST /<постановка задачи>   ->  202  (status: queued)
GET  /result/{task_id}      ->  202  (status: queued | processing)   повторять
GET  /result/{task_id}      ->  200  (status: done | failed)         терминал

• сохраняйте task_id сразу после ответа 202;
• не опрашивайте чаще, чем рекомендует estimated_wait_seconds и интервал из ответа — это не произвольное ограничение, а фактический ритм готового результата;
• если сервис поддерживает webhook, используйте его как ускоряющий сигнал, а не замену опроса: итог всегда подтверждайте через GET /result/{task_id};
• результат задачи хранится ограниченное время (retention/TTL) от момента постановки задачи, а не от её завершения — не откладывайте чтение.

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

Коды специфичны для каждого сервиса, но общий смысл HTTP-статусов один и тот же во всей экосистеме:

HTTP	Значение
401	нет токена или токен неверный
404	ресурс или задача не найдены (в том числе — истекла по времени хранения)
422	тело или параметры запроса не прошли проверку
429	превышен лимит запросов
503	сервис временно не может обработать запрос (не готов, не хватает ресурса)

Дальше

Откройте гайд нужного сервиса — там реальные примеры curl/httpx, таблица кодов ошибок и сквозной сценарий. Полный контракт (все поля, схемы, обязательность) — на странице /api/<сервис>/, сгенерированной из живой OpenAPI-спецификации.