{"openapi":"3.1.0","info":{"title":"Papa Tartufi Simulated Commerce Sandbox API","version":"1.0.0","description":"Cache-backed simulated cart and checkout operations for agent testing.\n\nSandbox writes never create production carts, customers, orders, payments,\ninventory reservations, or a real checkout URL.\n\nGenerated keys are temporary and use the declared sandbox bearer scopes."},"servers":[{"url":"https://api.papatartufi.com","description":"Papa Tartufi simulated commerce sandbox."}],"tags":[{"name":"sandbox","description":"Simulated commerce operations"}],"paths":{"/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"}}}}}}