{"openapi":"3.1.0","info":{"title":"Papa Tartufi Public Product API","version":"1.0.0","description":"Read-only product discovery for Papa Tartufi.\n\nUse this API to search published products, resolve variant option\ncombinations, and read live region-aware prices and availability.\n\nMarket behavior: locale defaults to en; country defaults to IT and\ncurrency defaults to EUR. The response echoes the resolved market\ncontext including region_id.\n\nVariant pricing: each variant carries its own calculated_price for the\nresolved Medusa region. Product price_range is a summary only.\n\nAvailability is purchasability, not exact stock:\nmanage_inventory=false or inventory_quantity>0 means in_stock and\npurchasable; otherwise allow_backorder=true means backorder and\npurchasable; otherwise out_of_stock and not purchasable.\n\nVersioning: breaking changes ship under a new /v2 path. Non-breaking\nadditions are backward compatible. Deprecated fields are marked\ndeprecated and announced in /developers before removal.\n\nAuthentication: v1 reads are public and keyless. No account, API key,\nor session is required.\n\nRate limiting is enforced at the edge (Cloudflare) at 120 requests per IP per minute. Responses include\nRateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset. A 429\nincludes Retry-After.","x-agent-onboarding":{"access":"free","authentication":"none","signup_required":false,"api_key_required":false,"sandbox":{"available":true,"url":"https://api.papatartufi.com/sandbox/v1","protocol":"REST","note":"The sandbox simulates cart and checkout writes without creating production carts, orders, customers, inventory reservations, or payments.","mcp_url":"https://api.papatartufi.com/mcp/sandbox","public_key_scopes":["catalog:read"],"generated_key_scopes":["catalog:read","cart:write","checkout:create"]},"next_step":"Use the live read-only catalog or connect to the MCP server."},"contact":{"name":"Papa Tartufi","url":"https://papatartufi.com/en/contact"}},"servers":[{"url":"https://api.papatartufi.com","description":"Live read-only catalog. No credentials required."}],"tags":[{"name":"products","description":"Public product discovery"}],"paths":{"/public/v1/products":{"get":{"operationId":"listPublicProducts","summary":"Search published products with live pricing","description":"Searches published products by title or handle. Each variant includes option values, calculated regional price, and purchasability.","tags":["products"],"security":[],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":120},"description":"Free-text search across title and handle."},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","it"],"default":"en"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"IT"},"description":"ISO-2 country. Defaults to IT."},{"name":"currency","in":"query","required":false,"schema":{"type":"string","minLength":3,"maxLength":3,"default":"EUR"},"description":"ISO-3 currency. Defaults to EUR."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":20,"default":10}},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"maximum":1000,"default":0}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string","maxLength":512},"description":"Opaque cursor returned as next_cursor. Preferred for subsequent pages; cannot be combined with offset."}],"responses":{"200":{"description":"Product list","headers":{"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}},"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicProductList"},"examples":{"truffle":{"value":{"products":[{"id":"prod_123","handle":"black-truffle-sauce","title":"Black Truffle Sauce","description":"Stone-ground black truffle sauce.","thumbnail":"https://example.com/media/sauce.jpg","url":"https://papatartufi.com/en/products/black-truffle-sauce","variants":[{"id":"variant_123","sku":"SAUCE-90","display_name":"90 g","options":[{"name":"Weight","value":"90 g"}],"price":{"amount":16,"currency":"EUR"},"availability":{"status":"in_stock","purchasable":true}}],"price_range":{"minimum":9.5,"maximum":16,"currency":"EUR"}}],"count":1,"limit":10,"offset":0,"context":{"locale":"en","country":"IT","currency":"EUR","region_id":"reg_123"},"request_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6"}}}}}},"400":{"description":"Invalid market or query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiError"}}}},"429":{"description":"Rate limited","headers":{"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}},"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiError"}}}},"500":{"description":"Temporary failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiError"}}}}}}},"/public/v1/products/{handle}":{"get":{"operationId":"getPublicProduct","summary":"Get one published product with live pricing","description":"Retrieves a published product by handle with all variants, option combinations, calculated prices, and availability.","tags":["products"],"security":[],"parameters":[{"name":"handle","in":"path","required":true,"schema":{"type":"string"}},{"name":"locale","in":"query","required":false,"schema":{"type":"string","enum":["en","it"],"default":"en"}},{"name":"country","in":"query","required":false,"schema":{"type":"string","minLength":2,"maxLength":2,"default":"IT"}},{"name":"currency","in":"query","required":false,"schema":{"type":"string","minLength":3,"maxLength":3,"default":"EUR"}}],"responses":{"200":{"description":"Product detail","headers":{"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicProductDetail"}}}},"400":{"description":"Invalid market or handle","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiError"}}}},"404":{"description":"Unknown or unpublished product","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiError"}}}},"429":{"description":"Rate limited","headers":{"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}},"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicApiError"}}}}}}},"/sandbox/v1/keys":{"post":{"operationId":"createSandboxKey","summary":"Create a temporary sandbox key","description":"Creates a short-lived key for simulated cart and checkout testing. No real commerce side effects occur.","security":[],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxKeyRequest"}}}},"responses":{"201":{"description":"Sandbox key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxKeyResponse"}}}},"400":{"description":"Invalid or unsupported scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"429":{"description":"Rate limited","headers":{"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}},"Retry-After":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"503":{"description":"Sandbox disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}}}}},"/sandbox/v1":{"get":{"operationId":"getSandboxStatus","summary":"Discover the free simulated commerce sandbox","description":"Returns the live sandbox status, public key-issuance instructions, supported scopes, and machine-readable integration links. No authentication is required.","security":[],"responses":{"200":{"description":"Sandbox discovery document","content":{"application/json":{"schema":{"type":"object","required":["environment","status","simulated","free","key_issuance","available_scopes","openapi_url","mcp_url"],"properties":{"environment":{"const":"sandbox"},"status":{"const":"available"},"simulated":{"const":true},"free":{"const":true},"key_issuance":{"type":"object"},"available_scopes":{"type":"array","items":{"type":"string"}},"openapi_url":{"type":"string","format":"uri"},"mcp_url":{"type":"string","format":"uri"}}}}}},"503":{"description":"Sandbox disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}}}}},"/sandbox/v1/carts":{"post":{"operationId":"createSandboxCart","summary":"Create a simulated cart","security":[{"sandboxBearer":[]}],"parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Stable key used to safely retry this write operation."}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxCartRequest"}}}},"responses":{"201":{"description":"Simulated cart","headers":{"Idempotency-Key":{"schema":{"type":"string"}},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxCart"}}}},"400":{"description":"Invalid cart input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"401":{"description":"Missing or insufficient sandbox key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"503":{"description":"Sandbox disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}}}}},"/sandbox/v1/carts/{id}":{"get":{"operationId":"getSandboxCart","summary":"Retrieve a simulated cart","security":[{"sandboxBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Simulated cart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxCart"}}}},"401":{"description":"Missing or insufficient sandbox key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"404":{"description":"Cart not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}}}},"post":{"operationId":"advanceSandboxCart","summary":"Advance a simulated cart action (compatibility endpoint)","description":"Compatibility endpoint. Prefer the explicit shipping-address, shipping-option, and checkout routes for new integrations. Responses include Deprecation: true.","security":[{"sandboxBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxActionRequest"}}}},"responses":{"200":{"description":"Updated simulated cart or simulated checkout result","headers":{"Idempotency-Key":{"schema":{"type":"string"}},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}},"Deprecation":{"schema":{"type":"string"}},"Sunset":{"schema":{"type":"string"}},"Link":{"schema":{"type":"string"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxCart"}}}},"400":{"description":"Invalid action","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"401":{"description":"Missing or insufficient sandbox key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"403":{"description":"Required sandbox scope is missing","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"404":{"description":"Cart not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}}}}},"/sandbox/v1/carts/{id}/shipping-address":{"post":{"operationId":"setSandboxShippingAddress","summary":"Set a simulated shipping address","security":[{"sandboxBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxAddress"}}}},"responses":{"200":{"description":"Updated simulated cart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxCart"}}}},"400":{"description":"Invalid address","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"401":{"description":"Missing or insufficient sandbox key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"404":{"description":"Cart not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}}}}},"/sandbox/v1/carts/{id}/shipping-options":{"get":{"operationId":"listSandboxShippingOptions","summary":"List simulated shipping options","security":[{"sandboxBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Simulated shipping options","content":{"application/json":{"schema":{"type":"object","required":["environment","simulated","options"],"properties":{"environment":{"const":"sandbox"},"simulated":{"const":true},"options":{"type":"array","items":{"$ref":"#/components/schemas/SandboxShippingOption"}}}}}}},"401":{"description":"Missing or insufficient sandbox key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"404":{"description":"Cart not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}}}}},"/sandbox/v1/carts/{id}/shipping-option":{"post":{"operationId":"selectSandboxShippingOption","summary":"Select a simulated shipping option","security":[{"sandboxBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxShippingOptionRequest"}}}},"responses":{"200":{"description":"Updated simulated cart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxCart"}}}},"400":{"description":"Invalid shipping option","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"401":{"description":"Missing or insufficient sandbox key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"404":{"description":"Cart not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}}}}},"/sandbox/v1/carts/{id}/checkout":{"post":{"operationId":"createSandboxCheckoutLink","summary":"Prepare a simulated checkout result","description":"Returns checkout readiness with checkout_url=null. It never creates a production cart, payment, customer, inventory reservation, or order.","security":[{"sandboxBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":255},"description":"Stable key used to safely retry this write operation."}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxEmptyRequest"}}}},"responses":{"200":{"description":"Simulated checkout result","headers":{"Idempotency-Key":{"schema":{"type":"string"}},"RateLimit-Limit":{"schema":{"type":"integer"}},"RateLimit-Remaining":{"schema":{"type":"integer"}},"RateLimit-Reset":{"schema":{"type":"integer"}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxCart"}}}},"401":{"description":"Missing or insufficient sandbox key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"403":{"description":"checkout:create scope is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"404":{"description":"Cart not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}}}}},"/sandbox/v1/carts/{id}/items":{"post":{"operationId":"addSandboxCartItem","summary":"Add a published variant to a simulated cart","security":[{"sandboxBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxItemRequest"}}}},"responses":{"201":{"description":"Updated simulated cart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxCart"}}}},"400":{"description":"Invalid item","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"401":{"description":"Missing or insufficient sandbox key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"404":{"description":"Cart not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"422":{"description":"Variant is not purchasable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}}}},"delete":{"operationId":"removeSandboxCartItem","summary":"Remove a variant from a simulated cart","security":[{"sandboxBearer":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}},{"name":"variant_id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Updated simulated cart","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxCart"}}}},"400":{"description":"Variant ID is required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"401":{"description":"Missing or insufficient sandbox key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}},"404":{"description":"Cart not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SandboxError"}}}}}}}},"components":{"securitySchemes":{"sandboxBearer":{"type":"http","scheme":"bearer","description":"Short-lived sandbox key created by POST /sandbox/v1/keys."}},"schemas":{"SandboxError":{"type":"object","required":["error"],"properties":{"error":{"type":"string","example":"sandbox_unauthorized"},"message":{"type":"string"},"scope":{"type":"string"},"retry_after":{"type":"integer"}}},"SandboxKeyRequest":{"type":"object","additionalProperties":false,"properties":{"scopes":{"type":"array","maxItems":3,"uniqueItems":true,"items":{"type":"string","enum":["catalog:read","cart:write","checkout:create"]}}}},"SandboxKeyResponse":{"type":"object","required":["environment","token_type","access_token","expires_at","scopes","available_scopes"],"properties":{"environment":{"type":"string","enum":["sandbox"]},"token_type":{"type":"string","enum":["Bearer"]},"access_token":{"type":"string","pattern":"^pt_test_"},"expires_at":{"type":"string","format":"date-time"},"scopes":{"type":"array","items":{"type":"string"}},"available_scopes":{"type":"array","items":{"type":"string"}}}},"SandboxCartRequest":{"type":"object","additionalProperties":false,"properties":{"currency":{"type":"string","pattern":"^[A-Z]{3}$","default":"EUR"}}},"SandboxItemRequest":{"type":"object","additionalProperties":false,"required":["variant_id","quantity"],"properties":{"variant_id":{"type":"string","minLength":1,"maxLength":128},"quantity":{"type":"integer","minimum":1,"maximum":99}}},"SandboxAddress":{"type":"object","additionalProperties":false,"required":["name","line_one","city","country","postal_code"],"properties":{"name":{"type":"string","minLength":1,"maxLength":256},"line_one":{"type":"string","minLength":1,"maxLength":120},"line_two":{"type":"string","maxLength":120},"city":{"type":"string","minLength":1,"maxLength":80},"state":{"type":"string","maxLength":80},"country":{"type":"string","pattern":"^[A-Za-z]{2}$"},"postal_code":{"type":"string","minLength":1,"maxLength":20},"phone_number":{"type":"string","maxLength":40}}},"SandboxShippingOptionRequest":{"type":"object","additionalProperties":false,"required":["shipping_option_id"],"properties":{"shipping_option_id":{"const":"sandbox_standard"}}},"SandboxEmptyRequest":{"type":"object","additionalProperties":false},"SandboxActionRequest":{"oneOf":[{"type":"object","additionalProperties":false,"required":["action","variant_id","quantity"],"properties":{"action":{"const":"add_item"},"variant_id":{"type":"string","minLength":1,"maxLength":128},"quantity":{"type":"integer","minimum":1,"maximum":99}}},{"type":"object","additionalProperties":false,"required":["action","address"],"properties":{"action":{"const":"set_shipping_address"},"address":{"$ref":"#/components/schemas/SandboxAddress"}}},{"type":"object","additionalProperties":false,"required":["action","shipping_option_id"],"properties":{"action":{"const":"select_shipping_option"},"shipping_option_id":{"const":"sandbox_standard"}}},{"type":"object","additionalProperties":false,"required":["action"],"properties":{"action":{"const":"checkout_link"}}}]},"SandboxCartItem":{"type":"object","required":["variant_id","quantity","unit_price"],"properties":{"variant_id":{"type":"string"},"quantity":{"type":"integer","minimum":1,"maximum":99},"unit_price":{"type":"number","minimum":0}}},"SandboxShippingOption":{"type":"object","required":["id","name","amount"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"amount":{"type":"number"},"currency":{"type":"string"}}},"SandboxCart":{"type":"object","required":["id","environment","simulated","currency","items","totals"],"properties":{"id":{"type":"string","pattern":"^sandbox_cart_[0-9a-f]{24}$"},"environment":{"type":"string","enum":["sandbox"]},"simulated":{"type":"boolean","const":true},"currency":{"type":"string","pattern":"^[A-Z]{3}$"},"items":{"type":"array","items":{"$ref":"#/components/schemas/SandboxCartItem"}},"shipping_address":{"$ref":"#/components/schemas/SandboxAddress"},"shipping_option":{"$ref":"#/components/schemas/SandboxShippingOption"},"totals":{"type":"object","required":["item_total","shipping_total","grand_total"],"properties":{"item_total":{"type":"number","minimum":0},"shipping_total":{"type":"number","minimum":0},"grand_total":{"type":"number","minimum":0}}},"status":{"type":"string","enum":["ready_for_checkout"]},"checkout_url":{"type":"null"}}},"PublicVariantOption":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string","example":"Weight"},"value":{"type":"string","example":"90 g"}}},"PublicPrice":{"type":"object","required":["amount","currency"],"properties":{"amount":{"type":"number","description":"Major-unit amount as stored by Medusa, for example 16 means EUR 16.","example":16},"currency":{"type":"string","example":"EUR"}}},"PublicAvailability":{"type":"object","required":["status","purchasable"],"properties":{"status":{"type":"string","enum":["in_stock","backorder","out_of_stock"]},"purchasable":{"type":"boolean"}}},"PublicVariant":{"type":"object","required":["id","options","availability"],"properties":{"id":{"type":"string","example":"variant_123"},"sku":{"type":["string","null"],"example":"SAUCE-90"},"display_name":{"type":["string","null"],"description":"Option values joined in Medusa option order, for example 90 g.","example":"90 g"},"options":{"type":"array","items":{"$ref":"#/components/schemas/PublicVariantOption"}},"price":{"anyOf":[{"$ref":"#/components/schemas/PublicPrice"},{"type":"null"}],"description":"Calculated regional variant price. Null when no price exists for the market."},"availability":{"$ref":"#/components/schemas/PublicAvailability"}}},"PublicPriceRange":{"type":"object","required":["minimum","maximum","currency"],"properties":{"minimum":{"type":"number","example":9.5},"maximum":{"type":"number","example":16},"currency":{"type":"string","example":"EUR"}}},"PublicProduct":{"type":"object","required":["id","handle","title","url","variants"],"properties":{"id":{"type":"string","example":"prod_123"},"handle":{"type":"string","example":"black-truffle-sauce"},"title":{"type":"string","example":"Black Truffle Sauce"},"description":{"type":["string","null"]},"thumbnail":{"type":["string","null"]},"url":{"type":"string","format":"uri","example":"https://papatartufi.com/en/products/black-truffle-sauce"},"variants":{"type":"array","items":{"$ref":"#/components/schemas/PublicVariant"}},"price_range":{"anyOf":[{"$ref":"#/components/schemas/PublicPriceRange"},{"type":"null"}]}}},"PublicMarketContext":{"type":"object","required":["locale","country","currency","region_id"],"properties":{"locale":{"type":"string","enum":["en","it"]},"country":{"type":"string","example":"IT"},"currency":{"type":"string","example":"EUR"},"region_id":{"type":"string","example":"reg_123"}}},"PublicProductList":{"type":"object","required":["products","count","limit","offset","has_more","next_cursor","context","request_id"],"properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/PublicProduct"}},"count":{"type":"integer","example":1},"limit":{"type":"integer","example":10},"offset":{"type":"integer","example":0},"has_more":{"type":"boolean","example":false},"next_cursor":{"type":["string","null"],"example":null},"context":{"$ref":"#/components/schemas/PublicMarketContext"},"request_id":{"type":"string","format":"uuid"}}},"PublicProductDetail":{"type":"object","required":["product","context","request_id"],"properties":{"product":{"$ref":"#/components/schemas/PublicProduct"},"context":{"$ref":"#/components/schemas/PublicMarketContext"},"request_id":{"type":"string","format":"uuid"}}},"PublicApiError":{"type":"object","required":["error","request_id"],"properties":{"error":{"type":"object","required":["code","message","hint"],"properties":{"code":{"type":"string","enum":["REGION_NOT_FOUND","PRODUCT_NOT_FOUND","INVALID_HANDLE","RATE_LIMITED","INTERNAL_ERROR"]},"message":{"type":"string"},"hint":{"type":"string"}}},"request_id":{"type":"string","format":"uuid"}}}}}}