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

API pública, claves y webhooks

La superficie REST versionada sobre la que construyen tus clientes.

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 define el contrato versionado: esquemas zod para cada petición y respuesta, el sobre de error y el documento OpenAPI servido en /api/v1/openapi y renderizado en /api/docs. Las claves de API del workspace se crean en Ajustes → Desarrolladores; el texto plano se muestra una vez, después solo persiste la clave hasheada.

Las claves llevan prefijo (sk_<env>_…), scope (lectura por defecto) y se resuelven a un workspace en cada petición. Las suscripciones de webhooks salientes se gestionan desde la misma superficie de Desarrolladores.

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

Flujo de implementación

Autentica con la clave Bearer; el servidor resuelve el workspace desde la clave, nunca desde un id suministrado por el cliente. Mantén las formas de respuesta versionadas — cambios aditivos dentro de v1, cambios rupturistas detrás de una nueva versión.

Para webhooks salientes, suscribe una URL de endpoint al catálogo de eventos; las entregas se firman y se registran para que los consumidores puedan verificarlas y reenviarlas. Usa webhook-events.ts para el catálogo y webhook-delivery.ts para los intentos.

Verificación y solución de problemas

Verifica que una clave revocada devuelve 401, que una clave con scope insuficiente es denegada y que el documento OpenAPI se parsea. Para webhooks, prueba la verificación de firma, la reentrega tras fallo y que los payloads de eventos nunca lleven secretos de proveedor.