{"openapi": "3.1.0", "info": {"title": "MelaVolt Catalogue and Enquiry API", "version": "1.1.0", "description": "Assisted electronics sourcing in Addis Ababa. No checkout or payments. Preview requests are test records. Explicit customer consent is required for all writes."}, "servers": [{"url": "/"}], "paths": {"/api/v1/products/": {"get": {"operationId": "listProducts", "summary": "Search public model references and fresh offers", "parameters": [{"in": "query", "name": "q", "schema": {"type": "string", "maxLength": 120}}, {"in": "query", "name": "category", "schema": {"type": "string"}}, {"in": "query", "name": "brand", "schema": {"type": "string"}}, {"in": "query", "name": "sort", "schema": {"enum": ["featured", "name", "recent"]}}, {"in": "query", "name": "page", "schema": {"type": "integer", "minimum": 1}}, {"in": "query", "name": "limit", "schema": {"type": "integer", "minimum": 1, "maximum": 100}}], "responses": {"200": {"description": "Paginated catalogue", "content": {"application/json": {"schema": {"type": "object", "properties": {"schema_version": {"type": "string"}, "test_mode": {"type": "boolean"}, "currency": {"const": "ETB"}, "total": {"type": "integer"}, "page": {"type": "integer"}, "next": {"type": ["string", "null"]}, "items": {"type": "array", "items": {"$ref": "#/components/schemas/Product"}}}}}}}, "429": {"description": "Rate limited; observe Retry-After"}}}}, "/api/v1/products/{slug}/": {"get": {"operationId": "getProduct", "parameters": [{"in": "path", "name": "slug", "required": true, "schema": {"type": "string"}}], "responses": {"200": {"description": "Product reference", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/Product"}}}}, "404": {"description": "Unknown product"}, "429": {"description": "Rate limited; observe Retry-After"}}}}, "/api/v1/enquiries/": {"post": {"operationId": "requestQuote", "summary": "Submit an explicitly authorized customer enquiry, not an order", "security": [{"AgentKey": []}], "parameters": [{"in": "header", "name": "Idempotency-Key", "required": true, "schema": {"type": "string", "format": "uuid"}}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/EnquiryRequest"}}}}, "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/EnquiryReceipt"}}}}, "200": {"description": "Identical retry", "content": {"application/json": {"schema": {"$ref": "#/components/schemas/EnquiryReceipt"}}}}, "400": {"description": "Invalid input"}, "401": {"description": "Agent key required or invalid"}, "409": {"description": "Idempotency key reused with different content"}, "415": {"description": "JSON required"}, "429": {"description": "Rate limited; observe Retry-After"}}}}, "/api/v1/search/": {"get": {"operationId": "suggestProducts", "summary": "Model search suggestions with actual product thumbnails", "parameters": [{"name": "q", "in": "query", "required": true, "schema": {"type": "string", "minLength": 2, "maxLength": 100}}], "responses": {"200": {"description": "Up to seven model matches"}, "429": {"description": "Rate limited; observe Retry-After"}}}}}, "components": {"securitySchemes": {"AgentKey": {"type": "http", "scheme": "bearer", "description": "Owner-issued and revocable; enquiry-only scope."}}, "schemas": {"Product": {"type": "object", "required": ["id", "name", "brand", "category", "availability", "price", "currency", "checkout_available", "offers"], "properties": {"id": {"type": "string"}, "name": {"type": "string"}, "brand": {"type": "string"}, "category": {"type": "string"}, "description": {"type": "string"}, "specifications": {"type": "object", "additionalProperties": {"type": "string"}}, "url": {"type": "string", "format": "uri"}, "image_url": {"type": ["string", "null"]}, "release_state": {"enum": ["released", "announced"]}, "availability": {"enum": ["supplier_confirmed", "unconfirmed"]}, "currency": {"const": "ETB"}, "price": {"type": ["string", "null"], "description": "Decimal ETB string. null is unconfirmed, never zero."}, "checkout_available": {"const": false}, "source_url": {"type": ["string", "null"]}, "source_status": {"enum": ["reference", "verified"]}, "source_checked_at": {"type": ["string", "null"], "format": "date-time"}, "updated_at": {"type": "string", "format": "date-time"}, "offers": {"type": "array", "items": {"type": "object", "properties": {"id": {"type": "integer"}, "sku": {"type": "string"}, "variant": {"type": "string"}, "condition": {"enum": ["new", "used", "refurbished"]}, "price": {"type": "string"}, "currency": {"const": "ETB"}, "checked_at": {"type": "string", "format": "date-time"}, "expires_at": {"type": "string", "format": "date-time"}, "warranty": {"type": "string"}, "returns": {"type": "string"}, "url": {"type": "string", "format": "uri"}}}}, "images": {"type": "array", "items": {"type": "object", "properties": {"url": {"type": "string", "format": "uri"}, "thumbnail_url": {"type": "string", "format": "uri"}, "alt": {"type": "string"}, "view": {"type": "string"}, "source": {"type": "string"}, "source_url": {"type": "string", "format": "uri"}, "checked_at": {"type": "string", "format": "date-time"}}}}, "configuration_preferences": {"type": "object", "description": "Manufacturer-reference options only; not a confirmed locally supplied SKU."}}}, "EnquiryRequest": {"type": "object", "additionalProperties": false, "required": ["name", "phone", "consent"], "properties": {"name": {"type": "string", "minLength": 1, "maxLength": 100}, "phone": {"type": "string", "description": "Ethiopian mobile number in 09, 07 or +251 format"}, "email": {"type": "string", "format": "email"}, "area": {"type": "string", "maxLength": 100}, "requirements": {"type": "string", "maxLength": 2000}, "consent": {"const": true}, "items": {"type": "array", "maxItems": 12, "items": {"type": "object", "required": ["slug"], "additionalProperties": false, "properties": {"slug": {"type": "string"}, "quantity": {"type": "integer", "minimum": 1, "maximum": 100, "default": 1}, "configuration": {"type": "string", "maxLength": 500}}}}}, "description": "At least one item or nonempty requirements is required. Explicit customer authorization only. Does not create a purchase."}, "EnquiryReceipt": {"type": "object", "properties": {"id": {"type": "string", "format": "uuid"}, "reference": {"type": "string"}, "status": {"type": "string"}, "test_mode": {"type": "boolean"}, "purchase_created": {"const": false}}}}}}