Quickstart для разработчиков¶

Цель: за десять минут сделать первый аутентифицированный API-вызов к Expecto, создать сессию и пройти тот же путь через MCP. Здесь вы не настраиваете проекты и entity — это путь владельца проекта. Предполагается, что всё это уже настроено, и у вас есть API-ключ.

Что нужно¶

API-ключ — выдаёт администратор организации в Настройки организации → API-ключи. Относитесь к нему как к паролю; он даёт доступ ко всему, что видит ваша организация. Если ключа нет — попросите того, кто подключал вашу организацию. Раздел API-ключи у Org Admins описывает выпуск.
Базовый URL вашего Expecto. Для хостед-инстанса это https://expecto-app.onrender.com. Замените EXPECTO_BASE_URL ниже на тот, что вам выдали.
Терминал с curl и, опционально, Python ≥ 3.10 для MCP-шага. Любой MCP-совместимый клиент (Claude Desktop, Claude Code, Cursor, ваш внутренний клиент) подойдёт для MCP-шага.

export EXPECTO_BASE_URL="https://expecto-app.onrender.com"
export EXPECTO_API_KEY="вставьте-сюда-ключ"

Все примеры ниже подразумевают, что эти две переменные установлены.

Шаг 1 — Проверить связь¶

Запрос на /api/me. Возвращает данные о вашем пользователе и организации за этим API-ключом. Если работает — ключ валиден и сеть до API доходит.

curl -sS \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  "$EXPECTO_BASE_URL/api/me" | jq .

Должны увидеть JSON с пользователем, организацией и ролью. 401 — ключ не тот или отозван; 403 — обычно ключ из другой организации, не той, к ресурсу которой обращаетесь.

Интерактивный просмотр API

Каждый эндпоинт ниже задокументирован в интерактивном Swagger UI по адресу <EXPECTO_BASE_URL>/api/docs (ReDoc — /api/redoc). Нажмите Authorize, вставьте свой API-ключ и пробуйте вызовы прямо из браузера.

Swagger UI Expecto по адресу /api/docs

Шаг 2 — Получить список ваших проектов¶

Каждый кейс приёма данных живёт внутри Project. Выведите те, к которым есть доступ:

curl -sS \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  "$EXPECTO_BASE_URL/api/projects" | jq '.items[] | {id, name}'

Выберите один и сохраните его ID — большинство дальнейших вызовов требуют project context напрямую или через Session:

export PROJECT_ID="..."

Шаг 3 — Создать сессию и загрузить файл¶

Session — один акт поставки: поставщик + период + комплект файлов, который идёт через пайплайн. Чтобы отправить данные через API — создаёте сессию, прикрепляете файлы, запускаете пайплайн.

Создать:

curl -sS -X POST \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_id": "'"$PROJECT_ID"'",
    "data_contract_id": "PUT_CONTRACT_ID_HERE",
    "period_label": "2026-06"
  }' \
  "$EXPECTO_BASE_URL/api/sessions" | jq .

Сохраните возвращённый id как SESSION_ID. Дальше загрузите файл под source role, заявленным в контракте:

curl -sS -X POST \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  -F "source_role=buchungsdatei" \
  -F "file=@/путь/к/файлу.csv" \
  "$EXPECTO_BASE_URL/api/sessions/$SESSION_ID/files" | jq .

Запустить пайплайн (асинхронно):

curl -sS -X POST \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  "$EXPECTO_BASE_URL/api/sessions/$SESSION_ID/run"

Возвращается 202 Accepted и job_id. Опрашивайте сессию на статус — parse → transform → check:

curl -sS \
  -H "X-API-Key: $EXPECTO_API_KEY" \
  "$EXPECTO_BASE_URL/api/sessions/$SESSION_ID" | jq '{status, health, stages}'

Когда health становится ready — данные прошли валидацию, сессию можно confirm-нуть и затем approve-нуть, чтобы получить экспортный пакет.

Шаг 4 — То же через MCP¶

Expecto предоставляет MCP-сервер на <EXPECTO_BASE_URL>/mcp/. Аутентификация — тот же заголовок X-API-Key.

Добавьте его в свой MCP-клиент. Для Claude Desktop редактируется claude_desktop_config.json:

{
  "mcpServers": {
    "expecto": {
      "url": "https://expecto-app.onrender.com/mcp/",
      "transport": "http",
      "headers": {
        "X-API-Key": "ваш-api-ключ"
      }
    }
  }
}

После подключения доступны инструменты: list_projects, get_project, create_session, upload_session_file, run_session_pipeline, list_sessions, get_session, get_session_violations. Тот же поток из шага 3 на MCP выглядит так:

list_projects → выбрать один
create_session(project_id, data_contract_id, period="2026-06")
upload_session_file(session_id, source_role="buchungsdatei", file=...)
run_session_pipeline(session_id)
get_session(session_id)

Большинство AI-ассистентов сами выстраивают эти вызовы в цепочку, когда задана цель («сабмить июньские данные IntReal в проект X») — это и есть основная причина выбирать MCP вместо REST для ручных submissions.

Куда двигаться дальше¶

Если хотите…	Идите сюда
Посмотреть каждый REST-endpoint	Справочник REST API — Coming soon. Интерактивная спека: /api/docs на вашем инстансе
Пройтись по всем MCP-инструментам	Каталог MCP-инструментов
Понять доменную модель	Концепции
Сделать "submit" из CI	Настроить CI и автоматизацию — Coming soon.
Передавать результаты downstream в BuiltAPI	Интегрироваться с BuiltAPI downstream — Coming soon.