Skip to content

Начало работы с TechCon API

Руководство для интеграторов: как подключиться к сервисам экосистемы, проверить их доступность и обработать базовые ошибки.

1. Обзор экосистемы

TechCon предоставляет четыре production-сервиса через единый домен techcon-ml.ru:

Сервис Базовый URL Назначение
Passports AI https://passports.techcon-ml.ru Распознавание и верификация паспортов
Defectoscopy https://defects.techcon-ml.ru Дефектоскопия изображений (ML pipeline)
STT https://stt.techcon-ml.ru Транскрибация голосовых описаний и polling результата
Techplans Search https://techplans.techcon-ml.ru Семантический поиск по техпланам

Все сервисы работают по HTTPS. HTTP-запросы автоматически перенаправляются на HTTPS.

Kroki

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

Открытые эндпоинты

Большинство публичных эндпоинтов не требуют аутентификации:

# Проверка доступности без токена
curl https://passports.techcon-ml.ru/health
curl https://defects.techcon-ml.ru/health
curl https://stt.techcon-ml.ru/health
curl https://techplans.techcon-ml.ru/health

Bearer token (Passports /health/deep)

Эндпоинт глубокой диагностики /health/deep требует Bearer token:

curl -H "Authorization: Bearer <ваш_токен>" \
     https://passports.techcon-ml.ru/health/deep

Token выдаётся командой ops. Для получения доступа — создайте Issue в репозитории techcon_infra_monitoring с тегом access-request.

3. Health checks

Все сервисы возвращают единый формат ответа на /health:

{"ok": true, "data": {...}}
Поле Тип Описание
ok boolean true = сервис готов к работе
data object Детали состояния (зависят от сервиса)

Примеры ответов:

# Passports
curl https://passports.techcon-ml.ru/health
# {"ok": true, "data": {"workers_online": 2}}

# Defectoscopy
curl https://defects.techcon-ml.ru/health
# {"ok": true, "data": {"model_loaded": true}}

# STT
curl https://stt.techcon-ml.ru/health
# {"ok": true, "data": {"status": "ok", "request_acceptance": true, ...}}

# Techplans
curl https://techplans.techcon-ml.ru/health
# {"ok": true, "data": {"status": "ok", ...}}

Проверка через Gatus dashboard

Статус всех сервисов в реальном времени доступен на ops.techcon-ml.ru/gatus/ (требует GitHub OAuth, доступно для авторизованных пользователей org TechCon-ML-Team).

Gatus проверяет каждый сервис каждые 1–2 минуты и отображает историю доступности.

4. Базовые ошибки

HTTP коды

Код Причина Действие
200 ОК —
302 Redirect (HTTPS или OAuth) Следовать редиректу; для OAuth — нужна авторизация
503 Сервис недоступен Проверить Gatus dashboard
504 Gateway timeout Повторить через 30 сек; если сохраняется — Gatus

Алгоритм диагностики

  1. Проверить Gatus dashboard — если сервис помечен как FAILURE, это инфраструктурная проблема, не ваша интеграция
  2. Проверить /health напрямую — если ok: false, сервис работает но не готов (например, модель не загружена)
  3. Создать Issue в techcon_infra_monitoring если Gatus зелёный, но ваши запросы падают — возможна проблема с конфигурацией конкретного клиента

Retry policy

Для временных сбоев рекомендуется exponential backoff: - Начальная задержка: 1 сек - Максимум попыток: 3 - Максимальная задержка: 10 сек

Не используйте retry для кодов 4xx (клиентские ошибки) — они не исчезнут сами по себе.