For AI agents: fetch the complete documentation index at /llms.txt, the full documentation corpus at /llms-full.txt, the agent skill at /skill.md, or this page as Markdown at /ru/docs/web/api.md (or send Accept: text/markdown).

Публичный API, ключи и вебхуки

Версионируемая REST-поверхность, на которой строят ваши клиенты.

Задать вопрос об этом руководстве

Прежде чем начать

Откройте загруженный проект supastack в Visual Studio Code, используя «Файл» → «Открыть папку», затем выберите «Терминал» → «Новый терминал». Корень репозитория — это папка, содержащая package.json, приложения и пакеты. Запустите команду ниже и оставьте терминал открытым. Если команда не распознается, завершите руководство по установке инструмента, прежде чем продолжить.

Сначала прочтите руководство по платформе. Сервер — это процесс приложения, который отвечает на запросы браузера или телефона. Веб читает apps/web/.env.local, Expo читает apps/mobile/.env.local, а команды миграции базы данных читают корневой .env. Демонстрация без базы данных / панели мониторинга отделена от реальных учетных записей / аутентификации, для которых необходимо перенести Postgres. Для оформления заказа только на телефоне или компьютере требуется отдельно работающий веб-сервер.

corepack pnpm --filter @supastack/web dev

Настройка и конфигурация

packages/api определяет версионируемый контракт: zod-схемы для каждого запроса и ответа, обёртку ошибок и документ OpenAPI, отдаваемый на /api/v1/openapi и отрисованный на /api/docs. API-ключи пространства создаются в Настройки → Разработчики; открытый текст показывается один раз, далее сохраняется только хэш ключа.

Ключи имеют префикс (sk_<env>_…), scope (по умолчанию read) и разрешаются в рабочее пространство при каждом запросе. Подписки исходящих вебхуков управляются на той же поверхности «Разработчики».

GET  /api/v1/workspaces/current
GET  /api/v1/entitlements
GET  /api/v1/models/requirements
POST /api/v1/ai-tasks
GET  /api/v1/openapi           # machine-readable spec
GET  /api/docs                 # rendered reference

Authorization: Bearer sk_live_…

Рабочий процесс внедрения

Аутентифицируйтесь Bearer-ключом; сервер разрешает пространство из ключа, а не из переданного клиентом id. Держите формы ответов версионируемыми — аддитивные изменения внутри v1, ломающие — за новой версией.

Для исходящих вебхуков подпишите URL конечной точки на каталог событий; доставки подписываются и логируются, чтобы потребители могли проверять и воспроизводить. Используйте webhook-events.ts для каталога и webhook-delivery.ts для попыток.

Проверка и устранение неполадок

Проверьте, что отозванный ключ возвращает 401, что ключ с недостаточным scope отклоняется и что документ OpenAPI парсится. Для вебхуков протестируйте проверку подписи, повторную доставку после сбоя и то, что полезные нагрузки событий никогда не несут секреты провайдера.