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

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

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

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

• Установите инструменты и получите код
• Изучение команд, файлов и конфигурации
• Пройдите руководство по первому запуску в Интернете

corepack pnpm --filter @supastack/web-tanstack 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 парсится. Для вебхуков протестируйте проверку подписи, повторную доставку после сбоя и то, что полезные нагрузки событий никогда не несут секреты провайдера.