{
  "openapi": "3.1.0",
  "info": {
    "title": "HVN Shopee Commerce Simulator API",
    "version": "1.0.0",
    "description": "Synthetic Shopee-shaped API for the HVN AI-native eCommerce working demo. This is not an official Shopee API and must never be presented as production connectivity. Write operations require an idempotency key."
  },
  "servers": [{ "url": "https://shopee.hoiai.net" }],
  "tags": [
    { "name": "Order" },
    { "name": "Product" },
    { "name": "Campaign" },
    { "name": "Payment" },
    { "name": "Webhook" },
    { "name": "Event" }
  ],
  "components": {
    "securitySchemes": {
      "PartnerId": { "type": "apiKey", "in": "header", "name": "X-Partner-Id" },
      "ShopId": { "type": "apiKey", "in": "header", "name": "X-Shop-Id" },
      "Timestamp": { "type": "apiKey", "in": "header", "name": "X-Timestamp" },
      "Signature": { "type": "apiKey", "in": "header", "name": "X-Signature", "description": "HMAC-SHA256(secret, METHOD\\nPATHNAME\\nTIMESTAMP\\nSHA256(rawBody))" }
    },
    "schemas": {
      "Envelope": {
        "type": "object",
        "required": ["request_id", "error", "message", "response"],
        "properties": {
          "request_id": { "type": "string" },
          "error": { "type": "string" },
          "message": { "type": "string" },
          "response": {}
        }
      }
    }
  },
  "security": [{ "PartnerId": [], "ShopId": [], "Timestamp": [], "Signature": [] }],
  "paths": {
    "/health": {
      "get": { "security": [], "summary": "Service health", "responses": { "200": { "description": "Healthy" } } }
    },
    "/api/v2/order/get_order_list": {
      "get": { "tags": ["Order"], "summary": "List orders", "parameters": [{ "in": "query", "name": "order_status", "schema": { "type": "string" } }], "responses": { "200": { "description": "Order list" } } }
    },
    "/api/v2/order/get_order_detail": {
      "get": { "tags": ["Order"], "summary": "Get one order", "parameters": [{ "in": "query", "name": "order_sn", "required": true, "schema": { "type": "string" } }], "responses": { "200": { "description": "Order detail" }, "404": { "description": "Order not found" } } }
    },
    "/api/v2/product/get_item_list": {
      "get": { "tags": ["Product"], "summary": "List products", "responses": { "200": { "description": "Item list" } } }
    },
    "/api/v2/product/update_stock": {
      "post": {
        "tags": ["Product"], "summary": "Update and verify stock", "parameters": [{ "in": "header", "name": "X-Idempotency-Key", "required": true, "schema": { "type": "string" } }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["item_id", "stock"], "properties": { "item_id": { "type": "integer" }, "stock": { "type": "integer", "minimum": 0 } } } } } },
        "responses": { "200": { "description": "Stock updated" }, "400": { "description": "Invalid request" } }
      }
    },
    "/api/v2/product/update_item": {
      "post": {
        "tags": ["Product"], "summary": "Update product title/description", "parameters": [{ "in": "header", "name": "X-Idempotency-Key", "required": true, "schema": { "type": "string" } }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["item_id"], "properties": { "item_id": { "type": "integer" }, "name": { "type": "string" }, "description": { "type": "string" } } } } } },
        "responses": { "200": { "description": "Item updated" } }
      }
    },
    "/api/v2/discount/get_discount_list": {
      "get": { "tags": ["Campaign"], "summary": "List campaigns and vouchers", "responses": { "200": { "description": "Campaign list" } } }
    },
    "/api/v2/discount/update_discount": {
      "post": {
        "tags": ["Campaign"], "summary": "Update campaign state or budget", "parameters": [{ "in": "header", "name": "X-Idempotency-Key", "required": true, "schema": { "type": "string" } }],
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["discount_id"], "properties": { "discount_id": { "type": "integer" }, "status": { "enum": ["ACTIVE", "PAUSED", "SCHEDULED", "ENDED"] }, "budget": { "type": "number" } } } } } },
        "responses": { "200": { "description": "Campaign updated" } }
      }
    },
    "/api/v2/payment/get_escrow_list": {
      "get": { "tags": ["Payment"], "summary": "List synthetic settlements", "responses": { "200": { "description": "Settlement list" } } }
    },
    "/api/v2/reconciliation/run": {
      "post": { "tags": ["Payment"], "summary": "Run deterministic reconciliation summary", "responses": { "200": { "description": "Reconciliation result" } } }
    },
    "/api/v2/event/get_event_list": {
      "get": { "tags": ["Event"], "summary": "List domain events", "responses": { "200": { "description": "Event list" } } }
    },
    "/api/v2/webhook/get_subscription_list": {
      "get": { "tags": ["Webhook"], "summary": "List webhook subscriptions", "responses": { "200": { "description": "Subscriptions" } } }
    },
    "/api/v2/webhook/set_subscription": {
      "post": {
        "tags": ["Webhook"], "summary": "Create or update a webhook subscription",
        "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "format": "uri" }, "events": { "type": "array", "items": { "type": "string" } }, "active": { "type": "boolean" } } } } } },
        "responses": { "200": { "description": "Subscription saved" } }
      }
    }
  }
}