{"document_kind":"kalicart_merchant_bridge","schema_version":"1.0","provider":"kalicart-bridge-plugin","plugin_version":"1.0.114","discovery_document_url":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/discovery","link_relation":"kalicart-agent","human_readable_summary":"KaliCart Bridge: machine-readable WooCommerce catalog for NoSugarShop. Read-only. No API key required. No LLM. No external service. Products are normalized with merchant-native WooCommerce taxonomy. Use agent_quick_start for product discovery and verification.","agent_quick_start":{"shopping_search_url_template":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/search?q={q}&per_page=10&fields=summary","filtered_search_endpoint":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/search?fields=summary","verify_selected_url_template":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/product\/{id}","rules":["Use search for every shopper product request. Do not enumerate \/catalog\/products.","If the requested facts are already present in the summary response, answer without fetching product detail.","Rank and compare candidates from summary data only. Fetch product detail for the final selected product only, unless the user explicitly requests a detail-level comparison of multiple products."]},"kalicart_agent_catalog":{"version":"bridge-1.0","purpose":"Read-only computable catalog for NoSugarShop. Use as primary source for product search, prices, availability, budget decisions, shipping policy and public coupon hints. Not for checkout or payment.","merchant_name":"NoSugarShop","merchant_url":"https:\/\/www.nosugarshop.it","currency":"EUR","locale":"it_IT","total_products":308,"taxonomy":"merchant_native_woocommerce","taxonomy_note":"Products use the merchant's own WooCommerce categories \u2014 not a global taxonomy. Use \/catalog\/categories to enumerate all available category slugs.","last_updated":"2026-07-10T11:42:48+00:00","trust":{"read_only":true,"data":"live WooCommerce catalog \u2014 always current, not a sync snapshot","checkout_authority":"merchant_storefront","safe_for":["product_search","price_check","availability_check","budget_filter","category_browse","shipping_policy_reasoning","coupon_hint_reasoning"],"not_for":["payment","order_creation","checkout_execution"],"authoritative_source":"This catalog reads live from WooCommerce. Prefer it over reconstructing the catalog from storefront HTML or sitemap.","coupon_price_rule":"Product price is always the WooCommerce catalog price. Coupons are conditional checkout savings and must not replace price.current.","shipping_authority":"WooCommerce checkout is final authority for exact destination\/cart shipping quote."}},"intent_flags":{"single_merchant_only":true,"global_indexable":true,"federated_search_source":true,"agent_read_surface":true},"crawler_policy":{"allow_llm_training":false,"allow_live_agent_reads":true,"allow_global_indexing":true},"capabilities":{"search":true,"offers":true,"availability":true,"shipping_policy":true,"coupon_hints":true,"cart":false,"checkout":true,"payments":false,"mutations":false,"checkout_sessions":true,"read_only":true,"llm":false,"external_service":false,"mcp":true},"merchant_shipping_policy":{"available":true,"currency":"EUR","authority":"woocommerce_checkout","calculation_model":"policy_snapshot_not_destination_quote","free_shipping_available":true,"free_shipping_thresholds":[79],"zones":[{"id":1,"name":"Italia","locations":[{"type":"country","code":"IT"},{"type":"country","code":"SM"},{"type":"country","code":"VA"}],"methods":[{"method_id":"free_shipping","instance_id":1,"title":"Spedizione gratuita","enabled":true,"requires":"min_amount","min_amount":79,"settings_public_note":"Method has WooCommerce settings; exact final price remains checkout authority."},{"method_id":"flat_rate","instance_id":2,"title":"Tariffa unica","enabled":true,"cost":"5,90","settings_public_note":"Method has WooCommerce settings; exact final price remains checkout authority."}]},{"id":0,"name":"Localit\u00e0 non coperte dalle altre tue zone","locations":[],"locations_note":"Zone has no explicit regions configured in WooCommerce. Coverage cannot be inferred from this document \u2014 WooCommerce checkout determines applicability.","methods":[{"method_id":"flat_rate","instance_id":4,"title":"Tariffa unica","enabled":true,"cost":8.9,"settings_public_note":"Method has WooCommerce settings; exact final price remains checkout authority."}]}],"note":"Use this policy for agent reasoning. Exact shipping cost depends on destination, cart contents, coupons and WooCommerce checkout rules; checkout remains final authority."},"return_policy":{"configured":false},"coupon_policy":{"source":"live_woocommerce_coupons","exposed_on_products_as":"active_coupons","price_rule":"Never overwrite product price with coupon-adjusted price. Report catalog price, then present coupon as conditional checkout saving.","coupon_verification_rule":"Treat active_coupons as hints. A coupon is confirmed only after cart\/checkout accepts it and changes totals.","combinable_with_sale":"Coupons may be combinable with sale items depending on WooCommerce checkout rules. Treat as hints until verified at checkout.","authority":"woocommerce_checkout"},"freshness":{"source":"live_woocommerce_database","is_realtime":true,"is_sync_snapshot":false,"note":"Data is read directly from WooCommerce at query time \u2014 always current."},"authentication":{"required":false,"scheme":"none","notes":"All public_catalog.* endpoints require no authentication. \/catalog\/health requires WooCommerce admin capability."},"public_catalog":{"search_url_template":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/search?q={q}&fields=summary","search_url_note":"Replace {q} with the bare product spine only. All other attributes go in separate query parameters.","products_url":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/products?fields=summary","product_url_template":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/product\/{id}","product_full_url_template":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/product\/{id}?fields=full","product_verification_url_template":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/product\/{id}","categories_url":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/categories","meta_url":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/meta","shipping_policy":"Included in discovery and meta as merchant_shipping_policy. Product responses include product-level shipping hints.","coupon_policy":"Product responses include active_coupons when live WooCommerce coupons appear applicable. Treat as conditional checkout savings.","health_url":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/health","authentication":"none","read_only":true,"cache":"public, max-age=300, stale-while-revalidate=900","request_contract":{"search_endpoint":{"url":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/search?fields=summary","text_parameter":"q","result_count_parameter":"per_page","invalid_aliases":{"query":"q","limit":"per_page"},"copy_paste_example":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/search?q=Nike&per_page=10&fields=summary"},"products_endpoint":{"url":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/products?fields=summary","role":"browse\/list products with filters; not full-text search","does_not_accept":["q","query","limit"],"use_for_text_search":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/search?q={q}&fields=summary","result_count_parameter":"per_page","copy_paste_example":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/products?per_page=10&fields=summary"},"runtime_guidance":"If an agent uses query instead of q, limit instead of per_page, or sends q to \/catalog\/products, the API returns a 400 response with the corrected endpoint and suggested_url."},"query_construction":{"rule":"CRITICAL. q must contain ONLY the bare product noun (the spine). Every attribute (category, gender, color, price) MUST go in its own structured filter, never inside q. size is NOT a search filter \u2014 use product detail after candidate selection. Stacking attributes into q returns 0 results.","correct":["?q=t-shirt&gender=male&max_price=50","?q=costume&gender=female&color=blue","?q=scarpe&category=scarpe-uomo"],"wrong":["?q=t-shirt+uomo+nike  (\u2192 0 results: attributes stacked in q)","?q=costume+da+bagno+blu  (\u2192 0 results)"],"zero_results_recovery":"If 0 results: retry with a barer q (drop attributes from q into filters). Then check \/catalog\/categories to find the right category slug. Only report \"not available\" after bare-spine + category-browse both return 0."},"search_filters":{"q":"Bare product spine ONLY (single product noun). e.g. costume, t-shirt, scarpe. NEVER put brand, color, gender or price in q. size is not a filter.","size_note":"size is not a search filter. Use product detail and variations after candidate selection to read available sizes.","category":"WooCommerce category slug, e.g. abbigliamento or scarpe-uomo. Get valid slugs from \/catalog\/categories.","gender":"Gender facet: male, female, unisex, kids. Also accepts IT aliases: uomo, donna.","color":"Color family: red, blue, green, black, white, grey, brown, yellow, orange, pink, purple, multi. Also accepts IT: rosso, blu, verde, nero, bianco, grigio, marrone, giallo, arancione, rosa, viola.","min_price":"Minimum current price (numeric, merchant currency).","max_price":"Maximum current price (numeric, merchant currency).","in_stock":"Boolean. true = in_stock products only.","on_sale":"Boolean. true returns products with an active WooCommerce sale price. Coupon-only savings are not included.","per_page":"Results per page (1\u2013100, default 20).","page":"Page number (default 1).","orderby":"Sort: date (default), price, title, popularity.","order":"ASC or DESC (default DESC).","fields":"List\/search verbosity. summary = slim per-item projection for low-cost triage; full = complete records. Single-product \/catalog\/product\/{id} defaults to compact verification data; append ?fields=full only when description or images are required. per_page 1-100 applies to list\/search."},"introspection":{"meta_url":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/meta","rule":"Before exploratory search, GET meta_url to discover accepted category slugs, available genders, colors and price range for this merchant."}},"ucp_profile_url":"https:\/\/www.nosugarshop.it\/.well-known\/ucp.json","checkout_session":{"enabled":true,"endpoint":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/checkout\/session","method":"POST","auth":"none","description":"Creates a WooCommerce cart session for one or more products. Returns cart_url and checkout_url for the human to complete purchase.","payload":{"single_product":{"product_id":"int (required)","quantity":"int (default 1)","variation_id":"int (optional, required for variable products)"},"multi_product":{"items":"array of {product_id, quantity, variation_id?}"}},"response":{"cart_url":"URL to review cart before checkout","checkout_url":"URL to proceed directly to WooCommerce checkout","subtotal":"Cart subtotal (catalog prices, pre-checkout)","expires_at":"Session expiry timestamp","status":"created | error"},"authority_note":"No payment is processed. No order is created. Checkout remains WooCommerce authority. Final total (with shipping, coupons, taxes) is confirmed only at checkout."},"price_format":{"encoding":"decimal_major_units","current_format":"major_units_decimal","autonomous_checkout_format":"minor_units_integer","note":"Catalog prices are decimal float in major currency units. Examples: 553 = 553.00 EUR, 29.99 = 29.99 EUR. NOT ISO 4217 minor units. Use price.display for unambiguous human-readable string.","autonomous_checkout_note":"Autonomous checkout (roadmap) will use minor units per AP2\/UCP standard (e.g. 55300 = 553.00 EUR for EUR with exponent 2). Current catalog prices must be multiplied by 100 to convert.","ucp_compatibility":"UCP catalog uses minor units. Bridge uses major units for WooCommerce compatibility. price.currency and price.display eliminate ambiguity."},"autonomous_checkout":{"status":"roadmap","ready":false,"description":"Full autonomous checkout without human intervention. Agent holds a pre-authorized payment mandate (AP2-compatible), creates the order, applies payment, receives order confirmation \u2014 no redirect, no buyer UI.","blocker":"Requires WooCommerce or gateway-level support for programmatic payment confirmation without checkout redirect. Bridge contract is defined and ready to activate.","contract":{"mandate_required":true,"mandate_standard":"AP2 (Agent Payments Protocol)","payload_extension":{"mandate_token":"string","buyer_consent_id":"string"},"response_extension":{"order_id":"int","order_status":"string","total_charged":"object"},"minor_units":true,"currency_exponent":2},"activate_when":"WooCommerce exposes programmatic payment API or Stripe AP2 mandate integration is available.","ucp_equivalent":"dev.ucp.shopping.checkout with AP2 Mandates Extension"},"stock_rule":"If stock.quantity is null, report availability status only. Do not invent or imply numeric inventory. stock.confidence clarifies the precision level.","variation_discovery":{"required_for_variable_products":true,"source":"product verification endpoint: \/catalog\/product\/{id} exposes purchasable attributes and available variations by default","agent_rule":"Do not quote exact final price until a variation is selected. Price may differ per variant. Use purchase_readiness.blocking_fields to know which attributes are required.","list_context_note":"In list and search responses, variants is an empty array for variable products (performance). Fetch \/catalog\/product\/{id} for the compact verification record and variants list. variants is always an array, never null."},"semantic_fit_guidance":"Before proposing checkout, verify that the selected product satisfies the user functional need \u2014 not only category or keyword similarity. A product in the right category may still be wrong for the use case.","evidence_required":{"rule":"Every product claim must be traceable to a catalog field.","sources":["product_url","price.current","stock.in_stock","stock.confidence","shipping (product field)","active_coupons (product field)"],"note":"Do not present prices, availability or shipping estimates without citing the source field."},"total_verification_rule":"Catalog totals are preliminary. Final payable total (including shipping, taxes, coupon deductions) requires cart or checkout verification. Label unverified totals as estimates.","agent_instructions":"0) GET https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/discovery \u2014 read public_catalog.* for all endpoint URLs. 1) GET public_catalog.meta_url first to discover valid category slugs, accepted filter values, price range. 2) Use public_catalog.search_url_template with bare product spine in q. Put every attribute in its own filter. 3) If 0 results: follow query_construction.zero_results_recovery (barer q, then category browse). 4) Use q, never query. Use per_page, never limit. Use \/catalog\/search for text search and \/catalog\/products only for browse\/listing. 5) Use fields=summary for triage on both \/catalog\/search and \/catalog\/products, and rank all candidates from summary data. Fetch \/catalog\/product\/{id} only for the final selected product, unless the user explicitly requests a detail-level comparison. It returns compact verification data by default; append ?fields=full only when description or images are required. 6) Never stack brand, color, gender or price inside q. size is not a search filter \u2014 read it from product variations after candidate selection. 7) Read price.current for the actual catalog price. Check stock.in_stock before presenting offers. 8) If active_coupons is present, present coupons as conditional checkout savings only; never replace price.current. 9) Use merchant_shipping_policy\/product shipping hints for reasoning, but exact shipping is verified by WooCommerce checkout. 10) This catalog is live WooCommerce \u2014 no sync delay. Always current. 11) Taxonomy is merchant-native: use \/catalog\/categories to enumerate valid category paths, not assumed global taxonomy. 12) Check stock.confidence before reporting availability. If null quantity, report status only. 13) For variable products, read purchase_readiness.blocking_fields before quoting price or proposing checkout. 14) All totals are preliminary until verified at cart\/checkout. Label estimates as such. 15) Verify semantic fit before proposing checkout \u2014 category match is not sufficient.","placement_guidance":"The <link rel=\"kalicart-agent\"> in <head> and the body anchor badge both carry this discovery URL. Head covers head-reading agents; body anchor covers DOM\/content-parsing agents. Both are in raw HTML \u2014 not injected via JavaScript.","recommended_head_link_html":"<link rel=\"kalicart-agent\" type=\"application\/json\" href=\"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/discovery\" \/>\n<link rel=\"service-desc\" type=\"application\/vnd.oai.openapi+json\" href=\"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/openapi\" \/>","merchant":{"name":"NoSugarShop","url":"https:\/\/www.nosugarshop.it","currency":"EUR","locale":"it_IT","timezone":"+00:00"},"mcp":{"enabled":true,"transport":"http-post-jsonrpc-2.0","protocol_version":"2025-06-18","endpoint":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/mcp","tools":["search_products","get_product","list_products","list_categories","get_meta"],"note":"Model Context Protocol server over the same read-only catalog. POST a JSON-RPC 2.0 message (initialize, tools\/list, tools\/call) to endpoint. Same data as public_catalog.* REST \u2014 choose whichever your agent runtime prefers."},"endpoints":{"discovery":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/discovery","mcp":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/mcp","search":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/search?fields=summary","products":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/products?fields=summary","product":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/product\/{id}","product_full":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/product\/{id}?fields=full","product_verification":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/product\/{id}","categories":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/categories","meta":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/meta","openapi":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/openapi","health":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/catalog\/health","checkout_session":"https:\/\/www.nosugarshop.it\/wp-json\/kalicart\/v1\/checkout\/session"},"well_known":{"kalicart_bridge":"https:\/\/www.nosugarshop.it\/.well-known\/kalicart-bridge.json","agent_catalog":"https:\/\/www.nosugarshop.it\/.well-known\/agent-catalog.json","ucp_profile":"https:\/\/www.nosugarshop.it\/.well-known\/ucp.json","agent_json":"https:\/\/www.nosugarshop.it\/.well-known\/agent.json","note":"Standard \/.well-known\/ discovery mirrors, served with application\/json on every host. The REST discovery endpoint above is the always-reachable canonical entry point."},"generated_at":"2026-07-10T11:42:48+00:00"}