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 /es/docs/modules/api.md (or send Accept: text/markdown).

Módulo de API

El contrato público versionado, la plomería de claves y la superficie OpenAPI.

Preguntar sobre esta guía

Antes de comenzar

Abra su proyecto supastack descargado en Visual Studio Code usando Archivo → Abrir carpeta, luego elija Terminal → Nueva terminal. La raíz del repositorio es la carpeta que contiene package.json, aplicaciones y paquetes. Ejecute el comando a continuación y deje su terminal abierta. Si no se reconoce un comando, finalice la guía de instalación de la herramienta antes de continuar.

Lea primero el tutorial de la plataforma. Un servidor es el proceso de la aplicación que responde a las solicitudes del navegador o del teléfono. La web lee apps/web/.env.local, Expo lee apps/mobile/.env.local y los comandos de migración de bases de datos leen root .env. La demostración sin base de datos/panel de control está separada de las cuentas reales/de autenticación, que necesitan migrar Postgres. Un proceso de pago solo por teléfono o computadora de escritorio necesita un backend web que se ejecute por separado.

corepack pnpm --filter @supastack/web dev

Configuración y ajustes

packages/api es la fuente de verdad para la superficie REST pública: esquemas zod para peticiones, respuestas y el sobre de error, más el documento OpenAPI (openApiDocument) servido en /api/v1/openapi. Los handlers de ruta componen estos esquemas en lugar de redefinir formas.

Las claves de API se emiten por workspace con prefijo sk_<env>_, se almacenan hasheadas con comparación en tiempo constante y llevan scopes — lectura por defecto. api-keys.ts posee la creación, búsqueda y revocación.

apiV1 = "/api/v1"

schemas: currentWorkspace, entitlement,
  modelRequirements, createAiTaskRequest,
  aiTask, aiTaskResult, apiError

openApiDocument → GET /api/v1/openapi

Flujo de implementación

Añade endpoints dentro de la versión existente: extiende los esquemas, mantén el sobre de error y regenera la superficie OpenAPI para que /api/docs siga siendo exacto. Los cambios rupturistas obtienen una nueva versión, no un cambio de forma silencioso.

Resuelve el workspace del llamante desde la clave presentada, aplica las mismas reglas de entitlement y validación que la app web, y limita la tasa por clave.

Verificación y solución de problemas

Haz contract-test de cada forma de ruta contra los esquemas del paquete. Verifica que las claves desconocidas, revocadas y las peticiones con scope insuficiente fallan todas con el sobre de error documentado, y que el documento OpenAPI sigue siendo JSON válido.