{
  "openapi": "3.1.0",
  "info": {
    "title": "YOUROOM ↔ qi-shoppy 訂單整合 API",
    "version": "0.6.0-draft",
    "description": "設計契約草案，端點尚未實作／上線，無可用 API 主機。現有網站僅執行瀏覽器本機示範。需 qi-shoppy 文件確認欄位、身分綁定及狀態映射後定版。 此版補充舊訂單賣家歸屬、稽核事件及 QG 來源事實分離。所有新增端點均未實作／未上線，不能將收款或代付事件推定為商品買賣或物流證據。"
  },
  "paths": {
    "/v1/integrations/qi-shoppy/orders": {
      "post": {
        "summary": "匯入或更新單筆來源訂單（僅服務端）",
        "security": [
          {
            "ServiceBearer": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 16,
              "maxLength": 128
            },
            "description": "每個建立／更新動作唯一；同客戶同 key 同內容回傳原結果，不同內容回 409。至少保留 7 天。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SourceOrder"
              }
            }
          }
        },
        "responses": {
          "200": {
            "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"
                }
              }
            }
          },
          "403": {
            "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"
                }
              }
            }
          },
          "422": {
            "description": "商品不可售、欠缺證據或條件不足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "超出頻率限制",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-required-scope": "orders:write"
      }
    },
    "/v1/orders": {
      "get": {
        "summary": "查詢授權會員訂單",
        "security": [
          {
            "ServiceBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "items": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Order"
                      }
                    },
                    "nextCursor": {
                      "type": [
                        "string",
                        "null"
                      ]
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "格式或金額錯誤",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "未驗證",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "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"
                }
              }
            }
          },
          "422": {
            "description": "商品不可售、欠缺證據或條件不足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "超出頻率限制",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "cursor",
            "in": "query",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 20
            }
          }
        ],
        "x-required-scope": "orders:read"
      }
    },
    "/v1/orders/{orderId}": {
      "parameters": [
        {
          "name": "orderId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "summary": "查詢單筆訂單及來源狀態",
        "security": [
          {
            "ServiceBearer": []
          }
        ],
        "responses": {
          "200": {
            "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"
                }
              }
            }
          },
          "403": {
            "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"
                }
              }
            }
          },
          "422": {
            "description": "商品不可售、欠缺證據或條件不足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "超出頻率限制",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-required-scope": "orders:read"
      }
    },
    "/v1/orders/{orderId}/matches": {
      "parameters": [
        {
          "name": "orderId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "summary": "建立金額完全相同的配對方案",
        "security": [
          {
            "ServiceBearer": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 16,
              "maxLength": 128
            },
            "description": "每個建立／更新動作唯一；同客戶同 key 同內容回傳原結果，不同內容回 409。至少保留 7 天。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MatchRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Match"
                }
              }
            }
          },
          "400": {
            "description": "格式或金額錯誤",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "未驗證",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "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"
                }
              }
            }
          },
          "422": {
            "description": "商品不可售、欠缺證據或條件不足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "超出頻率限制",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-required-scope": "matches:write"
      },
      "get": {
        "summary": "查詢配對方案",
        "security": [
          {
            "ServiceBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/Match"
                  }
                }
              }
            }
          },
          "400": {
            "description": "格式或金額錯誤",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "未驗證",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "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"
                }
              }
            }
          },
          "422": {
            "description": "商品不可售、欠缺證據或條件不足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "超出頻率限制",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-required-scope": "orders:read"
      }
    },
    "/v1/orders/{orderId}/matches/{matchId}/confirm": {
      "parameters": [
        {
          "name": "orderId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        },
        {
          "name": "matchId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "summary": "確認組合；只進入待供貨，不完成交易",
        "security": [
          {
            "ServiceBearer": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 16,
              "maxLength": 128
            },
            "description": "每個建立／更新動作唯一；同客戶同 key 同內容回傳原結果，不同內容回 409。至少保留 7 天。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Confirmation"
              }
            }
          }
        },
        "responses": {
          "200": {
            "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"
                }
              }
            }
          },
          "403": {
            "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"
                }
              }
            }
          },
          "422": {
            "description": "商品不可售、欠缺證據或條件不足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "超出頻率限制",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-required-scope": "matches:confirm"
      }
    },
    "/v1/orders/{orderId}/fulfillments": {
      "parameters": [
        {
          "name": "orderId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "post": {
        "summary": "以可驗證交付事件更新交易狀態（受權限及證據檢核）",
        "security": [
          {
            "ServiceBearer": []
          }
        ],
        "parameters": [
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 16,
              "maxLength": 128
            },
            "description": "每個建立／更新動作唯一；同客戶同 key 同內容回傳原結果，不同內容回 409。至少保留 7 天。"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Fulfillment"
              }
            }
          }
        },
        "responses": {
          "200": {
            "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"
                }
              }
            }
          },
          "403": {
            "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"
                }
              }
            }
          },
          "422": {
            "description": "商品不可售、欠缺證據或條件不足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "超出頻率限制",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-required-scope": "fulfillments:write"
      }
    },
    "/v1/orders/{orderId}/delivery-plan": {
      "parameters": [
        {
          "name": "orderId",
          "in": "path",
          "required": true,
          "schema": {
            "type": "string"
          }
        }
      ],
      "get": {
        "summary": "查詢依下單時間產生的配送預估安排（未實作）",
        "security": [
          {
            "ServiceBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "成功",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeliveryPlan"
                }
              }
            }
          },
          "400": {
            "description": "格式或金額錯誤",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "401": {
            "description": "未驗證",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "403": {
            "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"
                }
              }
            }
          },
          "422": {
            "description": "商品不可售、欠缺證據或條件不足",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          },
          "429": {
            "description": "超出頻率限制",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                }
              }
            }
          }
        },
        "x-required-scope": "orders:read"
      }
    },
    "/v1/orders/{orderId}/seller-attributions": {
      "post": {
        "summary": "草案：設定舊訂單商品行賣家歸屬（尚未實作）",
        "description": "僅授權營運角色；服務端驗證 member/order/seller 關係、版本、提領鎖定與實際商品交易證據。原子更新稽核、退款分攤、結算投影；相同歸屬不重複入帳。不得把來源收款／代付單自動轉成商品交易。",
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "ServiceBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SellerAttributionRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "原結果或更新後歸屬／版本／稽核事件 ID"
          },
          "403": {
            "description": "未授權操作此訂單"
          },
          "409": {
            "description": "版本衝突、提領鎖定或同冪等鍵不同內容"
          }
        }
      }
    },
    "/v1/orders/{orderId}/journal": {
      "get": {
        "summary": "草案：讀取會員自己的訂單事件日誌（尚未實作）",
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "ServiceBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "區分來源事實、實際商品履約及展示事件；未知狀態不補造",
            "content": {
              "application/json": {
                "schema": {
                  "type": "array",
                  "items": {
                    "$ref": "#/components/schemas/JournalEvent"
                  }
                }
              }
            }
          },
          "403": {
            "description": "會員不擁有此訂單"
          }
        }
      }
    },
    "/v1/orders/{orderId}/receiving-destinations": {
      "post": {
        "summary": "草案：保存買家／賣家收貨目的地（尚未實作）",
        "description": "服務端驗證會員與賣家對訂單的權限、地址／門市可配送資格及資料版本；分開買家收貨與賣家退貨收貨用途。保留訂單地址快照，不覆寫歷史物流事件。正式門市清單需以物流簽約 API 查驗。",
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "Idempotency-Key",
            "in": "header",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "ServiceBearer": []
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReceivingDestination"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "地址快照、版本及設定事件 ID"
          },
          "403": {
            "description": "無此收貨用途的訂單權限"
          },
          "409": {
            "description": "版本衝突或已有實際交寄事件，需要改址流程"
          },
          "422": {
            "description": "門市停業、溫層不符、地址或配送區域未通過查驗"
          }
        }
      }
    },
    "/v1/orders/{orderId}/shipping-plan": {
      "get": {
        "summary": "草案：依來源訂單日期查詢條件式預計時程（尚未實作）",
        "description": "保留 sourceOrderCreatedAt，時間必須含時區。預計階段不能寫成實際出貨／到店／簽收；運送限制、假日與實際交寄事件由服務端確認。 配送模擬以獨立 deliverySimulation 投影回傳，simulation=true；不得寫入正式物流事件、付款或結算。若將來由後端執行排程，須用 order+purpose+destination_revision+rule_version+milestone 作冪等鍵。",
        "parameters": [
          {
            "name": "orderId",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "security": [
          {
            "ServiceBearer": []
          }
        ],
        "responses": {
          "200": {
            "description": "sourceOrderCreatedAt、destinationRevision、estimateStages、verifiedActualEvents、trackingNumber（未知為 null）"
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "ServiceBearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "擬定服務端專用短期憑證，實作前確認核發方式；權限 scope 由服務端驗證。不可置於前端或本機示範。會員 API 另需正式已驗證登入 session／token 與會員綁定，不可自行傳 memberId 冒用。"
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": [
          "code",
          "message",
          "requestId"
        ],
        "properties": {
          "code": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "requestId": {
            "type": "string"
          }
        }
      },
      "SourceOrder": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "externalOrderId",
          "externalMemberId",
          "amountMinor",
          "currency",
          "sourceStatus",
          "sourceVersion",
          "occurredAt"
        ],
        "properties": {
          "externalOrderId": {
            "type": "string",
            "maxLength": 100
          },
          "externalMemberId": {
            "type": "string",
            "maxLength": 100
          },
          "amountMinor": {
            "type": "integer",
            "minimum": 1,
            "maximum": 10000000,
            "description": "TWD 分，例如 NT$1000 = 100000。配對商品小計，不含運費／手續費。"
          },
          "currency": {
            "type": "string",
            "enum": [
              "TWD"
            ]
          },
          "sourceStatus": {
            "type": "string",
            "enum": [
              "pending",
              "paid",
              "cancelled",
              "refunded"
            ]
          },
          "sourceVersion": {
            "type": "integer",
            "minimum": 1,
            "description": "同訂單單調遞增版本，避免亂序事件覆寫"
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          },
          "sourceOrderCreatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "來源訂單實際建立時間，必須含時區；不可用 webhook 收到時間、配單時間或查單時間代替。對應前端 sourceOrderCreatedAt。"
          }
        }
      },
      "Order": {
        "type": "object",
        "required": [
          "id",
          "externalOrderId",
          "amountMinor",
          "matchStatus",
          "tradeStatus",
          "version"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "externalOrderId": {
            "type": "string"
          },
          "amountMinor": {
            "type": "integer",
            "minimum": 1
          },
          "currency": {
            "type": "string",
            "enum": [
              "TWD"
            ]
          },
          "sourceStatus": {
            "type": "string"
          },
          "matchStatus": {
            "type": "string",
            "enum": [
              "unmatched",
              "matched",
              "confirmed",
              "no_match",
              "search_limit"
            ]
          },
          "tradeStatus": {
            "type": "string",
            "enum": [
              "not_started",
              "awaiting_supply",
              "ordered",
              "delivered",
              "completed",
              "cancelled",
              "refunded"
            ]
          },
          "version": {
            "type": "integer",
            "minimum": 1
          },
          "createdAt": {
            "type": "string",
            "format": "date-time"
          }
        }
      },
      "MatchRequest": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "kind",
          "pool",
          "maxPerItem",
          "expectedOrderVersion"
        ],
        "properties": {
          "kind": {
            "type": "string",
            "enum": [
              "physical",
              "virtual"
            ]
          },
          "pool": {
            "type": "string",
            "enum": [
              "sellable",
              "reference"
            ],
            "description": "reference 只能產生參考方案，不可直接下單"
          },
          "maxPerItem": {
            "type": "integer",
            "minimum": 1,
            "maximum": 20
          },
          "expectedOrderVersion": {
            "type": "integer",
            "minimum": 1
          }
        }
      },
      "MatchLine": {
        "type": "object",
        "required": [
          "productId",
          "quantity",
          "unitPriceMinor",
          "lineTotalMinor",
          "referenceOnly"
        ],
        "properties": {
          "productId": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "quantity": {
            "type": "integer",
            "minimum": 1
          },
          "unitPriceMinor": {
            "type": "integer",
            "minimum": 1
          },
          "lineTotalMinor": {
            "type": "integer",
            "minimum": 1
          },
          "sourceUrl": {
            "type": "string",
            "format": "uri"
          },
          "referenceOnly": {
            "type": "boolean"
          },
          "variantId": {
            "type": [
              "string",
              "null"
            ],
            "description": "來源 SKU／規格 ID；未提供時為 null，不虛構款式"
          },
          "variantLabel": {
            "type": "string"
          },
          "detailCheckedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "shippingReference": {
            "type": "object",
            "description": "來源配送方式、費率與條件快照，非本站物流或實際應付費用",
            "properties": {
              "method": {
                "type": "string"
              },
              "feeMinor": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 0
              },
              "freeAboveMinor": {
                "type": [
                  "integer",
                  "null"
                ],
                "minimum": 0
              },
              "condition": {
                "type": "string"
              },
              "checkedAt": {
                "type": "string",
                "format": "date-time"
              }
            }
          }
        }
      },
      "Match": {
        "type": "object",
        "required": [
          "id",
          "orderId",
          "status",
          "totalMinor",
          "lines",
          "catalogVersion"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "orderId": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "matched",
              "no_match",
              "search_limit"
            ]
          },
          "totalMinor": {
            "type": "integer",
            "minimum": 0
          },
          "catalogVersion": {
            "type": "string"
          },
          "lines": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/MatchLine"
            }
          }
        }
      },
      "Confirmation": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "expectedOrderVersion",
          "acceptReferenceOnly"
        ],
        "properties": {
          "expectedOrderVersion": {
            "type": "integer",
            "minimum": 1
          },
          "acceptReferenceOnly": {
            "type": "boolean",
            "description": "確認參考組合不代表庫存、付款或交付"
          }
        }
      },
      "Fulfillment": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "expectedOrderVersion",
          "event",
          "evidenceId"
        ],
        "properties": {
          "expectedOrderVersion": {
            "type": "integer",
            "minimum": 1
          },
          "event": {
            "type": "string",
            "enum": [
              "ordered",
              "delivered",
              "buyer_accepted"
            ]
          },
          "evidenceId": {
            "type": "string",
            "description": "指向後端已驗證且屬於該訂單的下單／交付／買家確認證據；不能以金額配對代替"
          }
        }
      },
      "DeliveryPlan": {
        "type": "object",
        "description": "僅預估安排，時間經過不得產生實際配送事件。",
        "properties": {
          "orderId": {
            "type": "string"
          },
          "timeZone": {
            "type": "string",
            "enum": [
              "Asia/Taipei"
            ]
          },
          "ruleVersion": {
            "type": "string"
          },
          "logisticsConnected": {
            "type": "boolean"
          },
          "trackingNumber": {
            "type": [
              "string",
              "null"
            ]
          },
          "estimatedStages": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "kind": {
                  "type": "string",
                  "enum": [
                    "physical",
                    "virtual"
                  ]
                },
                "title": {
                  "type": "string"
                },
                "from": {
                  "type": "string",
                  "format": "date-time"
                },
                "to": {
                  "type": "string",
                  "format": "date-time"
                },
                "conditional": {
                  "type": "boolean",
                  "const": true
                }
              }
            }
          }
        }
      },
      "SellerAttributionRequest": {
        "type": "object",
        "required": [
          "expectedRevision",
          "reason",
          "lines"
        ],
        "properties": {
          "expectedRevision": {
            "type": "integer",
            "minimum": 0
          },
          "reason": {
            "type": "string",
            "minLength": 4,
            "maxLength": 200
          },
          "lines": {
            "type": "array",
            "minItems": 1,
            "items": {
              "type": "object",
              "required": [
                "lineId",
                "sellerId"
              ],
              "properties": {
                "lineId": {
                  "type": "string"
                },
                "sellerId": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "JournalEvent": {
        "type": "object",
        "required": [
          "eventId",
          "eventType",
          "source",
          "occurredAt",
          "receivedAt"
        ],
        "properties": {
          "eventId": {
            "type": "string"
          },
          "eventType": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "company_api",
              "logistics_api",
              "payment_provider",
              "authorized_operator",
              "browser_simulation"
            ]
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time"
          },
          "receivedAt": {
            "type": "string",
            "format": "date-time"
          },
          "sourceVersion": {
            "type": "string"
          },
          "evidenceReference": {
            "type": [
              "string",
              "null"
            ]
          },
          "simulation": {
            "type": "boolean"
          },
          "payload": {
            "type": "object"
          }
        }
      },
      "ReceivingDestination": {
        "type": "object",
        "required": [
          "mode",
          "recipientRole",
          "recipientName",
          "recipientPhone"
        ],
        "properties": {
          "mode": {
            "type": "string",
            "enum": [
              "store",
              "home"
            ]
          },
          "recipientRole": {
            "type": "string",
            "enum": [
              "buyer",
              "seller"
            ]
          },
          "purpose": {
            "type": "string",
            "enum": [
              "buyer_receiving",
              "seller_receiving"
            ]
          },
          "recipientName": {
            "type": "string"
          },
          "recipientPhone": {
            "type": "string"
          },
          "chain": {
            "type": "string",
            "enum": [
              "UNIMART",
              "FAMI",
              "HILIFE",
              "OKMART"
            ]
          },
          "storeCode": {
            "type": "string",
            "description": "原始門市代碼字串，保留英文字母與前導零，不能用統編代替"
          },
          "directoryVersion": {
            "type": "string"
          },
          "temperature": {
            "type": "string"
          },
          "carrierCode": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "district": {
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "postalCode": {
            "type": "string"
          },
          "expectedRevision": {
            "type": "integer"
          },
          "productionValidated": {
            "type": "boolean",
            "readOnly": true
          }
        }
      },
      "SimulatedDeliveryEvent": {
        "type": "object",
        "required": [
          "id",
          "key",
          "occurredAt",
          "recordedAt",
          "simulation",
          "source"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "key": {
            "type": "string",
            "enum": [
              "created",
              "preparing",
              "dispatched",
              "in_transit",
              "arrived",
              "received",
              "stopped"
            ]
          },
          "occurredAt": {
            "type": "string",
            "format": "date-time",
            "description": "按來源訂單日期及規則推算的模擬節點時間，非真實交付時間"
          },
          "recordedAt": {
            "type": "string",
            "format": "date-time",
            "description": "本機實際補入模擬紀錄的時間"
          },
          "simulation": {
            "const": true
          },
          "source": {
            "const": "browser_delivery_simulation"
          }
        }
      },
      "DeliverySimulation": {
        "type": "object",
        "required": [
          "simulation",
          "actualShipmentCreated",
          "trackingNumber",
          "ruleVersion",
          "sourceOrderAt",
          "events"
        ],
        "properties": {
          "simulation": {
            "const": true
          },
          "actualShipmentCreated": {
            "const": false
          },
          "trackingNumber": {
            "type": "null"
          },
          "ruleVersion": {
            "type": "string"
          },
          "sourceOrderAt": {
            "type": "string",
            "format": "date-time"
          },
          "destinationRevision": {
            "type": "integer"
          },
          "status": {
            "type": "string"
          },
          "events": {
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/SimulatedDeliveryEvent"
            }
          }
        }
      }
    }
  },
  "x-implementation-status": "not-implemented",
  "x-auth-rules": [
    "來源外部會員 ID 必須先完成驗證綁定；未知會員隔離待處理",
    "僅服務帳號可匯入；會員查詢一律依驗證身分篩選，不能以 query memberId 越權",
    "API 只允許 HTTPS；憑證輪替、限流、稽核、敏感資料遮罩；正式會員登入另行定義，不接受本機示範登入",
    "scope 列表為服務端強制權限要求；HTTP Bearer 格式本身不代表 OAuth 已配置"
  ],
  "x-sync-rules": [
    "來源唯一鍵=(integration,externalOrderId)，不同會員不可重新指派",
    "以 sourceVersion 單調更新；舊版本不覆寫，相同版本內容不同回 409",
    "paid 不等同 completed；cancelled/refunded 停止新配對並使舊配對失效",
    "初次歷史同步、增量同步、重試及會員映射需依 qi-shoppy 文件確認；未確認的來源狀態隔離待處理",
    "正式金額重配需重新確認，不可覆寫已確認商品與稽核歷史"
  ],
  "x-transaction-rules": [
    "金額以 TWD 分計算；配對商品單價×數量總和須等於訂單配對金額",
    "商品單價、來源、規格、數量、目錄版本均快照保存；不修改價格湊總額",
    "搜尋上限與無解分開；確認方案不保證庫存，不建立完成交易",
    "正式訂單只用已授權供貨且可售庫存；確認時重新檢查價格及原子保留庫存，超時釋放",
    "completed 需要依序驗證付款、下單、交付、買家確認證據；原始來源狀態另存，不互相替代",
    "API 文件不宣稱現有靜態網站具備服務端驗證或跨裝置資料庫"
  ]
}