KaliCart Bridge

Un plugin WooCommerce gratuito che espone il tuo catalogo live come API REST strutturata per gli agenti AI di shopping. Niente LLM, niente cloud, nessun servizio esterno — tutto gira sul tuo server.

Tutti gli endpoint del catalogo leggono direttamente dal database WooCommerce al momento della query. Cambi di prezzo, aggiornamenti di stock e nuovi prodotti si riflettono immediatamente — niente sync, niente snapshot, niente ritardo.

Installazione

1. Scarica kalicart-bridge-1.0.114.zip
2. Carica e attiva da WP Admin → Plugin → Aggiungi nuovo → Carica
3. WooCommerce deve essere attivo — il plugin lo verifica e avvisa in caso contrario
4. All’attivazione tutti i segnali sono abilitati di default (badge, robots.txt, sitemap)
5. Vai su WP Admin → KaliCart per la dashboard salute del catalogo

Endpoint

Tutti gli endpoint sotto /wp-json/kalicart/v1/.

Documento di discovery

Il punto di ingresso unico. Campi chiave che un agente deve leggere:

• kalicart_agent_catalog.taxonomy — sempre merchant_native_woocommerce. Leggi /catalog/categories per enumerarle.
• public_catalog.query_construction — regole critiche per costruire correttamente le query di ricerca.
• public_catalog.search_filters — parametri accettati con i valori consentiti.
• merchant_shipping_policy — zone di spedizione dichiarative, metodi e soglie di spedizione gratuita.
• coupon_policy.price_rule — i coupon sono sempre risparmi condizionali al checkout; mai sostituire price.current.
• agent_instructions — passi ordinati che l’agente deve seguire.

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

Ricerca e filtri

La regola più importante: q deve contenere solo il sostantivo nudo del prodotto. Ogni altro attributo va nel proprio filtro strutturato.

Filtri disponibili

Giusto vs sbagliato

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

✗ sbagliato — attributi impilati in q → 0 risultati
GET /catalog/search?q=blue+men+sneakers+under+100

Recupero da zero risultati

• Riprova con una q più nuda — sposta gli attributi da q ai loro filtri
• GET /catalog/categories per trovare lo slug di categoria corretto
• Riferisci "non disponibile" solo dopo che sostantivo-nudo + browse-categoria hanno entrambi restituito 0

Payload prodotto

Prezzo

• price.encoding: decimal_major_units — i valori sono float decimali in unità di valuta piene (es. 29.99 = 29,99 EUR). Non unità minori ISO 4217.
• price.display: stringa formattata in testo semplice (es. "29,99 €") — non ambigua, usala per la presentazione.
• price.vat_included: se i prezzi includono l’IVA secondo le impostazioni fiscali WooCommerce.
• price.price_type: STATIC per i prodotti standard. Allineato al formato KaliCart Global.
• list_price: prezzo di listino originale prima degli sconti (solo prodotti semplici).

• price.current — il prezzo autoritativo del catalogo. Usa sempre questo per le decisioni commerciali.
• price.on_sale, price.discount_pct — stato di saldo e percentuale di sconto sul prezzo pieno.
• I prodotti variabili restituiscono price.type: "range" con min_regular, max_regular, min_sale, max_sale.

Stock

• stock.in_stock — booleano, verificalo prima di presentare qualsiasi offerta.
• stock.availability_status — UCP-standard values: in_stock, out_of_stock, backorder.
• stock.quantity — numerico se il merchant gestisce la quantità di stock; null altrimenti.
• stock.quantity_tracked — booleano, se il merchant gestisce lo stock numerico.
• stock.backorder_allowed — booleano, true se il backorder è notify o yes.
• stock.confidence — numeric_stock_quantity (conteggio esatto), availability_status_only (il merchant non espone la quantità — trattalo come disponibile, non come inventario confermato), o variant_dependent (seleziona prima una variazione).
• stock.agent_note — presente quando la confidenza non è numeric_stock_quantity. Leggilo prima di riferire la disponibilità.

Attributi calcolati

• gender — inferito dall’attributo pa_gender, keyword nel percorso categoria, tag, nome prodotto. null se indeterminato.
• colors[] — famiglie di colore mappate da pa_color / pa_colore. Ogni voce ha family e raw.
• sizes — estratte da pa_size / pa_taglia. Tipo auto-rilevato: clothing, numeric o shoes.

Prontezza all’acquisto

• purchase_readiness.status — direct_cart_possible (prodotto semplice disponibile, usa checkout_url direttamente) o variant_selection_required (prodotto variabile, l’utente deve prima selezionare una variante).
• purchase_readiness.blocking_fields[] — attributi che l’utente deve scegliere prima del checkout (es. ["size"]).
• purchase_readiness.can_add_to_cart_directly — scorciatoia booleana.

Varianti e variazioni

• variants[] — sempre un array, mai null. Dettaglio prodotto: i prodotti variabili espongono tutte le variazioni con attributes, price, in_stock, availability_status, sku, barcodes; i prodotti semplici espongono una singola voce coi dati del prodotto stesso. Risposte di elenco e ricerca: i prodotti semplici mantengono la loro voce singola, i variabili restituiscono un array vuoto per performance — recupera /catalog/product/{id} per la lista varianti completa.
• variations[] — alias solo per prodotti variabili (retrocompatibilità).
• Passa variation_id nel payload della sessione di checkout quando crei una sessione per un prodotto variabile.
• availability_status — valori standard UCP: in_stock, out_of_stock, backorder. Presente sia sullo stock del prodotto sia su ogni variante.
• list_price — prezzo di listino originale prima degli sconti (barrato). Presente sui prodotti semplici; null sui variabili (il prezzo varia per variante).
• barcodes[] — identificatori standard di settore (EAN, GTIN, UPC) letti dai meta prodotto WooCommerce. Array vuoto se non impostati dal merchant.

Metadati

• metadata.purchase_readiness — uguale al purchase_readiness di primo livello, esposto qui per gli agenti compatibili UCP che leggono metadata.
• metadata.stock_confidence — livello di confidenza dei dati di stock.
• metadata.bridge_version — versione del plugin che ha generato questa risposta.

Zone di spedizione

shipping.zones[] espone la configurazione di spedizione WooCommerce completa: nome zona, codici paese/regione, metodi (free_shipping, flat_rate, local_pickup) con costi e soglia di spedizione gratuita. Calcolata una volta per richiesta e messa in cache. Il costo di spedizione autoritativo è sempre il checkout WooCommerce.

Checkout

checkout_url — aggiunta diretta al carrello per prodotti semplici disponibili. Pagina prodotto per i variabili dove serve la selezione della variante.

Per flussi multi-prodotto usa le Sessioni di checkout qui sotto.

Spedizioni e coupon

Spedizioni

Il documento di discovery contiene merchant_shipping_policy — uno snapshot delle zone di spedizione WooCommerce, dei metodi e delle soglie di spedizione gratuita. Ogni prodotto porta anche un campo shipping con contesto a livello prodotto (classe, peso, idoneità alla spedizione gratuita al prezzo corrente). Il checkout WooCommerce è l’autorità finale per i costi specifici di destinazione.

Coupon

Ogni prodotto porta active_coupons[] — coupon attivi applicabili a quel prodotto o categoria. Mai sostituire price.current con un valore aggiustato dal coupon. Presenta il prezzo di catalogo; offri il codice come risparmio condizionale al checkout.

Ogni voce coupon include combinable_with_sale: "unknown — verify at checkout" e verification_required: true. Un coupon è confermato solo dopo che il carrello/checkout WooCommerce lo accetta e cambia i totali. I coupon possono essere combinabili coi prezzi in saldo, ma solo il checkout può confermarlo.

// Presentazione corretta dell’agente
"Price is €89. Use code SAVE20 at checkout for 20% off (≈ €17 saving)."

// Sbagliato
"Price is €71.20"  ← mai calcolare il coupon nel prezzo

Sessioni di checkout (opzionale)

Quando abilitato dal merchant, gli agenti possono creare sessioni di checkout con uno o più prodotti. Ogni sessione restituisce due URL per l’utente — niente OAuth, niente PII, nessun pagamento lato agente.

Risposta della sessione

• cart_url — un click: aggiunge tutti gli articoli al carrello, atterra sulla pagina carrello WooCommerce. L’utente rivede prima di pagare.
• checkout_url — un click: aggiunge tutti gli articoli al carrello, reindirizza direttamente al checkout.
• subtotal — somma dei totali articolo a prezzi di catalogo. Non include spedizioni né coupon.
• La sessione scade in 30 minuti. Transizioni di stato: pending → cart_loaded.

// Sessione multi-prodotto
POST /checkout/session
{
  "items": [
    { "product_id": 1326, "quantity": 1, "variation_id": 1477 },  // obbligatorio per i prodotti variabili
    { "product_id": 1307, "quantity": 2 }
  ]
}
→ { "cart_url": "...", "checkout_url": "...", "subtotal": 651 }

Segnali per agenti

Tutti e quattro i segnali vengono iniettati automaticamente all’attivazione — nessun codice manuale richiesto.

Catalogo federato

Una rete di discovery aperta e opzionale. Il Bridge rende il tuo catalogo leggibile dagli agenti che sono già sul tuo dominio; il Catalogo federato lo rende scopribile dagli agenti che ancora non conoscono il tuo negozio. Opt-in, servizio separato, revocabile in qualsiasi momento.

Due percorsi di discovery distinti — facili da confondere, quindi meglio dirlo chiaramente:

Come funziona, dall’inizio alla fine:

La revoca è simmetrica: togli la spunta al consenso e il plugin segnala a KaliCart Global di deregistrare; il tuo catalogo viene parcheggiato ed esce dai risultati federati, mentre l’accesso diretto degli agenti al tuo negozio resta attivo.

Dashboard salute del catalogo

Report qualità catalogo in tempo reale da WP Admin → KaliCart.

• Quality score — media pesata 0–100 su tutti i prodotti in base alla gravità dei problemi.
• Quality signals — prodotti con problemi di gravità alta o media (descrizione mancante, prezzo zero, nessuna categoria). Nulla viene bloccato: questi prodotti restano pienamente serviti agli agenti, ma i problemi viaggiano come quality flag dichiarati e abbassano il punteggio. Ogni voce punta direttamente alla schermata di modifica prodotto WP.
• Soft alerts — immagini mancanti e SKU mancanti compaiono come suggerimenti a bassa priorità e non contano come quality signal.
• Suggestions — lista prioritizzata di miglioramenti al catalogo con conteggio dei prodotti coinvolti.