KaliCart Bridge

Un plugin WooCommerce gratuit qui expose votre catalogue en direct sous forme d’API REST structurée pour les agents IA de shopping. Sans LLM, sans cloud, sans service externe — tout tourne sur votre serveur.

Tous les endpoints du catalogue lisent directement la base de données WooCommerce au moment de la requête. Les changements de prix, mises à jour de stock et nouveaux produits sont reflétés immédiatement — sans synchronisation, sans instantané, sans délai.

Installation

1. Télécharger kalicart-bridge-1.0.114.zip
2. Importer et activer depuis WP Admin → Extensions → Ajouter → Importer
3. WooCommerce doit être actif — le plugin le vérifie et alerte si ce n’est pas le cas
4. À l’activation, tous les signaux sont activés par défaut (badge, robots.txt, sitemap)
5. Rendez-vous sur WP Admin → KaliCart pour voir le tableau de bord de santé du catalogue

Endpoints

Tous les endpoints sous /wp-json/kalicart/v1/.

Document de découverte

Le point d’entrée unique. Champs clés qu’un agent doit lire :

• kalicart_agent_catalog.taxonomy — toujours merchant_native_woocommerce. Lire /catalog/categories pour les énumérer.
• public_catalog.query_construction — règles critiques pour construire correctement les requêtes de recherche.
• public_catalog.search_filters — paramètres acceptés avec valeurs autorisées.
• merchant_shipping_policy — zones de livraison déclaratives, méthodes et seuils de livraison gratuite.
• coupon_policy.price_rule — les coupons sont toujours des économies conditionnelles au checkout ; ne remplacent jamais price.current.
• agent_instructions — étapes ordonnées que l’agent doit suivre.

// 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

Recherche & filtres

La règle la plus importante : q ne doit contenir que le nom nu du produit. Tout autre attribut doit aller dans son propre filtre structuré.

Filtres disponibles

Correct vs incorrect

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

✗ incorrect — attributs empilés dans q → 0 résultat
GET /catalog/search?q=blue+men+sneakers+under+100

Récupération en cas de zéro résultat

• Réessayer avec un q plus nu — sortir les attributs de q vers leurs filtres
• GET /catalog/categories pour trouver le bon slug de catégorie
• Ne signaler « non disponible » qu’après que nom nu + parcours de catégorie aient tous deux renvoyé 0

Payload produit

Prix

• price.encoding: decimal_major_units — les valeurs sont des flottants décimaux en unités de devise pleines (ex. 29.99 = 29,99 EUR). Pas d’unités mineures ISO 4217.
• price.display: chaîne formatée en texte brut (ex. « 29,99 € ») — sans ambiguïté, à utiliser pour l’affichage.
• price.vat_included: si les prix incluent la TVA selon les paramètres fiscaux WooCommerce.
• price.price_type: STATIC pour les produits standards. Aligné sur le format KaliCart Global.
• list_price: prix catalogue original avant remises (produits simples uniquement).

• price.current — le prix catalogue faisant autorité. Toujours l’utiliser pour les décisions commerciales.
• price.on_sale, price.discount_pct — statut de promotion et pourcentage de remise sur le prix normal.
• Les produits variables renvoient price.type: "range" avec min_regular, max_regular, min_sale, max_sale.

Stock

• stock.in_stock — booléen, à vérifier avant de présenter toute offre.
• stock.availability_status — valeurs standard UCP : in_stock, out_of_stock, backorder.
• stock.quantity — numérique si le marchand gère la quantité en stock ; null sinon.
• stock.quantity_tracked — booléen, si le marchand gère le stock numérique.
• stock.backorder_allowed — booléen, true si la commande en réapprovisionnement est notify ou yes.
• stock.confidence — numeric_stock_quantity (compte exact), availability_status_only (le marchand n’expose pas la quantité — à traiter comme disponible, pas comme un inventaire confirmé), ou variant_dependent (sélectionner d’abord une variante).
• stock.agent_note — présent quand la confiance n’est pas numeric_stock_quantity. À lire avant de signaler la disponibilité.

Attributs calculés

• gender — déduit de l’attribut pa_gender, des mots-clés du chemin de catégorie, des tags, du nom du produit. null si indéterminé.
• colors[] — familles de couleurs mappées depuis pa_color / pa_colore. Chaque entrée a family et raw.
• sizes — extraites de pa_size / pa_taglia. Type auto-détecté : clothing, numeric ou shoes.

Aptitude à l’achat

• purchase_readiness.status — direct_cart_possible (produit simple en stock, utiliser checkout_url directement) ou variant_selection_required (produit variable, l’utilisateur doit d’abord sélectionner une variante).
• purchase_readiness.blocking_fields[] — attributs que l’utilisateur doit choisir avant le checkout (ex. ["size"]).
• purchase_readiness.can_add_to_cart_directly — raccourci booléen.

Variants & Variations

• variants[] — toujours un tableau, jamais null. Détail produit : les produits variables exposent toutes les variations avec attributes, price, in_stock, availability_status, sku, barcodes ; les produits simples exposent une entrée unique avec les données propres du produit. Réponses de liste et de recherche : les produits simples gardent leur entrée unique, les produits variables renvoient un tableau vide pour la performance — récupérer /catalog/product/{id} pour la liste complète des variantes.
• variations[] — alias pour les produits variables uniquement (compatibilité ascendante).
• Transmettre variation_id dans le payload de la session de checkout lors de la création d’une session pour un produit variable.
• availability_status — valeurs standard UCP : in_stock, out_of_stock, backorder. Présent à la fois sur le stock produit et sur chaque variante.
• list_price — prix catalogue original avant remises (barré). Présent sur les produits simples ; null sur les variables (le prix varie par variante).
• barcodes[] — identifiants standards du secteur (EAN, GTIN, UPC) lus depuis les métadonnées produit WooCommerce. Tableau vide si non renseigné par le marchand.

Metadata

• metadata.purchase_readiness — identique au purchase_readiness de premier niveau, exposé ici pour les agents compatibles UCP qui lisent metadata.
• metadata.stock_confidence — niveau de confiance des données de stock.
• metadata.bridge_version — version du plugin ayant généré cette réponse.

Zones de livraison

shipping.zones[] expose la configuration de livraison WooCommerce complète : nom de zone, codes pays/région, méthodes (free_shipping, flat_rate, local_pickup) avec coûts et seuil de livraison gratuite. Calculé une fois par requête et mis en cache. Le coût de livraison faisant autorité est toujours le checkout WooCommerce.

Checkout

checkout_url — ajout direct au panier pour les produits simples en stock. Page produit pour les produits variables où la sélection de variante est requise.

Pour les parcours multi-produits, utilisez les Sessions de checkout ci-dessous.

Livraison & coupons

Livraison

Le document de découverte contient merchant_shipping_policy — un instantané des zones de livraison WooCommerce, des méthodes et des seuils de livraison gratuite. Chaque produit porte aussi un champ shipping avec un contexte au niveau produit (classe, poids, éligibilité à la livraison gratuite au prix actuel). Le checkout WooCommerce fait autorité en dernier ressort pour les coûts spécifiques à la destination.

Coupons

Chaque produit porte active_coupons[] — coupons actifs applicables à ce produit ou cette catégorie. Ne jamais remplacer price.current par une valeur ajustée par un coupon. Présentez le prix catalogue ; proposez le code comme économie conditionnelle au checkout.

Chaque entrée coupon inclut combinable_with_sale: "unknown — verify at checkout" et verification_required: true. Un coupon n’est confirmé qu’après que le panier/checkout WooCommerce l’accepte et modifie les totaux. Les coupons peuvent être combinables avec des prix promotionnels, mais seul le checkout peut le confirmer.

// Présentation correcte de l’agent
"Price is €89. Use code SAVE20 at checkout for 20% off (≈ €17 saving)."

// Incorrect
"Price is €71.20"  ← ne jamais intégrer le coupon dans le prix

Sessions de checkout (optionnel)

Quand elle est activée par le marchand, les agents peuvent créer des sessions de checkout contenant un ou plusieurs produits. Chaque session renvoie deux URL pour l’utilisateur — pas d’OAuth, pas de PII, aucun paiement côté agent.

Réponse de session

• cart_url — un clic : ajoute tous les articles au panier, atterrit sur la page panier WooCommerce. L’utilisateur vérifie avant de payer.
• checkout_url — un clic : ajoute tous les articles au panier, redirige directement vers le checkout.
• subtotal — somme de tous les totaux d’articles aux prix catalogue. N’inclut ni livraison ni coupons.
• La session expire en 30 minutes. Transitions de statut : pending → cart_loaded.

// Session multi-produits
POST /checkout/session
{
  "items": [
    { "product_id": 1326, "quantity": 1, "variation_id": 1477 },  // obligatoire pour les produits variables
    { "product_id": 1307, "quantity": 2 }
  ]
}
→ { "cart_url": "...", "checkout_url": "...", "subtotal": 651 }

Signaux pour agents

Les quatre signaux sont injectés automatiquement à l’activation — aucun code manuel requis.

Catalogue fédéré

Un réseau de découverte ouvert et optionnel. Le Bridge rend votre catalogue lisible par les agents qui sont déjà sur votre domaine ; le Catalogue fédéré le rend découvrable par les agents qui ne connaissent pas encore votre boutique. Opt-in, service séparé, révocable à tout moment.

Deux parcours de découverte distincts — faciles à confondre, autant les préciser clairement :

Comment cela fonctionne, de bout en bout :

La révocation est symétrique : décochez le consentement et le plugin signale à KaliCart Global de se désenregistrer ; votre catalogue est mis en pause et quitte les résultats fédérés, tandis que l’accès direct des agents à votre boutique reste actif.

Tableau de bord de santé du catalogue

Rapport de qualité du catalogue en temps réel depuis WP Admin → KaliCart.

• Quality score — moyenne pondérée de 0 à 100 sur tous les produits selon la gravité des problèmes.
• Quality signals — produits avec des problèmes de gravité haute ou moyenne (description manquante, prix zéro, pas de catégorie). Rien n’est bloqué : ces produits restent pleinement servis aux agents, mais les problèmes voyagent comme des drapeaux de qualité déclarés et abaissent le score. Chaque entrée renvoie directement à l’écran d’édition produit WP.
• Soft alerts — images manquantes et SKU manquants apparaissent comme des suggestions de faible priorité et ne comptent pas comme quality signals.
• Suggestions — liste priorisation des améliorations du catalogue avec le nombre de produits concernés.