API pública, chaves e webhooks

Antes de começar

Abra seu projeto supastack baixado em Visual Studio Code usando Arquivo → Abrir pasta e escolha Terminal → Novo Terminal. A raiz do repositório é a pasta que contém package.json, apps e pacotes. Execute o comando abaixo e deixe seu terminal aberto. Se um comando não for reconhecido, conclua o guia de instalação da ferramenta antes de continuar.

Leia o tutorial da plataforma primeiro. Um servidor é o processo do aplicativo que responde às solicitações do navegador ou do telefone. A Web lê apps/web-tanstack/.env.local, Expo lê apps/mobile/.env.local e os comandos de migração de banco de dados leem root .env. A demonstração sem banco de dados/painel é separada das contas reais/auth, que precisam migrar para Postgres. Uma finalização de compra somente por telefone ou desktop precisa de um back-end da Web executado separadamente.

• Instale as ferramentas e obtenha o código
• Aprenda comandos, arquivos e configuração
• Conclua o tutorial inicial da Web

corepack pnpm --filter @supastack/web-tanstack dev

Instalação e configuração

O packages/api define o contrato versionado: schemas zod para cada pedido e resposta, o envelope de erro e o documento OpenAPI servido em /api/v1/openapi e renderizado em /api/docs. As chaves de API do workspace criam-se em Definições → Programadores; o texto em claro mostra-se uma vez, depois persiste apenas a chave com hash.

As chaves têm prefixo (sk_<env>_…), scope (leitura por predefinição) e resolvem para um workspace em cada pedido. As subscrições de webhooks de saída gerem-se na mesma superfície de Programadores.

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_…

Fluxo de implementação

Autentica com a chave Bearer; o servidor resolve o workspace a partir da chave, nunca de um id fornecido pelo cliente. Mantém as formas de resposta versionadas — alterações aditivas dentro de v1, alterações breaking atrás de uma nova versão.

Para webhooks de saída, subscreve um URL de endpoint ao catálogo de eventos; as entregas são assinadas e registadas para que os consumidores possam verificar e reenviar. Usa webhook-events.ts para o catálogo e webhook-delivery.ts para as tentativas.

Verificação e resolução de problemas

Verifica que uma chave revogada devolve 401, que uma chave com scope insuficiente é negada e que o documento OpenAPI faz parse. Para webhooks, testa a verificação de assinatura, a reentrega após falha e que os payloads de eventos nunca transportam secrets do provider.