KaliCart Bridge

Un plugin WooCommerce gratuito que expone su catálogo en vivo como una API REST estructurada para agentes de compra de IA. Sin LLM, sin nube, sin servicio externo — todo se ejecuta en su servidor.

Todos los endpoints del catálogo leen directamente de la base de datos WooCommerce en el momento de la consulta. Los cambios de precio, actualizaciones de stock y nuevos productos se reflejan de inmediato — sin sincronización, sin instantánea, sin demora.

Instalación

1. Descargue kalicart-bridge-1.0.114.zip
2. Suba y active desde WP Admin → Plugins → Añadir nuevo → Subir
3. WooCommerce debe estar activo — el plugin lo comprueba y avisa si no lo está
4. Al activarse, todas las señales están habilitadas por defecto (badge, robots.txt, sitemap)
5. Visite WP Admin → KaliCart para ver el panel de salud del catálogo

Endpoints

Todos los endpoints bajo /wp-json/kalicart/v1/.

Documento de descubrimiento

El único punto de entrada. Campos clave que un agente debe leer:

• kalicart_agent_catalog.taxonomy — siempre merchant_native_woocommerce. Lea /catalog/categories para enumerarlas.
• public_catalog.query_construction — reglas críticas para construir correctamente las consultas de búsqueda.
• public_catalog.search_filters — parámetros aceptados con valores permitidos.
• merchant_shipping_policy — zonas de envío declarativas, métodos y umbrales de envío gratuito.
• coupon_policy.price_rule — los cupones son siempre ahorros condicionales en el checkout; nunca reemplazan price.current.
• agent_instructions — pasos ordenados que el agente debe seguir.

// Minimal agent bootstrap
GET /wp-json/kalicart/v1/discovery
→ read public_catalog.* for all endpoint URLs
→ read merchant_shipping_policy for shipping reasoning
→ read agent_instructions for query rules

Búsqueda y filtros

La regla más importante: q debe contener solo el sustantivo desnudo del producto. Cualquier otro atributo debe ir en su propio filtro estructurado.

Filtros disponibles

Correcto vs incorrecto

✓ correcto
GET /catalog/search?q=sneakers&gender=male&max_price=120&in_stock=true
GET /catalog/search?q=jacket&category=outerwear&color=black

✗ incorrecto — atributos apilados en q → 0 resultados
GET /catalog/search?q=blue+men+sneakers+under+100

Recuperación ante cero resultados

• Reintente con una q más desnuda — saque los atributos de q a sus filtros
• GET /catalog/categories para encontrar el slug de categoría correcto
• Reporte «no disponible» solo después de que tanto el núcleo desnudo como la navegación por categoría devuelvan 0

Payload del producto

Precio

• price.encoding: decimal_major_units — los valores son decimales en unidades de moneda completas (ej. 29.99 = 29,99 EUR). No son unidades menores ISO 4217.
• price.display: cadena formateada en texto plano (ej. «29,99 €») — sin ambigüedad, úsela para la presentación.
• price.vat_included: si los precios incluyen IVA según la configuración fiscal de WooCommerce.
• price.price_type: STATIC para productos estándar. Alineado con el formato de KaliCart Global.
• list_price: precio de lista original antes de descuentos (solo productos simples).

• price.current — el precio de catálogo con autoridad. Úselo siempre para decisiones comerciales.
• price.on_sale, price.discount_pct — estado de oferta y porcentaje de descuento sobre el precio normal.
• Los productos variables devuelven price.type: "range" con min_regular, max_regular, min_sale, max_sale.

Stock

• stock.in_stock — booleano, compruébelo antes de presentar cualquier oferta.
• stock.availability_status — valores estándar UCP: in_stock, out_of_stock, backorder.
• stock.quantity — numérico si el comerciante gestiona la cantidad de stock; null en caso contrario.
• stock.quantity_tracked — booleano, si el comerciante gestiona el stock numérico.
• stock.backorder_allowed — booleano, true si el pedido pendiente es notify o yes.
• stock.confidence — numeric_stock_quantity (recuento exacto), availability_status_only (el comerciante no expone la cantidad — trátelo como disponible, no como inventario confirmado), o variant_dependent (seleccione primero una variación).
• stock.agent_note — presente cuando la confianza no es numeric_stock_quantity. Léalo antes de reportar la disponibilidad.

Atributos calculados

• gender — inferido del atributo pa_gender, palabras clave de la ruta de categoría, etiquetas, nombre del producto. null si es indeterminable.
• colors[] — familias de color mapeadas desde pa_color / pa_colore. Cada entrada tiene family y raw.
• sizes — extraídas de pa_size / pa_taglia. Tipo autodetectado: clothing, numeric o shoes.

Disposición de compra

• purchase_readiness.status — direct_cart_possible (producto simple en stock, use checkout_url directamente) o variant_selection_required (producto variable, el usuario debe seleccionar primero una variante).
• purchase_readiness.blocking_fields[] — atributos que el usuario debe elegir antes del checkout (ej. ["size"]).
• purchase_readiness.can_add_to_cart_directly — atajo booleano.

Variants & Variations

• variants[] — siempre un array, nunca null. Detalle de producto: los productos variables exponen todas las variaciones con attributes, price, in_stock, availability_status, sku, barcodes; los productos simples exponen una única entrada con los propios datos del producto. Respuestas de listado y búsqueda: los productos simples mantienen su entrada única, los variables devuelven un array vacío por rendimiento — obtenga /catalog/product/{id} para la lista completa de variantes.
• variations[] — alias solo para productos variables (retrocompatibilidad).
• Pase variation_id en el payload de la sesión de checkout al crear una sesión para un producto variable.
• availability_status — valores estándar UCP: in_stock, out_of_stock, backorder. Presente tanto en el stock del producto como en cada variante.
• list_price — precio de lista original antes de descuentos (tachado). Presente en productos simples; null en variables (el precio varía por variante).
• barcodes[] — identificadores estándar de la industria (EAN, GTIN, UPC) leídos de los metadatos de producto de WooCommerce. Array vacío si el comerciante no los ha configurado.

Metadata

• metadata.purchase_readiness — igual que el purchase_readiness de nivel superior, expuesto aquí para agentes compatibles con UCP que leen metadata.
• metadata.stock_confidence — nivel de confianza de los datos de stock.
• metadata.bridge_version — versión del plugin que generó esta respuesta.

Zonas de envío

shipping.zones[] expone la configuración de envío completa de WooCommerce: nombre de zona, códigos de país/región, métodos (free_shipping, flat_rate, local_pickup) con costes y umbral de envío gratuito. Calculado una vez por solicitud y cacheado. El coste de envío con autoridad es siempre el checkout de WooCommerce.

Checkout

checkout_url — añadido directo al carrito para productos simples en stock. Página de producto para productos variables donde se requiere la selección de variante.

Para flujos multi-producto use las Sesiones de checkout de abajo.

Envío y cupones

Envío

El documento de descubrimiento contiene merchant_shipping_policy — una instantánea de las zonas de envío de WooCommerce, los métodos y los umbrales de envío gratuito. Cada producto también lleva un campo shipping con contexto a nivel de producto (clase, peso, elegibilidad de envío gratuito al precio actual). El checkout de WooCommerce es la autoridad final para los costes específicos de destino.

Cupones

Cada producto lleva active_coupons[] — cupones activos aplicables a ese producto o categoría. Nunca reemplace price.current con un valor ajustado por cupón. Presente el precio de catálogo; ofrezca el código como ahorro condicional en el checkout.

Cada entrada de cupón incluye combinable_with_sale: "unknown — verify at checkout" y verification_required: true. Un cupón se confirma solo después de que el carrito/checkout de WooCommerce lo acepte y cambie los totales. Los cupones pueden ser combinables con precios de oferta, pero solo el checkout puede confirmarlo.

// Presentación correcta del agente
"Price is €89. Use code SAVE20 at checkout for 20% off (≈ €17 saving)."

// Incorrecto
"Price is €71.20"  ← nunca calcular el cupón en el precio

Sesiones de checkout (opcional)

Cuando el comerciante lo habilita, los agentes pueden crear sesiones de checkout con uno o más productos. Cada sesión devuelve dos URL para el usuario — sin OAuth, sin PII, sin pago del lado del agente.

Respuesta de la sesión

• cart_url — un clic: añade todos los artículos al carrito, aterriza en la página de carrito de WooCommerce. El usuario revisa antes de pagar.
• checkout_url — un clic: añade todos los artículos al carrito, redirige directamente al checkout.
• subtotal — suma de todos los totales de artículos a precios de catálogo. No incluye envío ni cupones.
• La sesión expira en 30 minutos. Transiciones de estado: pending → cart_loaded.

// Sesión multi-producto
POST /checkout/session
{
  "items": [
    { "product_id": 1326, "quantity": 1, "variation_id": 1477 },  // obligatorio para productos variables
    { "product_id": 1307, "quantity": 2 }
  ]
}
→ { "cart_url": "...", "checkout_url": "...", "subtotal": 651 }

Señales para agentes

Las cuatro señales se inyectan automáticamente al activarse — no se requiere código manual.

Catálogo federado

Una red de descubrimiento abierta y opcional. El Bridge hace que su catálogo sea legible por agentes que ya están en su dominio; el Catálogo federado lo hace descubrible por agentes que aún no conocen su tienda. Opt-in, servicio independiente, revocable en cualquier momento.

Dos rutas de descubrimiento distintas — fáciles de confundir, así que conviene precisarlas con claridad:

Cómo funciona, de principio a fin:

La revocación es simétrica: desmarque el consentimiento y el plugin le indica a KaliCart Global que dé de baja el registro; su catálogo se aparca y sale de los resultados federados, mientras que el acceso directo de los agentes a su tienda permanece activo.

Panel de salud del catálogo

Informe de calidad del catálogo en tiempo real desde WP Admin → KaliCart.

• Quality score — promedio ponderado de 0 a 100 en todos los productos según la gravedad de los problemas.
• Quality signals — productos con problemas de gravedad alta o media (descripción faltante, precio cero, sin categoría). Nada se bloquea: estos productos siguen siendo servidos por completo a los agentes, pero los problemas viajan como indicadores de calidad declarados y bajan la puntuación. Cada entrada enlaza directamente a la pantalla de edición de producto de WP.
• Soft alerts — imágenes faltantes y SKU faltantes aparecen como sugerencias de baja prioridad y no cuentan como quality signals.
• Suggestions — lista priorizada de mejoras de catálogo con el número de productos afectados.