{
  "openapi": "3.1.0",
  "info": {
    "title": "奇门云 API：旺店通与聚水潭只读查单",
    "version": "1.0.0",
    "description": "客户请求顶层统一使用 sid（字符串），值为旺店通 SID 或聚水潭 customer_id。Authorization: Bearer 使用客户自己的服务密钥。服务器根据密钥所属账号匹配已启用的 SID，注入上游授权并签名。同账号跨平台 SID 重复时须传 platform；同平台重复绑定应清理。旧 bindingId 兼容保留但不与 sid 同传。示例不包含可用凭据。旺店通网页版全目录见 /docs/wangdian-web。"
  },
  "servers": [
    {
      "url": "https://api.miandanni.com",
      "description": "奇门云生产网关；程序只向此服务发送客户奇门云密钥。"
    }
  ],
  "externalDocs": {
    "url": "https://api.miandanni.com/docs/ai-integration.md",
    "description": "奇门云 AI 接入手册"
  },
  "tags": [
    {
      "name": "只读查单",
      "description": "仅查询用户已授权的订单，不创建、修改、取消订单。"
    }
  ],
  "security": [
    {
      "QimenyunBearer": []
    }
  ],
  "paths": {
    "/api/gateway": {
      "post": {
        "operationId": "queryAuthorizedOrders",
        "summary": "通过奇门云查询旺店通企业版或聚水潭订单",
        "description": "选择下面 oneOf 的一种请求。旺店通通过自己已启用的 SID 路由；聚水潭也通过 sid 路由，sid 的值填写自己的 customer_id。不要同时发送 sid 和 bindingId，也不要发送 body、provider、appkey、appsecret、sign、timestamp 或上游地址。params 是对象；聚水潭这条奇门接口的业务字段直接放入 params，不套 biz。订单号始终保留为字符串。鉴权、服务到期、绑定归属与平台开关由网关验证；订单号与分页业务语义最终由上游验证。本规范不承诺错误订单号会被网关以 HTTP 400 拒绝。",
        "tags": [
          "只读查单"
        ],
        "security": [
          {
            "QimenyunBearer": []
          }
        ],
        "x-read-only-methods": [
          "wdt.trade.query",
          "jushuitan.order.list.query"
        ],
        "requestBody": {
          "required": true,
          "description": "UTF-8 JSON，完整正文不超过 512 KiB。只使用本规范的一种最小查单形态。",
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "$ref": "#/components/schemas/WangdianOrderQuery"
                  },
                  {
                    "$ref": "#/components/schemas/JushuitanOrderQuery"
                  }
                ]
              },
              "examples": {
                "wangdianSynthetic": {
                  "summary": "Synthetic：旺店通原平台订单号查询",
                  "description": "合成演示值，不是真实 SID 或订单。将 example_sid 换成用户自己的已启用 SID，将全零订单号换成真实订单字符串。",
                  "x-synthetic": true,
                  "value": {
                    "sid": "example_sid",
                    "method": "wdt.trade.query",
                    "params": {
                      "src_tid": "0000000000000000000"
                    }
                  }
                },
                "jushuitanSynthetic": {
                  "summary": "Synthetic：聚水潭线上订单号查询",
                  "description": "合成演示值。synthetic_customer_id 必须替换为当前客户已启用的聚水潭 customer_id，在本平台作为字符串 sid 传入。订单号为字符串。",
                  "x-synthetic": true,
                  "value": {
                    "method": "jushuitan.order.list.query",
                    "params": {
                      "so_ids": "0000000000000000000",
                      "page_index": 1,
                      "page_size": 25
                    },
                    "sid": "synthetic_customer_id"
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "上游原始响应。HTTP 200 仅说明 HTTP 调用成功，仍需检查实际返回的奇门或平台业务错误。奇门云不额外包装 ok/data，不保证固定字段、列表位置、收件人信息或一定有订单。按当前上游官方文档解析；未知字段和原始响应应保留。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpstreamJson"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string",
                  "description": "上游可能返回非 JSON；应作为异常响应处理，不假装成功订单。"
                }
              },
              "*/*": {
                "schema": {
                  "description": "其他上游原始响应内容。"
                }
              }
            },
            "headers": {
              "X-Upstream-Request-Id": {
                "description": "若上游提供请求编号，奇门云可能转发此响应头；不是必返字段。",
                "schema": {
                  "type": "string"
                }
              },
              "Cache-Control": {
                "description": "奇门云设置为 no-store。",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "请求格式、字段、路由或平台方法不正确。请根据 error.code 修正请求，不要盲目重试。 下列错误码用于奇门云自身拒绝的响应；若同一 HTTP 状态来自上游，奇门云会原样透传上游正文，不能只凭状态码断定错误来源。",
            "x-gateway-error-codes": [
              "VALIDATION_ERROR",
              "INVALID_JSON",
              "OBJECT_REQUIRED",
              "UNKNOWN_FIELDS",
              "INVALID_ROUTING_ID",
              "CONFLICTING_ROUTE",
              "INVALID_PARAMETER",
              "PARAMETER_TOO_LARGE",
              "PARAMETER_NESTING_TOO_DEEP",
              "PROTECTED_PARAMETER",
              "PROVIDER_METHOD_MISMATCH",
              "PROVIDER_BODY_NOT_ALLOWED"
            ],
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/GatewayError"
                    },
                    {
                      "$ref": "#/components/schemas/UpstreamJson"
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "*/*": {
                "schema": {}
              }
            }
          },
          "401": {
            "description": "缺少奇门云 Bearer 密钥、密钥无效或客户账号已停用。检查 appsecret；这不是淘宝 AppSecret。 下列错误码用于奇门云自身拒绝的响应；若同一 HTTP 状态来自上游，奇门云会原样透传上游正文，不能只凭状态码断定错误来源。",
            "x-gateway-error-codes": [
              "INVALID_API_KEY"
            ],
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/GatewayError"
                    },
                    {
                      "$ref": "#/components/schemas/UpstreamJson"
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "*/*": {
                "schema": {}
              }
            }
          },
          "402": {
            "description": "奇门云服务未开通或已到期。到奇门云服务台开通或续费。客户端不要自己计算到期时间。 下列错误码用于奇门云自身拒绝的响应；若同一 HTTP 状态来自上游，奇门云会原样透传上游正文，不能只凭状态码断定错误来源。",
            "x-gateway-error-codes": [
              "SUBSCRIPTION_REQUIRED"
            ],
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/GatewayError"
                    },
                    {
                      "$ref": "#/components/schemas/UpstreamJson"
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "*/*": {
                "schema": {}
              }
            }
          },
          "403": {
            "description": "未提供平台路由，或当前平台已暂停开放。 下列错误码用于奇门云自身拒绝的响应；若同一 HTTP 状态来自上游，奇门云会原样透传上游正文，不能只凭状态码断定错误来源。",
            "x-gateway-error-codes": [
              "BINDING_REQUIRED",
              "PLATFORM_METHODS_DISABLED"
            ],
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/GatewayError"
                    },
                    {
                      "$ref": "#/components/schemas/UpstreamJson"
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "*/*": {
                "schema": {}
              }
            }
          },
          "404": {
            "description": "指定 SID 或绑定编号在当前客户账号下不存在、未启用或已停用。绑定保存后立即启用。 下列错误码用于奇门云自身拒绝的响应；若同一 HTTP 状态来自上游，奇门云会原样透传上游正文，不能只凭状态码断定错误来源。",
            "x-gateway-error-codes": [
              "BINDING_NOT_FOUND"
            ],
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/GatewayError"
                    },
                    {
                      "$ref": "#/components/schemas/UpstreamJson"
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "*/*": {
                "schema": {}
              }
            }
          },
          "405": {
            "description": "对奇门云网关使用了非 POST 请求方法。 下列错误码用于奇门云自身拒绝的响应；若同一 HTTP 状态来自上游，奇门云会原样透传上游正文，不能只凭状态码断定错误来源。",
            "x-gateway-error-codes": [
              "METHOD_NOT_ALLOWED"
            ],
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/GatewayError"
                    },
                    {
                      "$ref": "#/components/schemas/UpstreamJson"
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "*/*": {
                "schema": {}
              }
            }
          },
          "409": {
            "description": "当前客户的同一 SID 存在多条已启用的旺店通企业版绑定；需要保留一条有效绑定。 下列错误码用于奇门云自身拒绝的响应；若同一 HTTP 状态来自上游，奇门云会原样透传上游正文，不能只凭状态码断定错误来源。",
            "x-gateway-error-codes": [
              "AMBIGUOUS_SID"
            ],
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/GatewayError"
                    },
                    {
                      "$ref": "#/components/schemas/UpstreamJson"
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "*/*": {
                "schema": {}
              }
            }
          },
          "413": {
            "description": "JSON 请求正文超过 512 KiB。 下列错误码用于奇门云自身拒绝的响应；若同一 HTTP 状态来自上游，奇门云会原样透传上游正文，不能只凭状态码断定错误来源。",
            "x-gateway-error-codes": [
              "BODY_TOO_LARGE"
            ],
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/GatewayError"
                    },
                    {
                      "$ref": "#/components/schemas/UpstreamJson"
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "*/*": {
                "schema": {}
              }
            }
          },
          "415": {
            "description": "Content-Type 必须是 application/json，可带 charset=utf-8。 下列错误码用于奇门云自身拒绝的响应；若同一 HTTP 状态来自上游，奇门云会原样透传上游正文，不能只凭状态码断定错误来源。",
            "x-gateway-error-codes": [
              "JSON_REQUIRED"
            ],
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/GatewayError"
                    },
                    {
                      "$ref": "#/components/schemas/UpstreamJson"
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "*/*": {
                "schema": {}
              }
            }
          },
          "500": {
            "description": "服务器内部异常。保留错误码并联系奇门云管理员。 下列错误码用于奇门云自身拒绝的响应；若同一 HTTP 状态来自上游，奇门云会原样透传上游正文，不能只凭状态码断定错误来源。",
            "x-gateway-error-codes": [
              "INTERNAL_ERROR",
              "INVALID_PROVIDER_ROUTE"
            ],
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/GatewayError"
                    },
                    {
                      "$ref": "#/components/schemas/UpstreamJson"
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "*/*": {
                "schema": {}
              }
            }
          },
          "502": {
            "description": "奇门云连接上游失败或超时。对本说明的只读查单可稍后重试，避免持续高频重试。 下列错误码用于奇门云自身拒绝的响应；若同一 HTTP 状态来自上游，奇门云会原样透传上游正文，不能只凭状态码断定错误来源。",
            "x-gateway-error-codes": [
              "UPSTREAM_UNAVAILABLE"
            ],
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/GatewayError"
                    },
                    {
                      "$ref": "#/components/schemas/UpstreamJson"
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "*/*": {
                "schema": {}
              }
            }
          },
          "503": {
            "description": "服务器的奇门应用或平台配置尚未就绪。请联系奇门云管理员。 下列错误码用于奇门云自身拒绝的响应；若同一 HTTP 状态来自上游，奇门云会原样透传上游正文，不能只凭状态码断定错误来源。",
            "x-gateway-error-codes": [
              "GATEWAY_NOT_CONFIGURED",
              "PROVIDER_NOT_CONFIGURED"
            ],
            "content": {
              "application/json": {
                "schema": {
                  "anyOf": [
                    {
                      "$ref": "#/components/schemas/GatewayError"
                    },
                    {
                      "$ref": "#/components/schemas/UpstreamJson"
                    }
                  ]
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "*/*": {
                "schema": {}
              }
            }
          },
          "default": {
            "description": "未列出的上游 HTTP 状态及正文也会原样透传；不要强制转换为奇门云错误封装，也不要仅凭 HTTP 状态假定业务结果。",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UpstreamJson"
                }
              },
              "text/plain": {
                "schema": {
                  "type": "string"
                }
              },
              "*/*": {
                "schema": {}
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "QimenyunBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "客户自己的奇门云代理密钥。若程序配置字段名为 appsecret，应把它转换为 Authorization: Bearer <客户奇门云密钥>，不能放入 JSON。无需淘宝签名、Cookie 或短信验证码。新密钥通常为 32 位小写十六进制，旧密钥继续兼容；客户端不应把格式检测作为鉴权或有效期判断。文档不提供可用的密钥。"
      }
    },
    "schemas": {
      "WangdianOrderQuery": {
        "type": "object",
        "description": "推荐的旺店通企业版最小查单形态；不包含旧 bindingId 兼容模式或其他业务过滤条件。",
        "additionalProperties": false,
        "required": [
          "sid",
          "method",
          "params"
        ],
        "properties": {
          "sid": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$",
            "description": "当前客户已启用的平台 SID，区分大小写。"
          },
          "method": {
            "type": "string",
            "const": "wdt.trade.query",
            "description": "旺店通订单管理查询，对应官方 trade_query.php。"
          },
          "params": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "src_tid"
            ],
            "description": "本规范只列按原平台单号查询。需要其他查询条件时先核对旺店通对应官方文档。",
            "properties": {
              "src_tid": {
                "type": "string",
                "minLength": 1,
                "description": "原平台订单号。必须使用 JSON 字符串，避免长整数精度丢失。"
              }
            }
          },
          "platform": {
            "type": "string",
            "const": "wangdian_qyb",
            "description": "同 SID 在多个平台绑定时指定平台。"
          }
        }
      },
      "JushuitanOrderQuery": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "sid",
          "method",
          "params"
        ],
        "description": "聚水潭奇门最小查单形态，服务端根据客户密钥与 sid 查找授权。",
        "properties": {
          "method": {
            "type": "string",
            "const": "jushuitan.order.list.query",
            "description": "聚水潭奇门淘系订单查询列表。"
          },
          "params": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "so_ids",
              "page_index",
              "page_size"
            ],
            "description": "奇门业务参数直接平铺，不使用普通开放平台的 biz 包装。分页约束来自对应上游官方文档，网关不会替代上游验证业务语义。",
            "properties": {
              "so_ids": {
                "type": "string",
                "minLength": 1,
                "description": "线上订单号字符串；多个订单号使用英文逗号连接，不能用数组或数字。"
              },
              "page_index": {
                "type": "integer",
                "minimum": 1,
                "description": "从第 1 页开始。仅获取当前页；需要后续结果时按上游实际返回继续翻页。"
              },
              "page_size": {
                "type": "integer",
                "minimum": 1,
                "maximum": 100,
                "default": 25,
                "description": "每页条数，本例 25，官方文档上限 100。"
              }
            }
          },
          "sid": {
            "type": "string",
            "minLength": 1,
            "maxLength": 128,
            "pattern": "^[A-Za-z0-9][A-Za-z0-9._:@-]{0,127}$",
            "description": "客户自己的聚水潭 customer_id，在本平台统一称为 sid，必须为字符串。"
          },
          "platform": {
            "type": "string",
            "const": "jushuitan"
          }
        }
      },
      "GatewayError": {
        "type": "object",
        "required": [
          "ok",
          "error"
        ],
        "additionalProperties": false,
        "description": "仅用于奇门云自身产生的错误。上游错误可能使用完全不同的 JSON 格式或非 JSON 正文。",
        "properties": {
          "ok": {
            "type": "boolean",
            "const": false
          },
          "error": {
            "type": "object",
            "required": [
              "code",
              "message"
            ],
            "additionalProperties": false,
            "properties": {
              "code": {
                "type": "string",
                "description": "可用于程序分支判断的奇门云错误码，见各 HTTP 状态的 x-gateway-error-codes。"
              },
              "message": {
                "type": "string",
                "description": "面向人的说明文字，不建议硬编码匹配。"
              },
              "details": {
                "description": "可选的额外错误资料；当前多数网关错误不提供，结构未固定。"
              }
            }
          }
        }
      },
      "UpstreamJson": {
        "description": "上游任意原始 JSON 值，不固定 success/data/response/orders/trades 的字段层级。成功业务结果、平台业务错误都可能以 HTTP 200 返回。不要将这一空约束理解成返回空对象。"
      }
    }
  }
}