{
  "openapi": "3.0.3",
  "info": {
    "title": "星火AI代理API",
    "version": "1.0.0",
    "description": "供代理商城服务端调用。客户向主站支付宝付款，真实到账后发货。金额单位为分，每单1份，按主站零售价及代理档位计佣。密钥不能放在前端，支付返回主站，本版通过轮询查询发货。"
  },
  "servers": [
    {
      "url": "https://xn--ai-4y7dq09a.com/api/partner/v1"
    }
  ],
  "security": [
    {
      "AgentKey": []
    }
  ],
  "paths": {
    "/products": {
      "get": {
        "operationId": "listProducts",
        "summary": "商品与可用库存",
        "responses": {
          "200": {
            "description": "商品列表",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "currency",
                    "settlement",
                    "paymentAvailable",
                    "products"
                  ],
                  "properties": {
                    "currency": {
                      "type": "string",
                      "enum": [
                        "CNY"
                      ]
                    },
                    "settlement": {
                      "type": "string",
                      "enum": [
                        "customer_alipay"
                      ]
                    },
                    "paymentAvailable": {
                      "type": "boolean"
                    },
                    "products": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Product"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求参数有误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "密钥无效、过期、停用或代理已停用",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "订单或接口不存在",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "库存不足、订单号冲突或订单状态不允许付款",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "请求超过4096字符",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Content-Type需为application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "超出每分钟请求限额",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "等待秒数"
              }
            }
          },
          "503": {
            "description": "支付宝未接通或服务暂不可用",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/orders": {
      "post": {
        "operationId": "createOrder",
        "summary": "创建订单，同一代理订单号幂等",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "merchantOrderId",
                  "productId"
                ],
                "properties": {
                  "merchantOrderId": {
                    "type": "string",
                    "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$"
                  },
                  "productId": {
                    "type": "string",
                    "example": "chatgpt-plus"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "幂等重试返回原订单",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "201": {
            "description": "新建订单",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "description": "请求参数有误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "密钥无效、过期、停用或代理已停用",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "订单或接口不存在",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "库存不足、订单号冲突或订单状态不允许付款",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "请求超过4096字符",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Content-Type需为application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "超出每分钟请求限额",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "等待秒数"
              }
            }
          },
          "503": {
            "description": "支付宝未接通或服务暂不可用",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/orders/{merchantOrderId}": {
      "get": {
        "operationId": "getOrder",
        "summary": "查询自己API创建的订单和发货，建议每10至15秒轮询",
        "parameters": [
          {
            "name": "merchantOrderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "订单状态；确认到账发货后包含delivery",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Order"
                }
              }
            }
          },
          "400": {
            "description": "请求参数有误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "密钥无效、过期、停用或代理已停用",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "订单或接口不存在",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "库存不足、订单号冲突或订单状态不允许付款",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "请求超过4096字符",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Content-Type需为application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "超出每分钟请求限额",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "等待秒数"
              }
            }
          },
          "503": {
            "description": "支付宝未接通或服务暂不可用",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    },
    "/orders/{merchantOrderId}/payment": {
      "post": {
        "operationId": "createPaymentLink",
        "summary": "获取支付宝跳转地址；返回主站订单页",
        "parameters": [
          {
            "name": "merchantOrderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "跳转地址",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "paymentUrl",
                    "orderUrl"
                  ],
                  "properties": {
                    "paymentUrl": {
                      "type": "string",
                      "format": "uri"
                    },
                    "orderUrl": {
                      "type": "string",
                      "format": "uri"
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "请求参数有误",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "密钥无效、过期、停用或代理已停用",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "404": {
            "description": "订单或接口不存在",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "409": {
            "description": "库存不足、订单号冲突或订单状态不允许付款",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "413": {
            "description": "请求超过4096字符",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "415": {
            "description": "Content-Type需为application/json",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "超出每分钟请求限额",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            },
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer"
                },
                "description": "等待秒数"
              }
            }
          },
          "503": {
            "description": "支付宝未接通或服务暂不可用",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "AgentKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "xh_live_<keyId>_<secret>"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "error"
        ],
        "properties": {
          "error": {
            "type": "string"
          }
        }
      },
      "Product": {
        "type": "object",
        "required": [
          "id",
          "name",
          "priceCents",
          "stock"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "priceCents": {
            "type": "integer",
            "minimum": 1,
            "description": "主站零售价，分"
          },
          "stock": {
            "type": "integer",
            "minimum": 0
          }
        }
      },
      "Order": {
        "type": "object",
        "required": [
          "merchantOrderId",
          "orderId",
          "productId",
          "productName",
          "priceCents",
          "currency",
          "status",
          "paymentVerified",
          "expiresAt",
          "checkoutUrl"
        ],
        "properties": {
          "merchantOrderId": {
            "type": "string",
            "pattern": "^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$"
          },
          "orderId": {
            "type": "string"
          },
          "productId": {
            "type": "string"
          },
          "productName": {
            "type": "string"
          },
          "priceCents": {
            "type": "integer",
            "minimum": 1
          },
          "currency": {
            "type": "string",
            "enum": [
              "CNY"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "pending",
              "delivered",
              "expired"
            ]
          },
          "paymentVerified": {
            "type": "boolean"
          },
          "expiresAt": {
            "type": "integer",
            "format": "int64",
            "description": "Unix毫秒时间戳"
          },
          "checkoutUrl": {
            "type": "string",
            "format": "uri",
            "description": "含订单访问凭证，只提供给该订单客户"
          },
          "delivery": {
            "type": "object",
            "description": "仅确认到账并发货后出现",
            "required": [
              "code"
            ],
            "properties": {
              "code": {
                "type": "string"
              }
            }
          }
        }
      }
    }
  }
}