{
  "openapi": "3.1.0",
  "info": {
    "title": "toko Storefront API",
    "version": "v1",
    "description": "toko 前台 API。租戶後端以前台金鑰讀取自建官網要用的公開資料（站台、行程、出團、日誌）。回應一律 { ok, data } / { ok, error } 外殼。自路由樹與 DTO 生成。"
  },
  "servers": [
    {
      "url": "https://{transactionDomain}/api/storefront/v1",
      "variables": {
        "transactionDomain": {
          "default": "shop.example.com",
          "description": "交易鏈網域（平台供應結帳與會員頁的租戶子網域）"
        }
      }
    }
  ],
  "security": [
    {
      "storefrontKey": []
    }
  ],
  "components": {
    "securitySchemes": {
      "storefrontKey": {
        "type": "http",
        "scheme": "bearer",
        "description": "前台金鑰（`toko_sfk_` 開頭），在後台「設定 → 開發者」建立"
      }
    }
  },
  "paths": {
    "/banners": {
      "get": {
        "operationId": "get_banners",
        "tags": [
          "banners"
        ],
        "summary": "首頁輪播，依後台排序，最多 5 張",
        "description": "`GET /api/storefront/v1/banners` —— 首頁輪播，依後台排序，最多 5 張（ADR 0054）。\n不分頁。圖片是絕對網址；連結是站內路徑或 http(s) 網址，沒有連結為 null。",
        "responses": {
          "200": {
            "description": "成功（{ ok: true, data }）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "imageUrl": {
                                "type": "string",
                                "description": "圖片的絕對網址。"
                              },
                              "alt": {
                                "type": "string",
                                "description": "圖片替代文字。"
                              },
                              "linkUrl": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "點擊後的連結：站內路徑或 http(s) 網址；沒有連結為 null。站內路徑原樣輸出， 相對於顯示輪播的官網，不是交易鏈網域。"
                              }
                            },
                            "required": [
                              "imageUrl",
                              "alt",
                              "linkUrl"
                            ]
                          }
                        }
                      },
                      "required": [
                        "items"
                      ]
                    }
                  }
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-cache"
                }
              },
              "Vary": {
                "schema": {
                  "type": "string",
                  "const": "Authorization, Toko-Version"
                }
              }
            }
          },
          "429": {
            "description": "超過限速（rate_limited）。`Retry-After` 是建議等待的秒數。",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "失敗（{ ok: false, error }；錯誤碼見文件）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "X-Toko-Buyer-IP",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "客人的 IP。租戶後端必須以自己驗證過的客人連線位址覆寫，不得轉送客人送來的同名 header。只用來分配「金鑰＋客人 IP」層的限速額度。"
          }
        ]
      }
    },
    "/categories": {
      "get": {
        "operationId": "get_categories",
        "tags": [
          "categories"
        ],
        "summary": "首頁行程分類，依後台排序，最多 8 個",
        "description": "`GET /api/storefront/v1/categories` —— 首頁行程分類，依後台排序，最多 8 個（ADR 0054）。\n不分頁。每個分類對應一個行程標籤；圖片是絕對網址，沒有圖片為 null。",
        "responses": {
          "200": {
            "description": "成功（{ ok: true, data }）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string",
                                "description": "分類名稱。"
                              },
                              "tag": {
                                "type": "string",
                                "description": "分類對應的行程標籤，與 `/trips` 回傳的 `tags` 其中一個完全相同。"
                              },
                              "imageUrl": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "分類圖片的絕對網址；沒有圖片為 null。"
                              }
                            },
                            "required": [
                              "name",
                              "tag",
                              "imageUrl"
                            ]
                          }
                        }
                      },
                      "required": [
                        "items"
                      ]
                    }
                  }
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-cache"
                }
              },
              "Vary": {
                "schema": {
                  "type": "string",
                  "const": "Authorization, Toko-Version"
                }
              }
            }
          },
          "429": {
            "description": "超過限速（rate_limited）。`Retry-After` 是建議等待的秒數。",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "失敗（{ ok: false, error }；錯誤碼見文件）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "X-Toko-Buyer-IP",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "客人的 IP。租戶後端必須以自己驗證過的客人連線位址覆寫，不得轉送客人送來的同名 header。只用來分配「金鑰＋客人 IP」層的限速額度。"
          }
        ]
      }
    },
    "/departures": {
      "get": {
        "operationId": "get_departures",
        "tags": [
          "departures"
        ],
        "summary": "所有行程近期出團的價格、名額與報名狀態",
        "description": "`GET /api/storefront/v1/departures` —— 所有行程近期出團的價格、名額與報名狀態（ADR 0054）。\n一次呼叫列出跨行程的出團，給首頁「最後名額」這類清單用。名額會變，邊緣只保留 1 秒（ADR 0086）。",
        "parameters": [
          {
            "name": "days",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 366,
              "default": 60,
              "description": "min 1）"
            }
          },
          {
            "name": "X-Toko-Buyer-IP",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "客人的 IP。租戶後端必須以自己驗證過的客人連線位址覆寫，不得轉送客人送來的同名 header。只用來分配「金鑰＋客人 IP」層的限速額度。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功（{ ok: true, data }）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "departures": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "tripSlug": {
                                "type": "string",
                                "description": "所屬行程的 slug；以它呼叫 `trips/{slug}`。"
                              },
                              "minGroupSize": {
                                "type": [
                                  "number",
                                  "null"
                                ],
                                "description": "所屬行程的最低成團人數；未設定為 null。還差幾位成團，讀 `availability.seatsToMinGroupSize`。"
                              },
                              "id": {
                                "type": "string",
                                "description": "出團 id（`dep_` 前綴）。"
                              },
                              "departureDate": {
                                "type": "string",
                                "description": "出發日（`YYYY-MM-DD`）。"
                              },
                              "returnDate": {
                                "type": "string",
                                "description": "回程日（`YYYY-MM-DD`）。"
                              },
                              "priceTwd": {
                                "type": "number",
                                "description": "每人直客價（TWD）。與結帳計價同一個函式，促銷中的出團是促銷價。"
                              },
                              "capacity": {
                                "type": "number",
                                "description": "名額上限（人數）。"
                              },
                              "remainingSeats": {
                                "type": "number",
                                "description": "剩餘名額（人數），不小於 0。"
                              },
                              "bookingState": {
                                "type": "string",
                                "enum": [
                                  "lottery",
                                  "open",
                                  "soldout",
                                  "waitlist"
                                ]
                              },
                              "availability": {
                                "type": "object",
                                "properties": {
                                  "status": {
                                    "type": "string",
                                    "enum": [
                                      "closed",
                                      "lottery",
                                      "lottery_full",
                                      "low",
                                      "open",
                                      "soldout",
                                      "waitlist"
                                    ],
                                    "description": "可報名度：`open` 有名額；`low` 有名額但快額滿（剩 1 或 2 位）；`soldout` 額滿且不收候補； `waitlist` 額滿但收候補；`lottery` 抽籤制、有名額；`lottery_full` 抽籤制、額滿； `closed` 不開放報名。之後可能新增值，不認得的值請當成不可報名。"
                                  },
                                  "remainingSeats": {
                                    "type": "number",
                                    "description": "剩餘名額（人數），不小於 0。"
                                  },
                                  "maxPartySize": {
                                    "type": "number",
                                    "description": "一張單最多可報幾位。額滿收候補時是名額上限；不可報名時是 0。"
                                  },
                                  "seatsToMinGroupSize": {
                                    "type": [
                                      "number",
                                      "null"
                                    ],
                                    "description": "還差幾位達到行程的最低成團人數：0 是已成團；行程未設定最低成團人數為 null。"
                                  }
                                },
                                "required": [
                                  "status",
                                  "remainingSeats",
                                  "maxPartySize",
                                  "seatsToMinGroupSize"
                                ],
                                "description": "公開可報名度：狀態、剩餘名額、一張單的人數上限、成團差額。與平台的行程頁同一個判準。"
                              },
                              "bookingUrl": {
                                "type": "string",
                                "description": "報名網址：`https://<交易鏈網域>/checkout?departure_id=<出團 id>`，直接進結帳流程第一步。"
                              },
                              "lotteryLeadDays": {
                                "type": [
                                  "number",
                                  "null"
                                ],
                                "description": "抽籤日在出發日前幾天（後台的「抽籤前幾天」）。梯次有設定用梯次的值，否則用行程的值； 都沒設定為 null。抽籤時程表有這一天時，實際抽籤日以時程表為準。"
                              },
                              "deposit": {
                                "anyOf": [
                                  {
                                    "type": "object",
                                    "properties": {
                                      "basis": {
                                        "type": "string",
                                        "enum": [
                                          "per_order",
                                          "per_person"
                                        ],
                                        "description": "計算單位：`per_person` 每位旅客一份訂金；`per_order` 每張訂單一筆，不看人數。 比例訂金一律是 `per_person`。"
                                      },
                                      "amountTwd": {
                                        "type": "number",
                                        "description": "一位旅客報名時的訂金（TWD）。`per_person` 的固定金額訂金是這個金額乘人數； 比例訂金按結帳的總額取整，不要自己乘。"
                                      },
                                      "percent": {
                                        "type": [
                                          "number",
                                          "null"
                                        ],
                                        "description": "比例訂金的百分比（1–100）；固定金額為 null。比例訂金以折扣後的總額計算。"
                                      },
                                      "required": {
                                        "type": "boolean",
                                        "description": "true：租戶只收訂金，結帳不提供付全額。false：客人可選付全額或付訂金。"
                                      },
                                      "balanceDue": {
                                        "oneOf": [
                                          {
                                            "type": "object",
                                            "properties": {
                                              "kind": {
                                                "type": "string",
                                                "enum": [
                                                  "before_date"
                                                ]
                                              },
                                              "date": {
                                                "type": "string"
                                              }
                                            },
                                            "required": [
                                              "kind",
                                              "date"
                                            ]
                                          },
                                          {
                                            "type": "object",
                                            "properties": {
                                              "kind": {
                                                "type": "string",
                                                "enum": [
                                                  "after_lottery_win"
                                                ]
                                              },
                                              "days": {
                                                "type": "number"
                                              }
                                            },
                                            "required": [
                                              "kind",
                                              "days"
                                            ]
                                          }
                                        ],
                                        "description": "尾款期限：`before_date` 是不抽籤的出團，於 `date`（`YYYY-MM-DD`）前繳； `after_lottery_win` 是抽籤出團，中籤後 `days` 天內繳。之後可能新增 `kind`。"
                                      }
                                    },
                                    "required": [
                                      "basis",
                                      "amountTwd",
                                      "percent",
                                      "required",
                                      "balanceDue"
                                    ]
                                  },
                                  {
                                    "type": "null"
                                  }
                                ],
                                "description": "訂金。沒設訂金、或一位旅客的訂金就是全額時為 null（只能付全額）。"
                              }
                            },
                            "required": [
                              "tripSlug",
                              "minGroupSize",
                              "id",
                              "departureDate",
                              "returnDate",
                              "priceTwd",
                              "capacity",
                              "remainingSeats",
                              "bookingState",
                              "availability",
                              "bookingUrl",
                              "lotteryLeadDays",
                              "deposit"
                            ]
                          }
                        }
                      },
                      "required": [
                        "departures"
                      ]
                    }
                  }
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-cache"
                }
              },
              "Vary": {
                "schema": {
                  "type": "string",
                  "const": "Authorization, Toko-Version"
                }
              }
            }
          },
          "429": {
            "description": "超過限速（rate_limited）。`Retry-After` 是建議等待的秒數。",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "失敗（{ ok: false, error }；錯誤碼見文件）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "x-module": "tour"
      }
    },
    "/faqs": {
      "get": {
        "operationId": "get_faqs",
        "tags": [
          "faqs"
        ],
        "summary": "首頁常見問題，依後台排序，最多 20 題",
        "description": "`GET /api/storefront/v1/faqs` —— 首頁常見問題，依後台排序，最多 20 題（ADR 0054）。\n不分頁。答案是純文字，可含換行。",
        "responses": {
          "200": {
            "description": "成功（{ ok: true, data }）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "question": {
                                "type": "string",
                                "description": "問題。"
                              },
                              "answer": {
                                "type": "string",
                                "description": "答案，純文字，可含換行。"
                              }
                            },
                            "required": [
                              "question",
                              "answer"
                            ]
                          }
                        }
                      },
                      "required": [
                        "items"
                      ]
                    }
                  }
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-cache"
                }
              },
              "Vary": {
                "schema": {
                  "type": "string",
                  "const": "Authorization, Toko-Version"
                }
              }
            }
          },
          "429": {
            "description": "超過限速（rate_limited）。`Retry-After` 是建議等待的秒數。",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "失敗（{ ok: false, error }；錯誤碼見文件）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "X-Toko-Buyer-IP",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "客人的 IP。租戶後端必須以自己驗證過的客人連線位址覆寫，不得轉送客人送來的同名 header。只用來分配「金鑰＋客人 IP」層的限速額度。"
          }
        ]
      }
    },
    "/journal": {
      "get": {
        "operationId": "get_journal",
        "tags": [
          "journal"
        ],
        "summary": "已發布日誌的卡片，cursor 分頁",
        "description": "`GET /api/storefront/v1/journal` —— 已發布日誌的卡片，cursor 分頁（ADR 0054）。\n分頁契約同 `trips`。排序固定為發布時間新到舊。`limit` 超過上限或 `cursor` 解不開\n回 422，不靜默截斷。",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20,
              "description": "min 1）"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 128,
              "description": "上一頁回應的 nextCursor；第一頁不帶（max 128 · min 1）"
            }
          },
          {
            "name": "X-Toko-Buyer-IP",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "客人的 IP。租戶後端必須以自己驗證過的客人連線位址覆寫，不得轉送客人送來的同名 header。只用來分配「金鑰＋客人 IP」層的限速額度。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功（{ ok: true, data }）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "slug": {
                                "type": "string",
                                "description": "日誌網址 slug；以它呼叫 `journal/{slug}`。"
                              },
                              "title": {
                                "type": "string",
                                "description": "標題。"
                              },
                              "excerpt": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "摘要；未設定為 null。"
                              },
                              "coverImageUrl": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "封面圖的絕對網址；未設定為 null。"
                              },
                              "publishedAt": {
                                "type": "string",
                                "description": "發布時間（ISO 8601，UTC）。"
                              },
                              "authorName": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "作者（嚮導）名稱；未設定為 null。"
                              },
                              "updatedAt": {
                                "type": "string",
                                "description": "Last edit time (ISO 8601, UTC). Use it for `dateModified` and sitemap `lastmod`."
                              }
                            },
                            "required": [
                              "slug",
                              "title",
                              "excerpt",
                              "coverImageUrl",
                              "publishedAt",
                              "authorName",
                              "updatedAt"
                            ]
                          }
                        },
                        "nextCursor": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "items",
                        "nextCursor"
                      ]
                    }
                  }
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-cache"
                }
              },
              "Vary": {
                "schema": {
                  "type": "string",
                  "const": "Authorization, Toko-Version"
                }
              }
            }
          },
          "429": {
            "description": "超過限速（rate_limited）。`Retry-After` 是建議等待的秒數。",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "失敗（{ ok: false, error }；錯誤碼見文件）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/journal/{slug}": {
      "get": {
        "operationId": "get_journal_slug_",
        "tags": [
          "journal"
        ],
        "summary": "一篇日誌的完整內容",
        "description": "`GET /api/storefront/v1/journal/{slug}` —— 一篇日誌的完整內容（ADR 0054）。正文沿用\n行程內容的 MDX → HTML 渲染與 sanitize（prose 模式，不展開行程元件）。",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "日誌 slug（路徑參數）（min 1）"
            }
          },
          {
            "name": "X-Toko-Buyer-IP",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "客人的 IP。租戶後端必須以自己驗證過的客人連線位址覆寫，不得轉送客人送來的同名 header。只用來分配「金鑰＋客人 IP」層的限速額度。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功（{ ok: true, data }）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "bodyHtml": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "title": {
                          "type": "string",
                          "description": "標題。"
                        },
                        "slug": {
                          "type": "string",
                          "description": "日誌網址 slug；以它呼叫 `journal/{slug}`。"
                        },
                        "excerpt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "摘要；未設定為 null。"
                        },
                        "coverImageUrl": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "封面圖的絕對網址；未設定為 null。"
                        },
                        "seoTitle": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "SEO title override; null uses the post title."
                        },
                        "seoDescription": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "SEO description override; null uses the excerpt."
                        },
                        "ogImageUrl": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Absolute sharing image URL; null uses the cover image."
                        },
                        "updatedAt": {
                          "type": "string",
                          "description": "Last edit time (ISO 8601, UTC). Use it for `dateModified` and sitemap `lastmod`."
                        },
                        "publishedAt": {
                          "type": "string",
                          "description": "發布時間（ISO 8601，UTC）。"
                        },
                        "authorName": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "作者（嚮導）名稱；未設定為 null。"
                        }
                      },
                      "required": [
                        "bodyHtml",
                        "title",
                        "slug",
                        "excerpt",
                        "coverImageUrl",
                        "seoTitle",
                        "seoDescription",
                        "ogImageUrl",
                        "updatedAt",
                        "publishedAt",
                        "authorName"
                      ]
                    }
                  }
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-cache"
                }
              },
              "Vary": {
                "schema": {
                  "type": "string",
                  "const": "Authorization, Toko-Version"
                }
              }
            }
          },
          "429": {
            "description": "超過限速（rate_limited）。`Retry-After` 是建議等待的秒數。",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "失敗（{ ok: false, error }；錯誤碼見文件）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/site": {
      "get": {
        "operationId": "get_site",
        "tags": [
          "site"
        ],
        "summary": "站台資訊：品牌名、首頁標題、logo、聯絡方式、交易鏈網址",
        "description": "`GET /api/storefront/v1/site` —— 站台資訊：品牌名、首頁標題、logo、聯絡方式、交易鏈網址、\n會員中心網址（ADR 0054）。租戶官網以一次呼叫組出頁首與頁尾。",
        "responses": {
          "200": {
            "description": "成功（{ ok: true, data }）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "name": {
                          "type": "string",
                          "description": "品牌名（`tenant_settings.company_name`）。"
                        },
                        "homeTitle": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "首頁標題整句（含品牌段，後台「網站 → SEO → 首頁標題」）；未設定為 null，由前台自訂預設。"
                        },
                        "ogImageUrl": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "預設分享圖的絕對網址（後台「網站 → SEO → 預設分享圖」）；未設定為 null，由前台自訂預設。"
                        },
                        "logoUrl": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Logo 的絕對網址；未設定為 null。"
                        },
                        "phone": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "聯絡電話；未設定為 null。"
                        },
                        "email": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "對外聯絡信箱（`tenant_settings.company_email`）；未設定為 null，不退回系統信的回覆信箱。"
                        },
                        "lineOfficialUrl": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "LINE 官方帳號加好友網址；未設定為 null。"
                        },
                        "facebookUrl": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Facebook 粉專網址；未設定為 null。"
                        },
                        "instagramUrl": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Instagram 網址；未設定為 null。"
                        },
                        "youtubeUrl": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "YouTube 頻道網址；未設定為 null。"
                        },
                        "shopUrl": {
                          "type": "string",
                          "description": "交易鏈網址（平台供應的結帳、會員、訂單頁所在的 origin）。"
                        },
                        "memberUrl": {
                          "type": "string",
                          "description": "會員中心網址。"
                        }
                      },
                      "required": [
                        "name",
                        "homeTitle",
                        "ogImageUrl",
                        "logoUrl",
                        "phone",
                        "email",
                        "lineOfficialUrl",
                        "facebookUrl",
                        "instagramUrl",
                        "youtubeUrl",
                        "shopUrl",
                        "memberUrl"
                      ]
                    }
                  }
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-cache"
                }
              },
              "Vary": {
                "schema": {
                  "type": "string",
                  "const": "Authorization, Toko-Version"
                }
              }
            }
          },
          "429": {
            "description": "超過限速（rate_limited）。`Retry-After` 是建議等待的秒數。",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "失敗（{ ok: false, error }；錯誤碼見文件）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "parameters": [
          {
            "name": "X-Toko-Buyer-IP",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "客人的 IP。租戶後端必須以自己驗證過的客人連線位址覆寫，不得轉送客人送來的同名 header。只用來分配「金鑰＋客人 IP」層的限速額度。"
          }
        ]
      }
    },
    "/trips": {
      "get": {
        "operationId": "get_trips",
        "tags": [
          "trips"
        ],
        "summary": "上架行程的卡片，cursor 分頁",
        "description": "`GET /api/storefront/v1/trips` —— 上架行程的卡片，cursor 分頁（ADR 0054）。\n排序固定為建立時間新到舊。`limit` 超過上限回 422，不靜默截斷。",
        "parameters": [
          {
            "name": "limit",
            "in": "query",
            "required": false,
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 50,
              "default": 20,
              "description": "min 1）"
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "required": false,
            "schema": {
              "type": "string",
              "minLength": 1,
              "maxLength": 64,
              "description": "上一頁回應的 nextCursor；第一頁不帶（max 64 · min 1）"
            }
          },
          {
            "name": "X-Toko-Buyer-IP",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "客人的 IP。租戶後端必須以自己驗證過的客人連線位址覆寫，不得轉送客人送來的同名 header。只用來分配「金鑰＋客人 IP」層的限速額度。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功（{ ok: true, data }）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "items": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "tags": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                },
                                "description": "Free-form trip tags. The website defines its own filters."
                              },
                              "difficultyLevel": {
                                "type": [
                                  "number",
                                  "null"
                                ],
                                "description": "Public difficulty, from 1 (easy) to 5 (challenging). Null means unrated."
                              },
                              "slug": {
                                "type": "string",
                                "description": "行程網址 slug；以它呼叫 `trips/{slug}`。"
                              },
                              "title": {
                                "type": "string",
                                "description": "行程標題。"
                              },
                              "summary": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "一句話摘要；未設定為 null。"
                              },
                              "destination": {
                                "type": "string",
                                "description": "目的地名稱。"
                              },
                              "isOverseas": {
                                "type": "boolean",
                                "description": "True when the trip goes outside Taiwan (the admin \"海外\" trip flag)."
                              },
                              "isClimbing": {
                                "type": "boolean",
                                "description": "登山行程（後台的「登山」行程旗標）。租戶沒開登山模組時一律 false。"
                              },
                              "durationDays": {
                                "type": "number",
                                "description": "天數。"
                              },
                              "hasPreTripNight": {
                                "type": "boolean",
                                "description": "True when the trip starts with a gathering night before departure (Day 0). The night adds one night to the trip length."
                              },
                              "priceFromTwd": {
                                "type": "number",
                                "description": "「NT$ X 起」的起價（TWD 整數）。"
                              },
                              "depositFromTwd": {
                                "type": [
                                  "number",
                                  "null"
                                ],
                                "description": "「訂金 NT$ X 起」：可報名出團中，一位旅客的最低訂金（TWD）。沒有訂金、訂金就是全額， 或訂金是每張訂單一筆時為 null。各出團的訂金細節讀 `trips/{slug}/departures` 的 `deposit`。"
                              },
                              "coverImageUrl": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "封面圖的絕對網址；未設定為 null。"
                              },
                              "nextDepartureDate": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "最近一個前台可報名出團的出發日（`YYYY-MM-DD`）；沒有為 null。"
                              },
                              "updatedAt": {
                                "type": "string",
                                "description": "Last edit time of the trip (ISO 8601, UTC). Use it for the sitemap `lastmod`. Gallery image changes move it forward. Departure seats, status, and prices do not change it."
                              }
                            },
                            "required": [
                              "tags",
                              "difficultyLevel",
                              "slug",
                              "title",
                              "summary",
                              "destination",
                              "isOverseas",
                              "isClimbing",
                              "durationDays",
                              "hasPreTripNight",
                              "priceFromTwd",
                              "depositFromTwd",
                              "coverImageUrl",
                              "nextDepartureDate",
                              "updatedAt"
                            ]
                          }
                        },
                        "nextCursor": {
                          "type": [
                            "string",
                            "null"
                          ]
                        }
                      },
                      "required": [
                        "items",
                        "nextCursor"
                      ]
                    }
                  }
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-cache"
                }
              },
              "Vary": {
                "schema": {
                  "type": "string",
                  "const": "Authorization, Toko-Version"
                }
              }
            }
          },
          "429": {
            "description": "超過限速（rate_limited）。`Retry-After` 是建議等待的秒數。",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "失敗（{ ok: false, error }；錯誤碼見文件）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "x-module": "tour"
      }
    },
    "/trips/{slug}": {
      "get": {
        "operationId": "get_trips_slug_",
        "tags": [
          "trips"
        ],
        "summary": "行程內容",
        "description": "`GET /api/storefront/v1/trips/{slug}` —— 行程內容（ADR 0054）。正文是平台渲染並\nsanitize 過的 HTML；費用、退改費階梯、住宿另外輸出成結構化欄位。出團不在這裡：\n名額會變，走 `trips/{slug}/departures`。",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "行程 slug（路徑參數）（min 1）"
            }
          },
          {
            "name": "X-Toko-Buyer-IP",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "客人的 IP。租戶後端必須以自己驗證過的客人連線位址覆寫，不得轉送客人送來的同名 header。只用來分配「金鑰＋客人 IP」層的限速額度。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功（{ ok: true, data }）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "bodyHtml": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "lodging": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "name": {
                                "type": "string"
                              },
                              "location": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "description": {
                                "type": [
                                  "string",
                                  "null"
                                ]
                              },
                              "nights": {
                                "type": "number",
                                "description": "本行程在此據點住幾晚。"
                              },
                              "facilities": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "key": {
                                      "type": "string"
                                    },
                                    "label": {
                                      "type": "string"
                                    }
                                  },
                                  "required": [
                                    "key",
                                    "label"
                                  ]
                                }
                              },
                              "imageUrls": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                },
                                "description": "據點相簿的絕對網址；沒有相簿時退回封面圖。"
                              },
                              "roomTypes": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "properties": {
                                    "name": {
                                      "type": "string"
                                    },
                                    "description": {
                                      "type": [
                                        "string",
                                        "null"
                                      ]
                                    },
                                    "capacityPerUnit": {
                                      "type": "number",
                                      "description": "每間最多人數。"
                                    },
                                    "beds": {
                                      "type": "array",
                                      "items": {
                                        "type": "object",
                                        "properties": {
                                          "label": {
                                            "type": "string"
                                          },
                                          "count": {
                                            "type": "number"
                                          }
                                        },
                                        "required": [
                                          "label",
                                          "count"
                                        ]
                                      },
                                      "description": "床型與床數。"
                                    },
                                    "floorSizeSqm": {
                                      "type": [
                                        "number",
                                        "null"
                                      ],
                                      "description": "坪數；未設定為 null。"
                                    },
                                    "facilities": {
                                      "type": "array",
                                      "items": {
                                        "type": "object",
                                        "properties": {
                                          "key": {
                                            "type": "string"
                                          },
                                          "label": {
                                            "type": "string"
                                          }
                                        },
                                        "required": [
                                          "key",
                                          "label"
                                        ]
                                      }
                                    },
                                    "imageUrls": {
                                      "type": "array",
                                      "items": {
                                        "type": "string"
                                      },
                                      "description": "房型照片的絕對網址。"
                                    }
                                  },
                                  "required": [
                                    "name",
                                    "description",
                                    "capacityPerUnit",
                                    "beds",
                                    "floorSizeSqm",
                                    "facilities",
                                    "imageUrls"
                                  ]
                                }
                              }
                            },
                            "required": [
                              "name",
                              "location",
                              "description",
                              "nights",
                              "facilities",
                              "imageUrls",
                              "roomTypes"
                            ]
                          },
                          "description": "住宿配套；沒有配套或住宿模組未開通時為空陣列。"
                        },
                        "title": {
                          "type": "string"
                        },
                        "slug": {
                          "type": "string"
                        },
                        "coverImageUrl": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "封面圖的絕對網址；未設定為 null。"
                        },
                        "seoTitle": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "SEO title override; null uses the trip title."
                        },
                        "seoDescription": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "SEO description override; null uses the summary."
                        },
                        "ogImageUrl": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Absolute sharing image URL; null uses the cover image."
                        },
                        "isOverseas": {
                          "type": "boolean",
                          "description": "True when the trip goes outside Taiwan (the admin \"海外\" trip flag)."
                        },
                        "updatedAt": {
                          "type": "string",
                          "description": "Last edit time of the trip (ISO 8601, UTC). Use it for `dateModified` and the sitemap `lastmod`. Gallery image changes move it forward. Departure seats, status, and prices do not change it."
                        },
                        "tags": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Free-form trip tags. The website defines its own filters."
                        },
                        "summary": {
                          "type": [
                            "string",
                            "null"
                          ]
                        },
                        "destination": {
                          "type": "string"
                        },
                        "durationDays": {
                          "type": "number"
                        },
                        "difficultyLevel": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "description": "Public difficulty, from 1 (easy) to 5 (challenging). Null means unrated."
                        },
                        "priceFromTwd": {
                          "type": "number"
                        },
                        "notices": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "注意事項。"
                        },
                        "suggestedFlights": {
                          "anyOf": [
                            {
                              "type": "object",
                              "properties": {
                                "updated": {
                                  "type": "string",
                                  "description": "最後核對班表的年月 YYYY-MM。"
                                },
                                "ticket": {
                                  "type": "string",
                                  "enum": [
                                    "不含",
                                    "可代訂",
                                    "含"
                                  ],
                                  "description": "機票：不含／可代訂（不含但可代訂）／含。"
                                },
                                "plans": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "properties": {
                                      "name": {
                                        "type": "string"
                                      },
                                      "primary": {
                                        "type": "boolean",
                                        "description": "推薦方案；陣列第一個一定是推薦方案。"
                                      },
                                      "mode": {
                                        "type": "string",
                                        "enum": [
                                          "flight",
                                          "station"
                                        ],
                                        "description": "flight＝搭飛機到機場集合（看 `segments`）；station＝自行前往車站集合（看 `airports`、`route`）。"
                                      },
                                      "meetDay": {
                                        "type": "number",
                                        "description": "集合在行程第幾天。"
                                      },
                                      "meetTime": {
                                        "type": [
                                          "string",
                                          "null"
                                        ],
                                        "description": "集合時間 HH:MM；null＝抵達後。"
                                      },
                                      "meetPlace": {
                                        "type": "string"
                                      },
                                      "segments": {
                                        "type": "array",
                                        "items": {
                                          "type": "object",
                                          "properties": {
                                            "dir": {
                                              "type": "string",
                                              "enum": [
                                                "dom",
                                                "out",
                                                "ret"
                                              ],
                                              "description": "out＝去程、ret＝回程、dom＝當地國內線。同一方向依陣列順序是第 1、2、3 段。"
                                            },
                                            "flight": {
                                              "type": "string",
                                              "description": "完整班號，例如 `CI118`。"
                                            },
                                            "airline": {
                                              "type": "string",
                                              "description": "航空公司名稱，例如「中華航空」。"
                                            },
                                            "from": {
                                              "type": "string",
                                              "description": "出發機場 IATA 三碼。"
                                            },
                                            "fromName": {
                                              "type": "string",
                                              "description": "出發機場短名，例如「桃園」。"
                                            },
                                            "to": {
                                              "type": "string",
                                              "description": "抵達機場 IATA 三碼。"
                                            },
                                            "toName": {
                                              "type": "string",
                                              "description": "抵達機場短名。"
                                            },
                                            "depDay": {
                                              "type": "number"
                                            },
                                            "dep": {
                                              "type": "string",
                                              "description": "起飛時間 HH:MM。"
                                            },
                                            "arrDay": {
                                              "type": "number"
                                            },
                                            "arr": {
                                              "type": "string",
                                              "description": "抵達時間 HH:MM。"
                                            }
                                          },
                                          "required": [
                                            "dir",
                                            "flight",
                                            "airline",
                                            "from",
                                            "fromName",
                                            "to",
                                            "toName",
                                            "depDay",
                                            "dep",
                                            "arrDay",
                                            "arr"
                                          ]
                                        },
                                        "description": "航班；station 方案為空陣列。"
                                      },
                                      "airports": {
                                        "type": "array",
                                        "items": {
                                          "type": "object",
                                          "properties": {
                                            "code": {
                                              "type": "string",
                                              "description": "IATA 三碼。"
                                            },
                                            "name": {
                                              "type": "string",
                                              "description": "短名，例如「名古屋中部」。"
                                            }
                                          },
                                          "required": [
                                            "code",
                                            "name"
                                          ]
                                        },
                                        "description": "建議抵達機場，第一個最推薦；flight 方案為空陣列。"
                                      },
                                      "route": {
                                        "type": [
                                          "string",
                                          "null"
                                        ],
                                        "description": "接駁路線；flight 方案為 null。"
                                      },
                                      "duration": {
                                        "type": [
                                          "string",
                                          "null"
                                        ],
                                        "description": "接駁所需時間與方式；flight 方案為 null。"
                                      },
                                      "arriveDayBefore": {
                                        "type": "boolean",
                                        "description": "建議前一天抵達。"
                                      }
                                    },
                                    "required": [
                                      "name",
                                      "primary",
                                      "mode",
                                      "meetDay",
                                      "meetTime",
                                      "meetPlace",
                                      "segments",
                                      "airports",
                                      "route",
                                      "duration",
                                      "arriveDayBefore"
                                    ]
                                  },
                                  "description": "推薦方案在第一個。"
                                }
                              },
                              "required": [
                                "updated",
                                "ticket",
                                "plans"
                              ]
                            },
                            {
                              "type": "null"
                            }
                          ],
                          "description": "建議航班；沒填或資料有錯時為 null。結構見 `StorefrontSuggestedFlightsDto`： `plans[]`（推薦方案在第一個）→ `segments[]`（搭飛機）或 `airports[]`／`route`（車站集合）。"
                        },
                        "cancellationFeeTiers": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "daysBefore": {
                                "type": "number",
                                "description": "距出發日 ≥ 此天數時適用本列。0 是出發當天。"
                              },
                              "feePercent": {
                                "type": [
                                  "number",
                                  "null"
                                ],
                                "description": "扣款百分比（0–100）；定額扣款的列為 null。"
                              },
                              "feeFixedTwd": {
                                "type": [
                                  "number",
                                  "null"
                                ],
                                "description": "每人定額扣款（TWD 整數）；百分比扣款的列為 null。"
                              }
                            },
                            "required": [
                              "daysBefore",
                              "feePercent",
                              "feeFixedTwd"
                            ]
                          },
                          "description": "生效的退改費階梯（行程覆寫，否則租戶預設），依 `daysBefore` 降序。"
                        },
                        "isClimbing": {
                          "type": "boolean",
                          "description": "登山行程（後台的「登山」行程旗標）。租戶沒開登山模組時一律 false。"
                        },
                        "isLinkOnly": {
                          "type": "boolean",
                          "description": "True when the trip is link-only: the trip list leaves it out, and only people with the trip URL can book it. Mark the trip page noindex and leave out structured data (JSON-LD)."
                        },
                        "hasPreTripNight": {
                          "type": "boolean",
                          "description": "True when the trip starts with a gathering night before departure (Day 0). The night adds one night to the trip length."
                        },
                        "foreignTravelersOnly": {
                          "type": "boolean",
                          "description": "True when the trip takes foreign travelers only (the admin \"限外籍旅客\" trip flag). Checkout rejects a traveler whose nationality is blank or Taiwan. Show a notice on the trip page."
                        },
                        "images": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "url": {
                                "type": "string",
                                "description": "圖片的絕對網址。"
                              },
                              "caption": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "圖說；未設定為 null。"
                              }
                            },
                            "required": [
                              "url",
                              "caption"
                            ]
                          },
                          "description": "行程相簿（依顯示順序）。"
                        },
                        "feeIncludes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "費用包含。"
                        },
                        "feeExcludes": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "費用不包含。"
                        }
                      },
                      "required": [
                        "bodyHtml",
                        "lodging",
                        "title",
                        "slug",
                        "coverImageUrl",
                        "seoTitle",
                        "seoDescription",
                        "ogImageUrl",
                        "isOverseas",
                        "updatedAt",
                        "tags",
                        "summary",
                        "destination",
                        "durationDays",
                        "difficultyLevel",
                        "priceFromTwd",
                        "notices",
                        "suggestedFlights",
                        "cancellationFeeTiers",
                        "isClimbing",
                        "isLinkOnly",
                        "hasPreTripNight",
                        "foreignTravelersOnly",
                        "images",
                        "feeIncludes",
                        "feeExcludes"
                      ]
                    }
                  }
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-cache"
                }
              },
              "Vary": {
                "schema": {
                  "type": "string",
                  "const": "Authorization, Toko-Version"
                }
              }
            }
          },
          "429": {
            "description": "超過限速（rate_limited）。`Retry-After` 是建議等待的秒數。",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "失敗（{ ok: false, error }；錯誤碼見文件）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "x-module": "tour"
      }
    },
    "/trips/{slug}/departures": {
      "get": {
        "operationId": "get_trips_slug_departures",
        "tags": [
          "trips"
        ],
        "summary": "行程的出團、價格、名額與報名狀態",
        "description": "`GET /api/storefront/v1/trips/{slug}/departures` —— 行程的出團、價格、名額與報名狀態\n（ADR 0054）。名額會變，邊緣只保留 1 秒（ADR 0086）。行程內容走另一支端點。",
        "parameters": [
          {
            "name": "slug",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "路徑參數"
            }
          },
          {
            "name": "X-Toko-Buyer-IP",
            "in": "header",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "客人的 IP。租戶後端必須以自己驗證過的客人連線位址覆寫，不得轉送客人送來的同名 header。只用來分配「金鑰＋客人 IP」層的限速額度。"
          }
        ],
        "responses": {
          "200": {
            "description": "成功（{ ok: true, data }）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "data"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        true
                      ]
                    },
                    "data": {
                      "type": "object",
                      "properties": {
                        "departures": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "出團 id（`dep_` 前綴）。"
                              },
                              "departureDate": {
                                "type": "string",
                                "description": "出發日（`YYYY-MM-DD`）。"
                              },
                              "returnDate": {
                                "type": "string",
                                "description": "回程日（`YYYY-MM-DD`）。"
                              },
                              "priceTwd": {
                                "type": "number",
                                "description": "每人直客價（TWD）。與結帳計價同一個函式，促銷中的出團是促銷價。"
                              },
                              "capacity": {
                                "type": "number",
                                "description": "名額上限（人數）。"
                              },
                              "remainingSeats": {
                                "type": "number",
                                "description": "剩餘名額（人數），不小於 0。"
                              },
                              "bookingState": {
                                "type": "string",
                                "enum": [
                                  "lottery",
                                  "open",
                                  "soldout",
                                  "waitlist"
                                ]
                              },
                              "availability": {
                                "type": "object",
                                "properties": {
                                  "status": {
                                    "type": "string",
                                    "enum": [
                                      "closed",
                                      "lottery",
                                      "lottery_full",
                                      "low",
                                      "open",
                                      "soldout",
                                      "waitlist"
                                    ],
                                    "description": "可報名度：`open` 有名額；`low` 有名額但快額滿（剩 1 或 2 位）；`soldout` 額滿且不收候補； `waitlist` 額滿但收候補；`lottery` 抽籤制、有名額；`lottery_full` 抽籤制、額滿； `closed` 不開放報名。之後可能新增值，不認得的值請當成不可報名。"
                                  },
                                  "remainingSeats": {
                                    "type": "number",
                                    "description": "剩餘名額（人數），不小於 0。"
                                  },
                                  "maxPartySize": {
                                    "type": "number",
                                    "description": "一張單最多可報幾位。額滿收候補時是名額上限；不可報名時是 0。"
                                  },
                                  "seatsToMinGroupSize": {
                                    "type": [
                                      "number",
                                      "null"
                                    ],
                                    "description": "還差幾位達到行程的最低成團人數：0 是已成團；行程未設定最低成團人數為 null。"
                                  }
                                },
                                "required": [
                                  "status",
                                  "remainingSeats",
                                  "maxPartySize",
                                  "seatsToMinGroupSize"
                                ],
                                "description": "公開可報名度：狀態、剩餘名額、一張單的人數上限、成團差額。與平台的行程頁同一個判準。"
                              },
                              "bookingUrl": {
                                "type": "string",
                                "description": "報名網址：`https://<交易鏈網域>/checkout?departure_id=<出團 id>`，直接進結帳流程第一步。"
                              },
                              "lotteryLeadDays": {
                                "type": [
                                  "number",
                                  "null"
                                ],
                                "description": "抽籤日在出發日前幾天（後台的「抽籤前幾天」）。梯次有設定用梯次的值，否則用行程的值； 都沒設定為 null。抽籤時程表有這一天時，實際抽籤日以時程表為準。"
                              },
                              "deposit": {
                                "anyOf": [
                                  {
                                    "type": "object",
                                    "properties": {
                                      "basis": {
                                        "type": "string",
                                        "enum": [
                                          "per_order",
                                          "per_person"
                                        ],
                                        "description": "計算單位：`per_person` 每位旅客一份訂金；`per_order` 每張訂單一筆，不看人數。 比例訂金一律是 `per_person`。"
                                      },
                                      "amountTwd": {
                                        "type": "number",
                                        "description": "一位旅客報名時的訂金（TWD）。`per_person` 的固定金額訂金是這個金額乘人數； 比例訂金按結帳的總額取整，不要自己乘。"
                                      },
                                      "percent": {
                                        "type": [
                                          "number",
                                          "null"
                                        ],
                                        "description": "比例訂金的百分比（1–100）；固定金額為 null。比例訂金以折扣後的總額計算。"
                                      },
                                      "required": {
                                        "type": "boolean",
                                        "description": "true：租戶只收訂金，結帳不提供付全額。false：客人可選付全額或付訂金。"
                                      },
                                      "balanceDue": {
                                        "oneOf": [
                                          {
                                            "type": "object",
                                            "properties": {
                                              "kind": {
                                                "type": "string",
                                                "enum": [
                                                  "before_date"
                                                ]
                                              },
                                              "date": {
                                                "type": "string"
                                              }
                                            },
                                            "required": [
                                              "kind",
                                              "date"
                                            ]
                                          },
                                          {
                                            "type": "object",
                                            "properties": {
                                              "kind": {
                                                "type": "string",
                                                "enum": [
                                                  "after_lottery_win"
                                                ]
                                              },
                                              "days": {
                                                "type": "number"
                                              }
                                            },
                                            "required": [
                                              "kind",
                                              "days"
                                            ]
                                          }
                                        ],
                                        "description": "尾款期限：`before_date` 是不抽籤的出團，於 `date`（`YYYY-MM-DD`）前繳； `after_lottery_win` 是抽籤出團，中籤後 `days` 天內繳。之後可能新增 `kind`。"
                                      }
                                    },
                                    "required": [
                                      "basis",
                                      "amountTwd",
                                      "percent",
                                      "required",
                                      "balanceDue"
                                    ]
                                  },
                                  {
                                    "type": "null"
                                  }
                                ],
                                "description": "訂金。沒設訂金、或一位旅客的訂金就是全額時為 null（只能付全額）。"
                              }
                            },
                            "required": [
                              "id",
                              "departureDate",
                              "returnDate",
                              "priceTwd",
                              "capacity",
                              "remainingSeats",
                              "bookingState",
                              "availability",
                              "bookingUrl",
                              "lotteryLeadDays",
                              "deposit"
                            ]
                          }
                        }
                      },
                      "required": [
                        "departures"
                      ]
                    }
                  }
                }
              }
            },
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string",
                  "const": "no-cache"
                }
              },
              "Vary": {
                "schema": {
                  "type": "string",
                  "const": "Authorization, Toko-Version"
                }
              }
            }
          },
          "429": {
            "description": "超過限速（rate_limited）。`Retry-After` 是建議等待的秒數。",
            "headers": {
              "Retry-After": {
                "schema": {
                  "type": "integer",
                  "minimum": 1
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          },
          "default": {
            "description": "失敗（{ ok: false, error }；錯誤碼見文件）",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": [
                    "ok",
                    "error"
                  ],
                  "properties": {
                    "ok": {
                      "type": "boolean",
                      "enum": [
                        false
                      ]
                    },
                    "error": {
                      "type": "object",
                      "required": [
                        "code",
                        "message"
                      ],
                      "properties": {
                        "code": {
                          "type": "string",
                          "enum": [
                            "internal",
                            "module_disabled",
                            "not_found",
                            "rate_limit_unavailable",
                            "rate_limited",
                            "service_unavailable",
                            "transaction_domain_not_configured",
                            "unauthorized",
                            "validation",
                            "version_invalid",
                            "version_required",
                            "version_unsupported"
                          ]
                        },
                        "message": {
                          "type": "string"
                        },
                        "issues": {
                          "type": "array",
                          "items": {},
                          "description": "422 validation 才有"
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "x-module": "tour"
      }
    }
  }
}