{
  "openapi": "3.1.0",
  "info": {
    "title": "Agent2Merchant API",
    "version": "1.3.0",
    "summary": "AI search visibility diagnostics, three-tier package ordering, feedback, accounts, and site messages.",
    "description": "Agent2Merchant helps website owners and AI agents diagnose whether a public website can be read, understood, cited, and recommended by Doubao, Kimi, DeepSeek, ChatGPT Search, and other agentic search tools. The public paid products are a 9.9 CNY entry scan, a 59.9 CNY standard fix pack, and a 99.9 CNY same-day advanced AI search visibility fix pack. Payment claims are not revenue and do not start delivery. Delivery starts only after the owner manually verifies a real WeChat or Alipay QR receipt."
  },
  "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema",
  "servers": [
    {
      "url": "https://www.agent2merchant.com"
    }
  ],
  "tags": [
    {
      "name": "Diagnostics",
      "description": "Public AI search visibility checks and generated public audit reports."
    },
    {
      "name": "Orders",
      "description": "Agent commerce order creation and manual QR payment-claim workflow."
    },
    {
      "name": "Feedback",
      "description": "User need collection. Feedback is stored in the backend and creates durable internal site messages. Email notification has been removed."
    },
    {
      "name": "Accounts",
      "description": "User registration, login, profile, and site-message inbox."
    },
    {
      "name": "Tracking",
      "description": "Conversion and DAU event collection. Events are not revenue."
    }
  ],
  "paths": {
    "/api/ai-search-audit": {
      "post": {
        "tags": ["Diagnostics"],
        "operationId": "createAiSearchAudit",
        "summary": "Run a public AI search visibility audit for a URL",
        "description": "Fetches a public http/https URL and returns readability, metadata, robots, sitemap, llms.txt, Agent Card, pricing/contact, and structured-data signals. This endpoint does not guarantee ranking, citation, inclusion, traffic, or revenue.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["url"],
                "properties": {
                  "url": {
                    "type": "string",
                    "format": "uri",
                    "examples": ["https://example.com"]
                  },
                  "website": {
                    "type": "string",
                    "format": "uri"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audit result envelope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/audit-reports": {
      "get": {
        "tags": ["Diagnostics"],
        "operationId": "listPublicAuditReports",
        "summary": "List public audit reports",
        "parameters": [
          {
            "name": "public",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["1", "true"]
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public audit report list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    },
    "/api/audit-reports/{id}": {
      "get": {
        "tags": ["Diagnostics"],
        "operationId": "getAuditReport",
        "summary": "Read one public audit report",
        "parameters": [
          {
            "name": "id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Public audit report",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/agent-commerce/orders": {
      "post": {
        "tags": ["Orders"],
        "operationId": "createAgentCommerceOrder",
        "summary": "Create a paid AI search visibility package order",
        "description": "Creates an order with status pending_payment. The order is not revenue until the owner manually verifies a real WeChat or Alipay QR receipt.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrderCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Order created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/agent-commerce/orders/{order_id}": {
      "get": {
        "tags": ["Orders"],
        "operationId": "getAgentCommerceOrder",
        "summary": "Read an order by id",
        "parameters": [
          {
            "name": "order_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Order envelope",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/agent-commerce/orders/{order_id}/payment-claim": {
      "post": {
        "tags": ["Orders"],
        "operationId": "submitPaymentClaim",
        "summary": "Submit a manual QR payment claim for owner verification",
        "description": "Records that a human says they paid by QR. This does not mark the order paid, does not count as revenue, and does not start delivery. The owner must manually confirm the real WeChat or Alipay receipt.",
        "parameters": [
          {
            "name": "order_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentClaimRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Payment claim recorded; receiptVerified and revenueCounted remain false",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/feedback": {
      "post": {
        "tags": ["Feedback"],
        "operationId": "createFeedback",
        "summary": "Submit a user need or service question",
        "description": "Stores feedback in the backend and creates an owner site message. If the request includes a valid user bearer token, the user also receives a confirmation site message. Email notification has been removed.",
        "security": [
          {},
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FeedbackRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Feedback saved",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/register": {
      "post": {
        "tags": ["Accounts"],
        "operationId": "registerUser",
        "summary": "Register a user account",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RegisterRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Registered and logged in",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/login": {
      "post": {
        "tags": ["Accounts"],
        "operationId": "loginUser",
        "summary": "Log in and receive a bearer token",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Logged in",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/me": {
      "get": {
        "tags": ["Accounts"],
        "operationId": "getCurrentUser",
        "summary": "Read current user profile",
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Current user",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/users": {
      "get": {
        "tags": ["Accounts"],
        "operationId": "listUsersForOwner",
        "summary": "List registered users for owner management",
        "description": "Owner-only endpoint. Requires owner_token query parameter. Returns public user profile fields only, never password hashes.",
        "parameters": [
          {
            "name": "owner_token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Registered user list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "403": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/users/{user_id}": {
      "patch": {
        "tags": ["Accounts"],
        "operationId": "updateUserForOwner",
        "summary": "Update a user profile or active/disabled status",
        "description": "Owner-only endpoint. The owner can enable or disable a user and edit name, contact, and website fields.",
        "parameters": [
          {
            "name": "user_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UserUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated user",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/site-messages": {
      "get": {
        "tags": ["Accounts"],
        "operationId": "listSiteMessages",
        "summary": "List site messages for the current user",
        "description": "With a bearer token, returns messages visible to the logged-in user. With owner_token, returns owner/admin messages.",
        "parameters": [
          {
            "name": "owner_token",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "Optional owner token. If provided and valid, returns owner/admin inbox messages."
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "responses": {
          "200": {
            "description": "Site-message list",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          }
        }
      },
      "post": {
        "tags": ["Accounts"],
        "operationId": "createSiteMessageForOwner",
        "summary": "Send an owner site message to a user or owner role inbox",
        "description": "Owner-only endpoint. Used for delivery communication, service status updates, order follow-up, and owner-to-user messages. Email notification has been removed.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SiteMessageCreateRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Site message created",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/site-messages/{message_id}": {
      "patch": {
        "tags": ["Accounts"],
        "operationId": "updateSiteMessageStatus",
        "summary": "Update site-message read/archive status",
        "description": "A logged-in user can update visible messages with bearer auth. The owner can update any owner-visible message by passing owner_token in the JSON body.",
        "parameters": [
          {
            "name": "message_id",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SiteMessageUpdateRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Updated site message",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          },
          "400": {
            "$ref": "#/components/responses/Error"
          },
          "401": {
            "$ref": "#/components/responses/Error"
          },
          "403": {
            "$ref": "#/components/responses/Error"
          },
          "404": {
            "$ref": "#/components/responses/Error"
          }
        }
      }
    },
    "/api/conversion-events": {
      "post": {
        "tags": ["Tracking"],
        "operationId": "createConversionEvent",
        "summary": "Record a conversion or DAU event",
        "description": "Used for traffic quality and DAU tracking. Events are never revenue.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConversionEventRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Event recorded with revenueCounted=false",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Envelope"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer"
      }
    },
    "responses": {
      "Error": {
        "description": "Error response",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    },
    "schemas": {
      "Envelope": {
        "type": "object",
        "properties": {
          "source": {
            "type": "string",
            "const": "agent2merchant-service"
          },
          "generatedAt": {
            "type": "string",
            "format": "date-time"
          },
          "data": {
            "type": "object"
          }
        }
      },
      "OrderCreateRequest": {
        "type": "object",
        "required": ["website", "customer_contact"],
        "properties": {
          "service_id": {
            "type": "string",
            "enum": [
              "ai_search_visibility_entry_scan_9_9",
              "ai_search_visibility_fix_pack_59_9",
              "ai_search_visibility_today_fix_99_9"
            ],
            "default": "ai_search_visibility_fix_pack_59_9",
            "description": "Use ai_search_visibility_entry_scan_9_9 for 9.9 CNY, ai_search_visibility_fix_pack_59_9 for 59.9 CNY, or ai_search_visibility_today_fix_99_9 for 99.9 CNY."
          },
          "website": {
            "type": "string",
            "format": "uri"
          },
          "customer_contact": {
            "type": "string",
            "description": "WeChat, phone, site-message account, or another contact path."
          },
          "customer_name": {
            "type": "string"
          },
          "target_models": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": ["doubao", "kimi", "deepseek", "chatgpt-search", "other"]
            },
            "default": ["doubao", "kimi", "deepseek"]
          },
          "note": {
            "type": "string"
          },
          "agent_id": {
            "type": "string"
          },
          "agent_name": {
            "type": "string"
          },
          "session_id": {
            "type": "string"
          }
        }
      },
      "PaymentClaimRequest": {
        "type": "object",
        "required": ["payment_method", "payer_contact"],
        "properties": {
          "payment_method": {
            "type": "string",
            "enum": ["wechat", "alipay", "manual_qr"]
          },
          "amount_text": {
            "type": "string",
            "examples": ["9.9 CNY", "59.9 CNY", "99.9 CNY"]
          },
          "payer_contact": {
            "type": "string"
          },
          "payment_note": {
            "type": "string",
            "description": "Order id or website domain used in the payment note."
          }
        }
      },
      "FeedbackRequest": {
        "type": "object",
        "required": ["message"],
        "properties": {
          "name": {
            "type": "string"
          },
          "contact": {
            "type": "string"
          },
          "website": {
            "type": "string",
            "format": "uri"
          },
          "need_type": {
            "type": "string",
            "examples": ["Doubao/Kimi/DeepSeek visibility fix"]
          },
          "budget": {
            "type": "string"
          },
          "message": {
            "type": "string",
            "minLength": 4
          },
          "source_page": {
            "type": "string"
          }
        }
      },
      "RegisterRequest": {
        "type": "object",
        "required": ["contact", "password"],
        "properties": {
          "name": {
            "type": "string"
          },
          "contact": {
            "type": "string"
          },
          "website": {
            "type": "string"
          },
          "password": {
            "type": "string",
            "minLength": 6
          },
          "source_page": {
            "type": "string"
          }
        }
      },
      "LoginRequest": {
        "type": "object",
        "required": ["contact", "password"],
        "properties": {
          "contact": {
            "type": "string"
          },
          "password": {
            "type": "string"
          }
        }
      },
      "UserUpdateRequest": {
        "type": "object",
        "required": ["owner_token"],
        "properties": {
          "owner_token": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": ["active", "disabled"]
          },
          "name": {
            "type": "string"
          },
          "contact": {
            "type": "string"
          },
          "website": {
            "type": "string"
          }
        }
      },
      "SiteMessageCreateRequest": {
        "type": "object",
        "required": ["owner_token", "title", "body"],
        "properties": {
          "owner_token": {
            "type": "string"
          },
          "recipient_user_id": {
            "type": "string",
            "description": "Target registered user id. Required unless recipient_role is provided."
          },
          "recipient_role": {
            "type": "string",
            "description": "Role inbox, such as owner. Required unless recipient_user_id is provided."
          },
          "title": {
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "website": {
            "type": "string"
          },
          "type": {
            "type": "string",
            "default": "owner_message"
          },
          "source_id": {
            "type": "string"
          }
        }
      },
      "SiteMessageUpdateRequest": {
        "type": "object",
        "required": ["status"],
        "properties": {
          "owner_token": {
            "type": "string",
            "description": "Optional owner token for owner/admin updates."
          },
          "status": {
            "type": "string",
            "enum": ["unread", "read", "archived"]
          }
        }
      },
      "ConversionEventRequest": {
        "type": "object",
        "required": ["event_type"],
        "properties": {
          "event_type": {
            "type": "string"
          },
          "source_page": {
            "type": "string"
          },
          "source_path": {
            "type": "string"
          },
          "website": {
            "type": "string"
          },
          "offer_id": {
            "type": "string"
          },
          "order_id": {
            "type": "string"
          },
          "visitor_id": {
            "type": "string"
          },
          "session_id": {
            "type": "string"
          }
        }
      }
    }
  }
}