变更日志

[3.13.0] - 2026-09-11

新增

• GET /reservations 新增 channel_details：按订单所属渠道归类的渠道专属字段容器。首个字段是 channel_details.airbnb.cancellation_policy_category——Airbnb 订单实际适用的取消政策，原样透传 Airbnb 返回的值（例如 flexible、long_term_flexible、tiered_pricing_non_refundable）。Airbnb 允许客人按单在房源的标准政策与打折的不可退款价之间选择，因此同一房源下的两张订单取值可能不同，这个字段可以把它们区分开。本次发布后首次从 Airbnb 同步的订单一开始就有值；已有的订单在其下一次于 Airbnb 发生变更（例如日期、人数、价格或状态）时补上，这次变更照常通过 reservation_updated webhook 通知，不会为补上该值单独发送 webhook。补上之前该字段为 null；本次发布前就已停止与 Airbnb 同步的订单则一直为 null。airbnb 以外的渠道，channel_details 本身为 null。channel_details 下的取值沿用各渠道自己的定义，不应跨渠道比较。

[3.12.1] - 2026-09-10

修复

• 携程（ctrip）房源调用 POST /listings/prices 改价：此前每次都被携程拒绝（同步任务报「提交变价单失败」），原因是下发到携程的请求里没有价格。现在可以正常生效，price 按客人支付的售价处理——与 Hostex 房价页里的含义一致——扣除携程佣金后得到房东的底价。

变更

• 文档写明了携程（ctrip）房源在两个日历接口上的价格口径不同：POST /listings/calendar 返回的是底价（扣除携程佣金后房东实际收到的金额），POST /listings/prices 接收的是售价。不要用 POST /listings/calendar 读到的值推算携程的相对调价（例如涨 10%）。这一读写差异是既有行为，本次没有改变，只是写进了文档。

[3.12.0] - 2026-08-24

新增

• GET /transactions 与 POST /transactions 新增入参 reservation_code——该笔收支所属的订单；GET /transactions 返回的每条收支也新增 reservation_code 字段。它与 GET /reservations 返回的 reservation_code 是同一个编码，因此收支可以直接与订单关联，不必再做标识转换。未挂在订单上的收支（记在房源或房东名下）该字段为 null。

废弃

• GET /transactions 与 POST /transactions 的入参 stay_code、以及 GET /transactions 响应中的 stay_code，均标记为废弃，请改用 reservation_code。该字段仍然可用，且没有下线计划；入参上两者等价，响应中两者恒为同一个值。同一请求中同时传入两者会返回 400。

变更

• 文档现在明确写出：一笔收支属于整张订单，而不是订单中的某一间房。多房订单只有一个订单编码、却有多张入住单，针对其中任意一张入住单记录的收支，都会记在整张订单上——金额随后按各房间房费比例分摊到每间房，回查时挂的是订单编码，而不是提交时用的那个入住单号。这是既有行为，本次没有改动；错的是文档——此前把该参数描述成可以把收支落到某一间房上。需要注意的是这个归一是静默的：POST /transactions 传入次房的入住单号会返回 201，既不报错也没有任何提示，而建出的这笔收支回报的是订单编码。若要把金额记在某一间具体房源上，请改用 property_id。

[3.11.0] - 2026-08-14

新增

• POST /reservations 新增可选入参 channel_id——渠道侧订单号，通常是你自己系统里的订单 ID——用于让建单具备幂等性。在同一个百居易账号内，一个 channel_id 至多只能产生一张订单，因此超时后重试不会建出重复订单：再次提交同一个值会返回已存在的那张订单，而不是新建第二张。唯一性由数据库主键保证，不是应用层的先查后插，因此重试与首个请求并发时同样安全。作用范围是百居易账号（子账号与主账号共享同一命名空间），既不按应用划分，也与使用哪个自定义渠道无关；且该值一经使用即被永久占用，订单取消后也不释放。只允许字母和数字（^[A-Za-z0-9]+$，最长 32 位）：该值会成为订单编码的一部分，而标点在某些环节会被特殊解释。传入的值会存为订单的 channel_id，可通过 GET /reservations?channel_id= 回查——这也是超时后确认「究竟建成没有」的推荐方式。
• POST /reservations 的响应在 reservation_code 之外新增 status（wait_accept / wait_pay / accepted / cancelled / denied / timeout）。新建订单的 status 恒为 accepted；当提交的 channel_id 已存在时，该字段反映的是那张既有订单的当前状态——重放一张已被取消的订单同样返回 200，此时 status 为 cancelled，意味着订单已取消、房态并未占用。请以该字段判断，而不是 HTTP 状态码。
• 新增内置自定义渠道 Naver Reservation（custom_channel_id = 35），无需在自定义选项页创建，GET /custom_channels 对所有账号直接返回，可当作常量使用。该渠道仅在国际站 https://api.hostex.io/v3 提供，百居易 https://api.myhostex.com/v3 不会列出它。

修复

• GET /transactions：系统收支项目的 item_name 现在同样以账号的收支项目字典为准。此前内置项目列表会覆盖字典中的条目，导致系统项目可能以字典之外的名称返回。现在字典优先，内置名称仅用于字典中没有对应条目的系统项目。

[3.10.0] - 2026-07-31

新增

• 新增三个收支流水的 webhook 事件，订阅方不必再按较宽的 action_at 窗口轮询 GET /transactions——编辑流水不会改变其 action_at，窄窗口轮询会静默漏掉对历史流水的修改：

  • transaction_created——流水被创建，来源包括 POST /transactions、百居易网页端，以及退款等系统自动产生的流水。
  • transaction_updated——既有流水被修改。
  • transaction_deleted——流水被删除，请从你的镜像中移除。

  载荷沿用既有的薄载荷惯例（{ event, transaction_id, timestamp }），拿到后用 GET /transactions?id={transaction_id} 回捞当前状态。订阅方式与其他事件一致，通过 POST /webhooks 或 PATCH /webhooks/{id} 配置。参见 Webhook 事件类型。

[3.9.1] - 2026-07-17

变更

• POST /conversations/{conversation_id}（发送消息）的文档现已明确说明：该接口不具备幂等性，也不返回消息 ID。 请求超时时结果不可知——百居易无法判断渠道是否已经把消息投递出去，这一不确定性在我们侧无法消除，因此不提供幂等保证。接口行为没有变化，只是把这一点写进了文档，并给出我们的建议：出错时请按需重试——房客收到一条重复消息，好过收不到消息。

[3.9.0] - 2026-06-25

新增

• GET /reservations 现在为每条预约返回 payment 对象，暴露与百居易网页端一致的「已收 / 未收」收款状态：total_amount（应收金额）、received_amount（已收金额）、balance_amount（未收金额，不会为负）与 status（unreceived 未收 / partial 部分收款 / received 已收 / over_received 超额收款）。结算按订单级计算，因此共享同一 reservation_code 的各 stay 的 payment 值相同。该字段主要面向通过 POST /transactions 记录收款的 Hostex Direct（手动创建）预约。

[3.8.0] - 2026-06-17

新增

• GET /listings/airbnb/price_and_rules 与 POST /listings/airbnb/price_and_rules 新增 high_rated_guest_discount 与 mobile_only_discount 布尔字段，用于读取与开关 Airbnb 的高评分房客折扣与移动端专享折扣。

[3.7.0] - 2026-06-12

新增

• 新增 Messages 接口，用于管理会话中的特惠报价与预先批准（此前仅能在 Hostex 收件箱界面操作）：
  • GET /conversations/{conversation_id}/special_offers 列出会话中已发送的特惠报价与预先批准及其当前状态（active / accepted / declined / expired / withdrawn），返回的 id 用于撤回报价。同时作为 MCP 工具 search_special_offers 暴露。
  • POST /conversations/{conversation_id}/special_offers 向客人发送特惠报价：邀请客人以自定义总价 price 预订指定房源（listing_id）与日期，并附带人数明细（number_of_adults / number_of_children / number_of_infants / number_of_pets）。支持 Airbnb 与直订网站（booking site）会话；直订网站会话还需提供 rate_plan_id 与 currency。报价通常在发送后 24 小时过期。同时作为 MCP 工具 send_special_offer 暴露。
  • POST /conversations/{conversation_id}/preapprovals 预先批准客人的咨询（仅限 Airbnb 会话），邀请客人按标准价格预订其咨询的房源与日期。同时作为 MCP 工具 send_preapproval 暴露。
  • DELETE /conversations/{conversation_id}/special_offers/{special_offer_id} 撤回仍处于有效状态的已发送报价。同时作为 MCP 工具 withdraw_special_offer 暴露。
• 新增房源级价格与规则的查询接口，与已有的更新接口配套：
  • GET /listings/airbnb/price_and_rules 实时从 Airbnb 读取房源当前的价格、费用、折扣、预订设置与可订规则。响应与 POST /listings/airbnb/price_and_rules 接受的 settings 对象一一对应（读取到的值可直接原样写回），并额外返回 eligible_cancellation_policies，即该房源 cancellation_policy 的合法取值。限流与写操作相同（每分钟 120 次）。
  • GET /listings/vrbo/price_and_rules 返回 Hostex 当前记录的 Vrbo 房源价格、费用与预订规则（为同步快照，并非实时读取 Vrbo）。响应与 POST /listings/vrbo/price_and_rules 接受的 settings 对象一一对应。

[3.6.0] - 2026-06-01

新增

• POST /reviews/{reservation_code} 新增可选的 category_ratings 对象，可在提交房东评价时一并提交各分项评分（overall_rating、cleanliness、communication、respect_of_house_rules、recommend）。仅对支持分项评分的渠道生效（目前为 Airbnb 和 榛果）。未传 host_review_score 时，使用 overall_rating 的值作为评价分数。
• 新增用于更新房源级别价格、费用与预订规则的写接口（更新房源默认设置，而非指定日期区间；仅更新所传字段）：
  • POST /listings/airbnb/price_and_rules 更新 Airbnb 房源的价格、费用、折扣、预订设置与可订规则（base_price、weekend_price、cleaning_fee、security_deposit、pet_fee、early_bird_discount / last_minute_discount / long_term_discount、check_in_start_time / check_in_end_time / check_out_before、instant_booking、minimum_stay / maximum_stay、advance_notice、availability_window、cancellation_policy、new_listing_promotion 等）。同步提交至 Airbnb。
  • POST /listings/vrbo/price_and_rules 更新 Vrbo 房源的价格、费用与预订规则（base_price 或按星期的 nightly_rate、cleaning_fee、security_deposit、extra_guest_fee、weekly_discount / monthly_discount、check_in_start_time / check_out_before、instant_booking、minimum_stay、advance_notice、availability_window）。同步提交至 Vrbo。

[3.5.0] - 2026-05-25

新增

• Messages 新增写入端点，用于管理对话线程上的房东备注（即 GET /conversations/{conversation_id} 已暴露为只读的 note 字段）：
  • PATCH /conversations/{conversation_id}/note 设置或清空备注。备注仅存储在百居易内部（在百居易 Inbox 可见），绝不会发送给客人，也绝不推送到任何渠道；同一商家账号内的所有商家共享，便于团队互相留上下文。在 note 字段传空串或 null 即可清空（上限 5000 字符）。暴露为 MCP 工具 update_conversation_note。
• Property 房间分组字典新增写入端点，补齐已有的 GET /groups：
  • POST /groups 创建新分组（name 必填；可选 property_ids 在创建时直接挂房间）。分组名在商家账号内必须唯一。暴露为 MCP 工具 create_property_group。
  • PATCH /groups/{id} 更新分组。name 改名；property_ids 整体替换当前的房间挂载关系（传空数组即解除所有挂载）。暴露为 MCP 工具 update_property_group。
  • DELETE /groups/{id} 删除分组及其关联表，房间本身不受影响。暴露为 MCP 工具 delete_property_group。
• Property 房间标签字典新增写入端点，补齐已有的 GET /tags：
  • POST /tags 创建新房间标签（name 必填；可选 color，须为百居易调色板枚举值；可选 property_ids、room_type_ids）。每个商家最多 500 个房间标签；同名的软删标签会透明恢复。暴露为 MCP 工具 create_property_tag。
  • PATCH /tags/{id} 更新标签。name / color 改标签本身；property_ids / room_type_ids 各自整体替换挂载列表（空数组即解除全部挂载）。暴露为 MCP 工具 update_property_tag。
  • DELETE /tags/{id} 删除标签及其房间 / 房型关联表。暴露为 MCP 工具 delete_property_tag。
• 新增 Reservation Tags 一节，覆盖商家订单标签字典的读写（即 POST /reservations/{stay_code}/tags 能挂到订单上的那批标签）：
  • GET /reservation_tags 列出商家的订单标签字典，含系统默认标签（is_default = true，所有商家共享）和商家自建的自定义标签。支持 offset / limit 分页、id 精查、keyword 子串搜索。暴露为 MCP 工具 search_reservation_tags。
  • POST /reservation_tags 创建新自定义标签（仅 tag_name，上限 15 字符）。颜色由百居易调色板自动分配。与系统默认标签或商家已有标签同名时返回 409；同名的软删标签会透明恢复。每个商家最多 500 个自定义标签。暴露为 MCP 工具 create_reservation_tag。
  • DELETE /reservation_tags/{id} 删除商家某个自定义标签。系统默认标签不允许通过此 API 删除。删除时会同时解除该标签和它当时挂载的所有订单的关联。暴露为 MCP 工具 delete_reservation_tag。
• 新增 Calendar Share Links 一节，覆盖公开只读日历共享链接的读写（即百居易房东后台 "Share calendar" 暴露的那批对象）：
  • GET /calendar_share_links 列出商家的共享链接。每条返回 id、scope（entire / partial）、url 以及该链接暴露的 property_ids（scope = entire 时为空数组）。暴露为 MCP 工具 search_calendar_share_links。
  • POST /calendar_share_links 创建新共享链接。scope = entire 覆盖商家所有房间（幂等：已存在则返回已有链接）。scope = partial 需传非空 property_ids 列表，且每个 id 必须属于该商家。暴露为 MCP 工具 create_calendar_share_link。
  • DELETE /calendar_share_links/{id} 失效一条共享链接；持有旧 URL 的人会拿到 share link invalid 错误。暴露为 MCP 工具 delete_calendar_share_link。

变更

• GET /tags 的 x-mcp 元数据：description 和 intent_examples 已澄清——此端点返回的是房间标签（挂在房间 / 房型上的标签），不是订单标签。订单标签字典由新加的 MCP 工具 search_reservation_tags 覆盖。响应体结构本身不变。
• GET /reservations：每条订单新增 checkin_guide_images 字段，返回客人通过在线入住登记上传的证件图片，覆盖该订单下的所有上传图片——包括尚未关联到客人记录的图片（这些图片 client_id 为 null）。每个元素包含 id、client_id 和 url（图片 CDN 上的 extra-large 尺寸）。原有的客人维度 guests[].id_images 字段保持不变。
• GET /reservations：每条预订新增 rates.tax 字段，单独返回预订的 TAXES（税费）金额，结构为 { currency, amount }（无税费时返回 null）。汇总的 rates.rate 与 rates.details 保持不变。

---

[3.4.1] - 2026-05-21

变更

• BREAKING GET /knowledge_bases：property_ids 查询参数从重复数组改为逗号分隔的整数串（例如 1,2,3），与 GET /automation/actions 以及 v3 其余列表端点统一。
• BREAKING POST /knowledge_bases 和 PATCH /knowledge_bases/{id}：scope_property.scope_ids 改名为 scope_property.ids，与 GET /knowledge_bases 和 GET /knowledge_bases/{id} 返回值的字段名对齐。

新增

• GET /knowledge_bases/{id}：响应新增 process_status（字符串枚举 waiting / processing / done / failed），与列表端点一致。
• GET /automation/actions：actions[] 每项新增 type（message / review）和 stay_code（关联订单的行程编号，可能为 null）。
• POST /automation/actions/{plan_id}/execute：补全文档中针对不支持的计划类型，以及订单尚未退房的 review 计划返回 400 的说明。

修复

• GET /knowledge_bases：用 channel_types 过滤不再因 TypeError 报错；每行返回的 scope_property 现在能正确反映条目实际的房间范围（all / by_property / by_group / by_room_type），不再一律回退为空的 by_property 集合。
• GET /knowledge_bases/{id}：同上 scope_property 修正。
• POST /knowledge_bases 和 PATCH /knowledge_bases/{id}：当 scope_channel.type 为 all 时，上游渠道列表不再被填上 unknown 哨兵；PATCH /knowledge_bases/{id} 和 DELETE /knowledge_bases/{id} 的权限失败统一返回 404。
• GET /knowledge_bases：分页现在尊重任意 offset 值，不再每次必整页跳进（原来用 ceil(offset / limit) + 1 算页号，导致 offset=5, limit=10 返回第 11–20 行而不是第 6–15 行）。
• GET /automation/actions：结果现在正确限定在商家主账号范围内，子账号 access token 不再返回空列表。total 也与返回的 actions[] 行数一致（缺规则或详情行的 plan 在 SQL 层过滤，而不是在 PHP 层跳过）。
• POST /automation/actions/{plan_id}/execute：当天的评价不再被误判为"尚未退房"——退房日期比较改用订单退房时间的日期部分，而非字符串字典序比较。

---

[3.4.0] - 2026-05-20

新增

• 新增 Knowledge Base 一节，完整覆盖自动化助手使用的 HostGPT 知识库条目的读写。每条目带正文和适用范围（房间 / 渠道）：
  • GET /knowledge_bases 列出条目，支持分页和按房间或渠道过滤。
  • GET /knowledge_bases/{id} 获取单条目的完整详情。
  • POST /knowledge_bases 创建新条目。
  • PATCH /knowledge_bases/{id} 更新已有条目。
  • DELETE /knowledge_bases/{id} 删除条目。
• 新增 Channels 一节，只读访问商家已接入的渠道账号以及这些账号同步过来的房源：
  • GET /channel_accounts 返回商家已接入的第三方平台账号（Airbnb、Booking.com 等），含 channel_type、username、origin_account_id 以及可读的 auth_status 枚举（active / connecting / disconnected / exception）。支持按 id 和 channel_type 过滤。channel_type=booking_site 的账号会被排除。暴露为 MCP 工具 search_channel_accounts。
  • GET /listings 返回挂在这些账号下的房源（渠道侧的 property），含 listing_id、channel_type、channel_account_id、title、cover、url、inventory、可读的 shelf_status 枚举以及一个 metadata 透传对象，暴露百居易内部缓存的渠道侧归一化数据（地理、图片、价格表等；形状随渠道不同）。支持按 channel_account_id、listing_id 和 channel_type 过滤。暴露为 MCP 工具 search_listings。
• GET /tasks：新增可选 id 查询参数，按内部 id 取单条任务（仍限定当前商家）。其他过滤条件不变。
• GET /transactions：新增可选 id 查询参数，按内部 id 取单条收支条目。带 id 时 start_date 和 end_date 可省略；不带 id 时仍受现有日期范围（以及 366 天上限）约束。
• GET /reservations：guests 每项新增 id_images 数组，暴露为该客人上传的证件影像。每项含图片 id 和指向图片 CDN 大图变体的 url。无影像时返回空数组。
• GET /conversations/{id}：messages 每项新增：
  • sender_name：发送者的显示名（房东侧消息为商家账号名，HostGPT 生成的消息为 HostGPT，影子预览消息为本地化的 HostGPT 标签）。客人消息以及其他无法识别发送者的情况为 null。
  • sources：HostGPT 生成该条消息引用的知识源，按 type 分组（如 checkin_guide、automation_reply、host_knowledge、thread、host_assistant）。每组暴露 docs[].title / docs[].fragment / docs[].source_type / docs[].link_id。人工发送的消息以及无引用的 HostGPT 消息为空数组。
• PATCH /reservations/{stay_code}/check_in_details：新增可选 id_required 字段，控制客人在入住前是否需要登记 / 上传证件。字符串枚举：not_required（无需证件）、required（采集证件，无需人工审核）、required_with_review（采集证件且房东人工审核通过）。内部映射到该行程入住指南的 need_credential，并触发与百居易房东后台一致的下游入住解锁逻辑。
• GET /reservations：check_in_details 每项现在暴露对应的 id_required 字符串枚举（未对该行程设置时默认 not_required）。
• GET /reservations：order_by 新增支持 created_at（按行创建时间排序，即订单首次同步进百居易的时间）。已有枚举值（booked_at、check_in_date、check_out_date、cancelled_at）保持不变；默认仍为 booked_at。
• POST /tasks：新增可选 stay_code 字段，写入 schedule_task__reservation 关联表把任务与具体订单关联。stay_code 不带 property_id 时房间由行程继承；两者都带时必须指向同一房间。LLM 流程用于"为这单订单创建清洁 / 维修任务"。
• GET /tasks：每条任务新增 stay_code 字段（字符串，可空）——任务关联到的订单；无关联返回 null。
• Property 新增写入端点：
  • POST /properties 在当前商家下创建新房间。仅 title 必填；其余（地址、渠道、图片、价格、默认入住 / 退房时间）一律通过百居易房东后台后续配置。受商家订阅的房间数量上限约束。
• Room Type 新增写入端点：
  • POST /room_types 在当前商家下创建新房型。可选 property_ids 在创建时直接挂房间（每个房间不能已挂在其他房型下）。受房型数量上限约束（受订阅房间数量上限封顶），Basic 版本不可用。
• Listing Calendar 下新增 GET /pricing_ratios，返回挂在房间（property_id）或房型（room_type_id）下每个 OTA 房源的渠道侧价格比例。每条暴露 channel_type、listing_id、listing_title、ratio（百分比）以及 readonly。这条让技能 / 客户端层不依赖专门的服务器端点即可实现"按房间 / 房型改价"工作流：读出比例，每个非 readonly 房源算出 target_price = round(base_price * ratio / 100)，再对每个房源调一次 POST /listings/prices（readonly: true 的房源——例如 Airbnb 子套餐——必须跳过）。

---

[3.3.1] - 2026-05-11

修复

• GET /transactions：start_date 和 end_date 现在一律以商家配置的时区解读，与条目存储方式以及 action_at 返回值一致。原来边界可能按数据库会话默认时区计算，使非 UTC+8 商家最多偏移一天。
• POST /transactions 和 PATCH /transactions/{id}：以 UTC ISO 8601 提供的 action_at 现在会先转换到商家时区再落库，使 GET /transactions 的来回往返返回同一时刻。

---

[3.3.0] - 2026-05-08

新增

• GET /reservations：新增可选 channel_id 查询参数，按渠道侧订单 ID 过滤（即响应中 channel_id 字段的同一个值）。

---

[3.2.0] - 2026-04-29

新增

• 新增 Incomes & Expenses 一节，完整覆盖收支条目（账目）的读写：
  • GET /transactions 查询条目。支持按日期范围（start_date / end_date）、property_id、stay_code、direction、item_id、payment_method_id、currency 和 keyword 过滤。每条暴露可读字符串枚举 direction（income / expense）、link_type（property / reservation / operator）和 status（paid / outstanding），并把 item_name / payment_method_name 从下方字典解析出来。
  • POST /transactions 记录新条目。关联目标按请求推断：传 stay_code 关联到具体行程，传 property_id 关联到房间，两者都不传则为商家层条目（仅主账号可用）。amount 一律为正——符号由 direction 推导。currency 必填，除非传了 stay_code，此时从订单继承。
  • PATCH /transactions/{id} 更新条目的 amount、item_id、payment_method_id、action_at 或 note。方向、关联目标和币种不可变。
  • DELETE /transactions/{id} 永久删除条目。
  • 新增字典端点 GET /income_items、GET /expense_items、GET /income_methods 和 GET /expense_methods，用于解码 GET /transactions 返回的 item_id / payment_method_id。
• Task 新增写入端点：
  • POST /tasks 创建任务。可选 property_id 和 staff_id 把任务关联到房间并分配员工；level 仅对清洁任务有意义。expected_date / expected_time 以商家配置的时区解读。返回新任务的 task_id。
  • PATCH /tasks/{id} 更新已有任务。所有字段均为可选；传 property_id=0 或 staff_id=0 解除关联。status 完整生命周期（pending / in_progress / completed / cancelled）也在这里设置。expected_date / expected_time 以商家配置的时区解读。
  • DELETE /tasks/{id} 删除任务。
• Staff 新增写入端点：
  • POST /staffs 创建员工（创建为启用状态）。用 property_ids 把员工限定到具体房间。国际商家须以 +<国家代码> <号码> 格式提供 mobile。
  • PATCH /staffs/{id} 更新已有员工。传 property_ids 会整体替换挂载列表；传空数组即清空。is_active 控制启用 / 停用。
  • DELETE /staffs/{id} 删除员工（并移除其房间挂载）。

变更

• PATCH /reservations/{stay_code}（更新订单基本信息）：路径参数从 reservation_code 改为 stay_code，因为该端点更新的是具体行程的属性，而不是订单本身。URL pattern 不变。DELETE /reservations/{reservation_code}（取消）以及渠道侧的 POST /reservations/{reservation_code}/approve|decline 仍保留 reservation_code，因为它们作用在订单层。

修复

• GET /reservations：custom_channel.id 现在返回与 GET /custom_channels 一致的 id（原来返回的是内部表主键，无法与字典匹配）。

---

[3.1.2] - 2026-04-28

新增

• 新增 Task 端点 GET /tasks 和 GET /staffs，用于查询任务和员工。
• GET /tasks 支持按日期范围（start_date / end_date）、staff_id、property_id、type 和 status 过滤。
• 任务的 type、status 和 level 以可读字符串枚举返回（如 cleaning、pending、standard）。

---

[3.1.1] - 2026-03-10

新增

• 新增 Property 端点 GET /tags，返回所有标签及其关联的房间与房型 id。
• GET /properties 支持 tag_id 过滤，每条房间新增 tags 数组。
• GET /room_types 支持 id 和 tag_id 过滤，每条房型新增 tags 数组。

---

[3.1.0] - 2026-01-21

新增

• 新增 Property 端点 GET /groups，返回所有房间分组及其关联的房间 id。
• GET /properties 支持 group_id 过滤，每条房间新增 groups 数组。

---

[3.0.0]

新增

• 首次发布百居易 OpenAPI v3，覆盖 Property、Room Type、Reservations、Availabilities、Listing Calendar、Messaging、Reviews、Automation 和 Webhooks。