Saltar al contenido principal

APIs Headless Commerce (roadmap)

Estado 2026-08: este documento describe el blueprint commerce.
Fuente de verdad implementada: OpenAPI Core, CMS Runtime, Handoff CRM.

El CMS y CRM deals productivos no usan rutas /cms/posts ni Drizzle/Fastify. El backend canónico es Go UAP.

Blueprint histórico (no afirmar como productivo)​

GET /api/v1/cms/posts (planificado / legado)​

  • Parámetros Query: limit (int, default: 50), offset (int, default: 0)
  • Descripción: Idea de publicaciones; en Core actual usar content types + pages.

POST /api/v1/cms/posts (planificado / legado)​

  • Body (JSON): 
    {
      "title": "Nuevos Términos de Servicio 2026",
      "slug": "terminos-servicio-2026",
      "content": "Contenido completo para consumo humano e indexación RAG...",
      "status": "published",
      "metadata": { "category": "Legal", "author": "Equipo Legal" }
    }
  • Comportamiento RAG: Si status es "published", el servidor genera una entrada en la tabla knowledge_embeddings (con source_module: 'cms'), disponible inmediatamente para consultas de los agentes AI sin duplicación de bases de datos vectoriales.

2. Universal Marketplace & ERP Inventarios (/api/v1/erp)​

GET /api/v1/erp/products​

  • Descripción: Consulta en tiempo real el stock y precios del catálogo para frontends Headless E-Commerce.
  • Respuesta: Lista de productos con SKU, precio en centavos, stock físico y tasa de IVA (taxRateBasisPoints).

POST /api/v1/erp/products​

  • Descripción: Crea un nuevo producto y despacha un Webhook firmado (erp.inventory.updated) a los conectores suscritos.

POST /api/v1/erp/orders​

  • Body (JSON): 
    {
      "clientId": 104,
      "paymentMethod": "stripe_card",
      "items": [
        { "productId": 1, "quantity": 2, "unitPrice": 45000 }
      ]
    }
  • Comportamiento: Calcula automáticamente impuestos (19% IVA estándar), inserta la cabecera e ítems en Drizzle ORM de forma atómica y despacha el evento criptográfico erp.order.created mediante el WebhookDispatcher con firma HMAC SHA-256.

3. CRM Inteligencia de Ventas & Analítica (/api/v1/crm)​

POST /api/v1/crm/events​

  • Descripción: Registra clics, visitas o interacciones transaccionales en e-commerce sin cookies de terceros.
  • Payload: { "eventType": "add_to_cart", "customerRef": "usr_789", "eventData": { "sku": "COL-AI-PRO" } }

POST /api/v1/crm/recover-abandoned-carts​

  • Descripción: Analiza la tabla crm_abandoned_carts, selecciona carritos pendientes e invoca estrategias IA de recomendación y generación de cupones automáticos para incrementar la conversión en un 34%.

POST /api/v1/crm/support-tickets​

  • Descripción: Recepción de PQRS e incidencias desde clientes finales con trazabilidad hacia los deals en curso.

4. Licenciamiento y App Hub ("A la Carta")​

PATCH /api/v1/tenants/:id/licensed-modules​

Permite activar o desactivar módulos individuales en el clúster sin duplicar bases de datos ni servicios en segundo plano.

  • Payload: { "appCode": "cms", "isEnabled": true }
  • Seguridad: Protegido contra vulnerabilidades IDOR; valida rigurosamente que el JWT corresponda al Tenant autenticado de la sucursal o super-administrador ZITADEL.