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/commerce.md (or send Accept: text/markdown).
Comercio
Productos y pedidos del workspace sobre un ciclo de vida unidireccional.
Guía paso a paso para principiantes
Requisitos previos: lea las dos guías para principiantes a continuación, finalice la configuración local web y abra este monorepo en la raíz de su editor. La configuración web pertenece a apps/web/.env.local; Next.js no lee la raíz .env. /dashboard en el modo falso predeterminado es una demostración sin base de datos; /auth necesita una base de datos migrada.
Términos breves: un espacio de trabajo son los usuarios, datos y configuraciones separados de un equipo. El servidor es el backend confiable; Mantenga las claves del proveedor fuera del código del navegador y del teléfono. Una migración es un cambio de base de datos versionada que crea o actualiza tablas. Un modelo de IA es el motor que responde; el catálogo de modelos es la lista del servidor de ID de modelos disponibles y precios. Un proveedor es un servicio externo, como inteligencia artificial, correo electrónico o servicio de facturación. Un derecho es una concesión que permite que un espacio de trabajo utilice una función. Un webhook es un mensaje que un servicio envía al URL de otro servicio.
1. Como propietario o administrador del espacio de trabajo, abra /commerce y utilice el formulario del producto para crear un borrador con un nombre, moneda, precio unitario menor entero y stock rastreado opcional (para USD, 1299 significa $12,99).
2. Actívelo y cree una orden de prueba local; Confirme que el servidor calcula el total y almacena la instantánea del producto.
3. No conecte un proveedor de pagos real ni le cobre a un comprador real. Si un pedido no puede avanzar, verifique el stock disponible y el estado documentado del pedido antes de volver a intentarlo.
Para obtener código personalizado, comience con el prompts/README.md proporcionado y copie el mensaje más cercano: prompts/new-app-screen.md para una pantalla de aplicación o prompts/new-landing-page.md para una página pública. Para trabajos de servidor, base de datos o proveedor, asigne a su agente de codificación la tarea de esta guía y pídale que lea AGENTS.md, .ai/PROJECT_CONTEXT.md y los espejos .ai/ correspondientes; inspeccionar los archivos fuente exactos nombrados aquí; enumerar archivos y verificaciones antes de editarlos; preservar la propiedad del espacio de trabajo y los secretos exclusivos del servidor; y mostrarte la diferencia. Dígale el comportamiento que desea, los campos de entrada y salida, los roles permitidos, los éxitos y errores esperados y la cuenta, proveedor o dispositivo de prueba. Utilice valores de muestra; Nunca pegues un verdadero secreto.
Administra productos e inventario
/commerce proporciona administración de productos del espacio de trabajo para owner/admin. Los estados de los productos son draft/active/archived; los precios usan unidades monetarias menores y el inventario se puede controlar de forma opcional. La persistencia compartida está en packages/db.
Este es un módulo para crear productos. No incluye la compra de este kit, la entrega de repositorios de código fuente ni la gestión de licencias del vendedor.
Sigue el ciclo de vida del pedido
Los pedidos avanzan pending → paid → fulfilled, con comportamiento de cancelación/reposición y reembolso. El servidor calcula los totales y guarda instantáneas del nombre del producto/precio unitario de cada artículo para que las ediciones de un producto no reescriban pedidos históricos. Los eventos commerce.order_* admiten integraciones posteriores.
Conecta deliberadamente un flujo de pago de producto real. Una transición de estado de administrador no verifica por sí sola un cargo o reembolso del proveedor de pago.
Prueba las transiciones de inventario y estado
Verifica el inventario insuficiente, los pedidos simultáneos, la manipulación de precios desde el cliente, las transiciones hacia atrás no válidas, la reposición al cancelar, el comportamiento del reembolso y el acceso entre espacios de trabajo.
Configuración y ajustes
La superficie /commerce gestiona un catálogo de productos y pedidos para el workspace activo. Los productos llevan nombre, slug, precio en céntimos enteros, moneda de tres letras, URL de imagen opcional e inventario rastreado opcional; los pedidos guardan líneas en commerce_order_item con totales calculados en el servidor.
El estado del pedido solo avanza — pending → paid → fulfilled, con cancelación antes del pago y reembolso después. evaluateOrderStatusChange rechaza transiciones inválidas, sin cambios o prohibidas, así que un pedido cancelado o reembolsado nunca puede reabrirse.
/commerce owner/admin console
src/commerce.ts money math + lifecycle
src/commerce-actions.ts owner/admin mutations
commerce_product/order/order_itemFlujo de implementación
Solo owners y admins escriben — cada acción resuelve la sesión y el workspace mediante requireWorkspaceManager. createCommerceOrderAction valida las líneas (cantidades enteras de 1–9999, productos duplicados combinados), restringe las líneas a productos activos, recalcula los totales en el servidor y mantiene el pedido en una sola moneda.
El inventario rastreado decrece al crear un pedido y se repone al cancelar; un campo de inventario vacío significa sin seguimiento. La creación del pedido y cada cambio de estado emiten los webhooks commerce.order_created y commerce.order_status_changed más filas de auditoría.
Verificación y solución de problemas
Verifica que un miembro por debajo de admin no pueda crear productos ni mover pedidos, que las transiciones hacia atrás o laterales se rechacen, y que un pedido pagado no pueda cancelarse. Comprueba que los totales vienen del servidor — nunca confíes en un importe del cliente — y que el stock vuelve tras una cancelación.