{"openapi":"3.1.0","info":{"title":"Valio Aimo Trusted Trade Agents","version":"1.0.0","description":"Challenge sandbox: Valio catalog and live price/stock when configured, synthetic offline fallback otherwise. EUR excluding VAT. Live quantities are whole sales units with technical Valio codes (packSize=1); synthetic packs use kg/l. Fixed local snapshots, not supplier reservations. Orders are always mock; no order API exists. JWT mandate required on every operation. Exceptions require human approval. Browser buyer APIs are not agent tools."},"servers":[{"url":"/api/agent/v1"}],"security":[{"mandate":[]}],"paths":{"/search_products":{"post":{"operationId":"search_products","summary":"Search the local catalog restricted to mandate categories (at most 100 results; narrow your query). Live prices are null until request_offer. Live quantities are whole sales units using Valio technical unit codes; synthetic packs use kg/l. Missing dietary flags mean unknown, not allergen-free.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"query":{"type":"string","maxLength":200},"category":{"type":"string","minLength":1,"maxLength":200},"lactoseFree":{"type":"boolean"},"organic":{"type":"boolean"},"origin":{"type":"string","minLength":1,"maxLength":200},"packSize":{"type":"number","exclusiveMinimum":0},"certificates":{"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"rationale":{"type":"string","minLength":1,"maxLength":2000}},"required":["rationale"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful structured result","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or expired signed mandate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not owned by agent or not in scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Expired offer, conflicting retry or already decided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/get_product":{"post":{"operationId":"get_product","summary":"Get canonical product declarations within your mandate categories. Live prices and stock are unknown until a dated offer.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"productId":{"type":"string","minLength":1,"maxLength":200},"rationale":{"type":"string","minLength":1,"maxLength":2000}},"required":["productId","rationale"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful structured result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or expired signed mandate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not owned by agent or not in scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Expired offer, conflicting retry or already decided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/request_offer":{"post":{"operationId":"request_offer","summary":"Request a fixed local price snapshot for an ISO delivery date, not a supplier quote or reservation. Live packs means whole sales units (packSize=1), respecting allowedLotSize; synthetic packs use kg/l. Includes tax, cutoff, historical fill rate and CO2 group averages where known. Alternatives are unpriced suggestions, never silently selected. Out-of-mandate offers require human approval.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"lines":{"minItems":1,"maxItems":50,"type":"array","items":{"type":"object","properties":{"productId":{"type":"string","minLength":1,"maxLength":200},"packs":{"type":"integer","exclusiveMinimum":0,"maximum":100000},"substitutesFor":{"description":"Only when this line replaces a different, unavailable product: that product id. Omit for the product you were asked to buy.","type":"string","minLength":1,"maxLength":200}},"required":["productId","packs"],"additionalProperties":false}},"deliveryDate":{"type":"string","pattern":"^\\d{4}-\\d{2}-\\d{2}$"},"deliveryLocation":{"type":"string","minLength":1,"maxLength":200},"rationale":{"type":"string","minLength":1,"maxLength":2000}},"required":["lines","deliveryDate","deliveryLocation","rationale"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful structured result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Offer"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or expired signed mandate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not owned by agent or not in scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Expired offer, conflicting retry or already decided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/place_order":{"post":{"operationId":"place_order","summary":"Submit an offer for a mock order only (there is no Valio order API) with a stable idempotency key. Returns placed, pending_approval (a human decides) or refused (stock or cut-off block: request a fresh offer or an alternative; nobody can approve it). Never bypass human approval. Reuse the same key on retry.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"offerId":{"type":"string","minLength":1,"maxLength":200},"idempotencyKey":{"type":"string","minLength":1,"maxLength":200},"rationale":{"type":"string","minLength":1,"maxLength":2000}},"required":["offerId","idempotencyKey","rationale"],"additionalProperties":false}}}},"responses":{"200":{"description":"Order status is placed, pending_approval or refused (stock or cut-off block; request a fresh offer). Keep id for polling. Reusing a key returns the same order; conflicting contents return 409.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or expired signed mandate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not owned by agent or not in scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Expired offer, conflicting retry or already decided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/get_order_status":{"post":{"operationId":"get_order_status","summary":"Poll an order or pending approval owned by your agent.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"orderId":{"type":"string","minLength":1,"maxLength":200},"rationale":{"type":"string","minLength":1,"maxLength":2000}},"required":["orderId","rationale"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful structured result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Order"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or expired signed mandate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not owned by agent or not in scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Expired offer, conflicting retry or already decided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/list_my_mandate":{"post":{"operationId":"list_my_mandate","summary":"Inspect your verified signed mandate and validity.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$schema":"https://json-schema.org/draft/2020-12/schema","type":"object","properties":{"rationale":{"type":"string","minLength":1,"maxLength":2000}},"required":["rationale"],"additionalProperties":false}}}},"responses":{"200":{"description":"Successful structured result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Mandate"}}}},"400":{"description":"Invalid input","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Missing, invalid or expired signed mandate","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Resource not owned by agent or not in scope","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Expired offer, conflicting retry or already decided","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"securitySchemes":{"mandate":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"Buyer-issued ES256 mandate. Discovery: /.well-known/jwks.json. iss=urn:trusted-trade:demo-buyer; aud=urn:valio-aimo:agent-gateway:v1. Demo keys rotate on process restart."}},"schemas":{"Product":{"type":"object","required":["id","name","category","packSize","unit","pricePerUnit","listPricePerUnit","certificates"],"properties":{"id":{"type":"string"},"name":{"type":"string"},"category":{"type":"string"},"packSize":{"type":"number"},"unit":{"type":"string","description":"Technical sales-unit code for Valio; kg/l for synthetic packs"},"pricePerUnit":{"type":["number","null"],"description":"EUR excluding VAT; unknown until a dated live offer"},"listPricePerUnit":{"type":["number","null"]},"deliveryReliability":{"type":"number","minimum":0,"maximum":1,"description":"Historical fill rate, not a guarantee"},"co2KgPerKg":{"type":"number","description":"kg CO2-eq/kg product-group average, not a measurement"},"allowedLotSize":{"type":"number"},"gtin":{"type":"string"},"certificates":{"type":"array","items":{"type":"string"}},"lactoseFree":{"type":"boolean"},"organic":{"type":"boolean"},"origin":{"type":"string"}}},"Offer":{"type":"object","required":["id","validUntil","lines","total","currency","rules","deliveryDate","deliveryLocation","alternatives"],"properties":{"id":{"type":"string"},"validUntil":{"type":"string","format":"date-time"},"total":{"type":"number"},"currency":{"const":"EUR"},"deliveryDate":{"type":"string","format":"date"},"deliveryLocation":{"type":"string"},"rules":{"type":"array","items":{"type":"string"}},"alternatives":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"lines":{"type":"array","items":{"type":"object","properties":{"product":{"$ref":"#/components/schemas/Product"},"packs":{"type":"integer"},"unitPrice":{"type":"number"},"lineTotal":{"type":"number"},"priceWithTax":{"type":"number"},"tax":{"type":"object","properties":{"taxRate":{"type":"number"},"taxValue":{"type":"number"}}},"availability":{"type":"object","properties":{"date":{"type":"string","format":"date"},"availablePacks":{"type":"number"},"deliverable":{"type":"boolean"},"closingTime":{"type":"string","format":"date-time","description":"Order cut-off, enforced even for human approvals"},"unavailableReason":{"type":"string"}}}}}}}},"Order":{"type":"object","required":["id","status","offer","rationale","rules"],"properties":{"id":{"type":"string"},"status":{"enum":["pending_approval","placed","rejected","refused"]},"refusal":{"type":"string"},"offer":{"$ref":"#/components/schemas/Offer"},"rationale":{"type":"string"},"rules":{"type":"array","items":{"type":"string"}},"supplierOrderId":{"type":"string"},"fulfillment":{"type":["object","null"],"description":"Supplier pending mock-order status when polled"}}},"Mandate":{"type":"object","required":["id","agent","organisation","expiresAt","allowedCategories","maxOrderValue","maxUnitPriceDeviation","allowedSubstitutions","deliveryLocations"],"properties":{"id":{"type":"string"},"agent":{"type":"string"},"organisation":{"type":"string"},"expiresAt":{"type":"number","description":"Unix seconds"},"allowedCategories":{"type":"array","items":{"type":"string"}},"maxOrderValue":{"type":"number"},"minDeliveryReliability":{"type":"number","minimum":0,"maximum":1,"description":"Optional historical fill-rate floor; lower or unknown values require human approval"},"maxUnitPriceDeviation":{"type":"number","description":"Fraction above list price: 0.05 means 5%"},"allowedSubstitutions":{"type":"boolean"},"deliveryLocations":{"type":"array","items":{"type":"string"}}}},"Error":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}}}}