{"document_kind":"kalicart_merchant_bridge","schema_version":"1.0","provider":"kalicart-bridge-plugin","plugin_version":"1.0.144","catalog_data_version":1,"discovery_document_url":"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/discovery","link_relation":"kalicart-agent","human_readable_summary":"KaliCart Bridge: machine-readable WooCommerce catalog for Fattoria Paradiso - Azienda Agricola. 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:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/search?q={q}&per_page=10&fields=summary","filtered_search_endpoint":"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/search?fields=summary","verify_selected_url_template":"https:\/\/paradisofattoria.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 Fattoria Paradiso - Azienda Agricola. Use as primary source for product search, prices, availability, budget decisions, shipping policy and public coupon hints. Not for checkout or payment.","merchant_name":"Fattoria Paradiso - Azienda Agricola","merchant_url":"https:\/\/paradisofattoria.it","currency":"EUR","locale":"it_IT","total_products":14,"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-10-16T06:06:34+00:00","trust":{"read_only":true,"data":"Read from WooCommerce at request time, not from a sync snapshot. Caching, plugins or the store being offline can still make a response differ from the storefront: verify price, stock and variant on the product page before committing.","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},"commerce_distribution":{"schema_version":1,"global_active":true,"providers":{"openai_acp":{"authorized":false,"purpose":"product_discovery","consent_id":null,"occurred_at":null,"terms_version":"commerce-consent-1.0","canonical_text_hash":null,"consent_text_hash":null,"previous_record_hash":null,"record_hash":null}}},"kalicart_identity":{"v":1,"host":"paradisofattoria.it","installation_id":"5d6b0584-473f-49f1-80d3-304c9707d7e1","key_fingerprint":"IaEo-UNEmPVoCd6KwSf800jkwbrk9UyTTvu9PCQ4NPQ","nonce":"4_2wng-W79bEWDB8BfqNkzo0sniNmmHJBm9C8Rb_Z4g","ts":1790634287368},"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":false,"payments":false,"mutations":false,"checkout_sessions":false,"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":[99],"free_shipping_unconditional":false,"free_shipping_requires_coupon":false,"zones":[{"id":1,"name":"Italia","locations":[{"type":"country","code":"IT"}],"methods":[{"method_id":"free_shipping","instance_id":1,"title":"Spedizione gratuita","enabled":true,"requires":"min_amount","min_amount":99,"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":0,"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":true,"url":"https:\/\/paradisofattoria.it\/modulo-richiesta-resi\/","note":"Merchant-provided return and refund policy page. Consult before presenting purchase decisions to buyers."},"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 from WooCommerce at query time. That is the perimeter of the guarantee: it is not a promise that the response matches the storefront at the instant you read it. Verify the final product before quoting price, stock or variant."},"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:\/\/paradisofattoria.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:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/products?fields=summary","product_url_template":"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/product\/{id}","product_full_url_template":"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/product\/{id}?fields=full","product_verification_url_template":"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/product\/{id}","categories_url":"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/categories","meta_url":"https:\/\/paradisofattoria.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:\/\/paradisofattoria.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:\/\/paradisofattoria.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:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/search?q=Nike&per_page=10&fields=summary"},"products_endpoint":{"url":"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/products?fields=summary","role":"browse\/list products with filters; not full-text search","does_not_accept":["q","search","query","limit"],"use_for_text_search":"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/search?q={q}&fields=summary","result_count_parameter":"per_page","copy_paste_example":"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/products?per_page=10&fields=summary"},"runtime_guidance":"Unknown query parameters return 400 and no search runs. If an agent uses search\/query instead of q, limit instead of per_page, or sends q\/search to \/catalog\/products, the response includes invalid_parameters, parameter_corrections, correct_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. Zero results means this search found nothing \u2014 not that the store does not carry the product. Report absence only as \"not found with these terms\", after bare-spine and category-browse have both returned 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. Canonical values only: male, female, unisex, kids. Input is trimmed and lowercased; no translation is performed. Soft filter: a product with a different gender is excluded, one whose gender cannot be determined is retained and marked unknown_retained.","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.","physical_only":"Boolean. true returns only products that require shipping according to WooCommerce product semantics. It does NOT mean \"physical\": a downloadable product that still ships is kept, and a pickup-only product is not identified by this flag, because WooCommerce models collection as a shipping method and not as a product property. On a variable product the value is decided by the variations. Opt-in: omitted, the catalog is returned as the merchant published it. Every summary record carries shipping_required, fulfilment, virtual and downloadable, so this filter changes what is returned, never what is disclosed. To tell shipped, downloadable, virtual (a code, an access or a service) and collected-in-store apart, read fulfilment.","on_sale":"Boolean. true returns products with an active WooCommerce sale price. For variable products this can mean only some size\/color variants; verify price.sale_scope and the selected variation. Coupon-only savings are not included.","per_page":"Results per page (1\u2013100, default 20).","page":"Page number (1\u20131000, default 1).","orderby":"Sort: date (default), price, title, popularity, id. Use id with order=asc, plus after_id, to walk the whole catalog in repeatable pages.","after_id":"Integer threshold: only products with a greater id. Meant for orderby=id&order=asc, to resume a walk without rereading or skipping.","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:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/meta","rule":"Before exploratory search, GET meta_url for populated category slugs, accepted filters, asynchronous facet snapshots and price range. Use categories_url for the complete taxonomy including empty categories."}},"checkout_session":{"enabled":false,"endpoint":"https:\/\/paradisofattoria.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":"pending | cart_loaded | error","status_note":"pending after creation; cart_loaded after the buyer successfully opens a Bridge cart or checkout URL."},"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 ISO 4217 minor units (e.g. 55300 = 553.00 EUR for EUR with exponent 2). Current catalog prices must be multiplied by 100 to convert."},"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."},"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 top-level product attributes plus available variations by default; variants[].attributes remains variation-level evidence","agent_rule":"Do not quote exact final price or promise a sale until a variation is selected. Price and sale eligibility may differ per size\/color. Use price.sale_scope and purchase_readiness.blocking_fields before handoff.","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:\/\/paradisofattoria.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:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/discovery\" \/>\n<link rel=\"service-desc\" type=\"application\/vnd.oai.openapi+json\" href=\"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/openapi\" \/>","merchant":{"name":"Fattoria Paradiso - Azienda Agricola","url":"https:\/\/paradisofattoria.it","currency":"EUR","locale":"it_IT","timezone":"Europe\/Rome"},"mcp":{"enabled":true,"transport":"http-post-jsonrpc-2.0","protocol_version":"2025-06-18","endpoint":"https:\/\/paradisofattoria.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:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/discovery","mcp":"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/mcp","search":"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/search?fields=summary","products":"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/products?fields=summary","product":"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/product\/{id}","product_full":"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/product\/{id}?fields=full","product_verification":"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/product\/{id}","categories":"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/categories","meta":"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/meta","openapi":"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/openapi","health":"https:\/\/paradisofattoria.it\/wp-json\/kalicart\/v1\/catalog\/health","checkout_session":null},"well_known":{"kalicart_bridge":"https:\/\/paradisofattoria.it\/.well-known\/kalicart-bridge.json","agent_catalog":"https:\/\/paradisofattoria.it\/.well-known\/agent-catalog.json","agent_json":"https:\/\/paradisofattoria.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-10-16T06:06:34+00:00"}