变更日志

变更日志

[3.23.0] - 2026-11-16

新增

  • POST /reservations/{reservation_code}/charges 为订单创建一笔一次性收款,返回收款 ID charge_id 与客人付款页链接 payment_link。必传 amount、currency(须与订单币种一致)、due_date;name、note、income_item_id、idempotency_key 可选。需要可写的 access token。典型用法:用 POST /reservations 建单,创建收款,把客人跳转到 payment_link,再读 GET /reservations 的 payment 判断是否已付款。
    • 客人可以用房东所有已连接、开启「用于收款」且能收这个币种的收款账户付款(微信支付账户只收人民币,Flywire 账户只收它自己的币种,PayPal 账户只收 PayPal 支持的币种),调用方不能指定账户。房东没有这样的账户时返回 400,不会创建收款。payment_account_types 列出客人会看到的账户类型。
    • income_item_id 默认 22(订单收入)。GET /reservations 的 payment 只统计订单收入,选其他收入项目时,客人付款不会改变 payment。
    • 房东的收款通知规则与在百居易里创建的收款一样生效:默认情况下,收款创建后客人还会收到一封带付款链接的邮件,到期日前后会收到提醒。
    • 传 idempotency_key(8-64 位字母、数字、- 或 _)可以安全重试:24 小时内同一个 key、同样参数返回已有收款,created: false;同一个 key 换了参数返回 409。带 key 的请求返回 500 时也可以用同一个 key 重试:返回那次请求建出的收款,或只建一笔。
    • 已取消、已拒绝、已超时的订单返回 400;其他账号的订单返回 404。
    • 暂不支持:客人付款成功的 Webhook、付款后跳回你的网站、未付款订单自动取消、周期或分期收款。

[3.22.0] - 2026-11-11

新增

  • POST /reservations/{reservation_code}/decline 对 Airbnb 订单支持可选的 JSON 请求体:decline_reason(dates_not_available、not_a_good_fit、waiting_for_better_reservation 或 not_comfortable,默认 not_comfortable)、decline_message_to_guest(客人在 Airbnb 上看到的说明)和 decline_message_to_airbnb(给 Airbnb 的私密备注)。Airbnb 拒单时要求必须给客人说明;未传或传空的 decline_message_to_guest 时,会发送一条默认英文说明(例如:"Sorry, we are unable to accommodate your requested dates.")。decline_reason 取值不合法时返回 400,不会调用 Airbnb。其他渠道忽略这些字段,行为不变。MCP 工具 decline_reservation 支持同样的字段。

修复

  • 用 POST /reservations/{reservation_code}/decline 拒绝 Airbnb 订单申请时,传了 decline_message_to_guest 不再报 decline_message_to_guest is missing;此前该说明没有转发给 Airbnb。

[3.21.0] - 2026-11-10

新增

  • 新建、修改、启用、停用 Booking.com 优惠活动。四个接口都同步调用 Booking.com、会改变客人在 Booking.com 上看到的价格、需要可写的 access token,功能对你的账号开放前返回 501(与 POST /channel_accounts/booking/promotions/excluded_dates 分开开放)。结果带 confirmed(已从 Booking.com 读回时为 true;Booking.com 已接受但约 30 秒内尚未可见时为 false)和 Booking.com 的 ruid。Booking.com 拒绝的取值返回 400,error_msg 中带 Booking.com 错误码;502 表示 Booking.com 暂时不可用或结果无法确认。
    • POST /channel_accounts/booking/promotions 新建优惠,类型为 basic、last_minute、early_booker、geo_rate、mobile_rate、campaign_black_friday、campaign_early_year、campaign_getaway、campaign_late_escape 或 new_property_deal。必填字段与折扣范围随类型不同,会在调用 Booking.com 之前校验。一个住宿只有一条 mobile_rate,每个国家渠道只有一条 geo_rate,已存在时再新建返回 409 并给出其 id,请改用 PATCH 修改。geo_rate 与 mobile_rate 不需要 name 和 stay_date,early_booker 与 last_minute 最多传一个,与 Booking.com 返回这两种优惠的方式一致。必须带 idempotency_key:第一次请求后的 24 小时内,失败或超时后用同一个 key 重发,会拿到第一次请求建出的优惠(created: false),而不是建出重复的一条;502 的错误信息里列出了优惠 id 时,请核对这些优惠,不要再重试。non_refundable: true 时,如果住宿还没有不可退款政策,Booking.com 会新建一个 3 天不可退款政策。每个 Booking.com 住宿每天最多 20 次新建请求。MCP 工具 create_booking_promotion。
    • PATCH /channel_accounts/booking/promotions/{promotion_id} 只改传入的字段:name、discount、target_channel、min_stay_through、non_refundable、stay_date(start/end、active_weekdays)、additional_dates、book_date、book_time(传 null 去掉限制)、last_minute、early_booker、rooms、parent_rates。排除日期仍只能用 POST /channel_accounts/booking/promotions/excluded_dates 修改。Booking.com 每次更新成功都会把优惠设为启用,所以已停用的优惠会返回 409,除非传 activate: true。geo_rate 优惠只能改 discount,mobile_rate 优惠只能改 discount、target_channel 与 parent_rates(否则返回 409)。Booking.com 不返回已启用优惠的 rooms 与 parent_rates,所以设置这两项通常得到 confirmed: false。MCP 工具 update_booking_promotion。
    • POST /channel_accounts/booking/promotions/{promotion_id}/activate 与 …/deactivate 启用或停用优惠;已是目标状态时 changed: false。Booking.com 优惠无法删除,请改用停用。MCP 工具 activate_booking_promotion 与 deactivate_booking_promotion。
    • 四个 MCP 工具都需要确认。

变更

  • 每个 Booking.com 住宿每分钟 10 次写入的限制改为所有 Booking.com 优惠写入合计,包括 POST /channel_accounts/booking/promotions/excluded_dates。参见 限流。
  • GET /channel_accounts/booking/promotions 与 POST /channel_accounts/booking/promotions/excluded_dates 遇到更多表示请求本身无效的 Booking.com 错误码(如 ID_INVALID、ROOMS_INVALID、RATES_INVALID)时,也改为返回 400 而不是 502,原样重试不会有用。

[3.20.0] - 2026-11-09

新增

  • Booking.com 优惠活动。GET /channel_accounts/booking/promotions?channel_account_id=<id> 从 Booking.com 实时读取某个 Booking.com 住宿的优惠活动:id、name、type、active、discount、min_stay_through、stay_date(含 active_weekdays 与 excluded_dates)、可预订时间窗,以及关联的 rooms 与 parent_rates。加 active_only=true 只返回已启用的优惠。优惠活动属于 Booking.com 住宿,所以入参是渠道账号(GET /channel_accounts),而不是房源。同时提供 MCP 工具 get_booking_promotions(只读)。
  • POST /channel_accounts/booking/promotions/excluded_dates:用 {channel_account_id, promotion_id, add[], remove[]} 为某个优惠添加或移除排除的入住日期。只改动传入的日期;其他排除日期、折扣、房型、价格计划和房态都不受影响,响应带 confirmed:已从 Booking.com 读回新日期时为 true;Booking.com 已接受但约 30 秒内尚未可见时为 false(请过一分钟左右用读接口核对;删除最后一个排除日期时也可能为 false)。更新后的几十秒内读接口可能仍返回旧的排除日期,重发同样的请求是安全的。add 与 remove 是幂等的。只能修改已启用的优惠(否则返回 409),因为 Booking.com 每次更新成功都会把优惠设为启用。日期格式为 YYYY-MM-DD,不能早于今天、在 3 年以内,合计最多 366 个;Booking.com 拒绝的日期返回 400,error_msg 中带 Booking.com 错误码。502 表示 Booking.com 暂时不可用或结果无法确认,更新仍可能在几分钟内生效:重发相同请求是安全的,但如要传不同的日期,请等几分钟、先读取该优惠再决定。每个 Booking.com 住宿每分钟最多更新 10 次;需要可写的 access token;功能尚未对你的账号开放时返回 501。同时提供 MCP 工具 update_booking_promotion_excluded_dates(需要确认)。

变更

  • 两个 Booking.com 优惠接口每次请求都会调用 Booking.com,与写操作共用更严格的接口级限流(每分钟 120 次)。参见 限流。

[3.19.1] - 2026-11-09

修复

  • transaction_created 现在按 Webhook 事件类型 所述,每新建一条收支流水发送一次,不论流水是在百居易里添加、通过 POST /transactions 创建,还是由百居易自动生成。此前很多新建的流水(例如在订单上添加的收支、费用收款和退款、任务费用、押金结算)只发送 transaction_updated,或不发送任何 webhook。其中一部分仍会在 transaction_created 之后紧跟一条同一流水的 transaction_updated,请用 GET /transactions?id= 回查,以当前状态为准。百居易随订单自动同步维护的流水(渠道订单的房费,以及 BookingSite 订单的房费、退款和支付手续费)仍不发送收支事件。
  • transaction_deleted 现在每删除一条收支流水发送一次,无论是在百居易里删除、删除或取消费用 / 任务 / 手工订单时连带删掉,还是通过 DELETE /transactions/{id} 删除。此前这个事件从未发送过。收到后请从本地镜像中移除该流水。

[3.19.0] - 2026-11-06

新增

  • 新增两个说明「变了什么」的 webhook 事件,订阅方不必在每次 reservation_updated / review_updated 之后回查订单或评价才知道发生了什么:

    • reservation_cancelled——订单状态变为 cancelled 时发送一次,无论在渠道上还是在百居易里取消。已取消订单之后的更新不会再次发送;最终为 denied 或 timeout 的预订申请不会发送。
    • guest_review_created——房客对某次入住的评价第一次出现时发送一次,也就是 GET /reviews 开始返回其 guest_review 的时候。与 review_created 不同,部分渠道在退房时先创建的空评价记录不会触发它;房东回复和之后的修改也不会再次发送。

    载荷与 reservation_created 相同(reservation_code、stay_code、property_id)。同一次变化仍会照常发送 reservation_updated、review_created、review_updated。未设置 events 过滤的 webhook 会开始收到这两个新事件;如只想接收部分事件,请通过 POST /webhooks 或 PATCH /webhooks/{id} 设置 events。参见 Webhook 事件类型。

  • PATCH /reservations/{stay_code}/guests/{guest_id}:更新一位住客的证件与个人信息,可写 id_type、id_number、name、gender、birthday(YYYY-MM-DD)与 country(ISO 3166-1 Alpha-2)。guest_id 即 GET /reservations 返回的 guests[].id。至少传一个字段;未传的字段保持不变,不支持清空(传 null 或空字符串返回 400)。传 id_number 时必须同时传 id_type。修改保存在住客档案上,该住客关联的所有入住单都会显示新值。修改 name 后,后续渠道同步不再覆盖姓名,与在网页端改姓名一致;渠道同步的证件字段只在为空时回填,不会覆盖这里写入的值。住客不在该入住单上或属于其他账号时返回 404。需要可写的 access token。本接口不上传证件照片。百居易请求日志中的 id_number 会被打码。同时提供 MCP 工具 update_reservation_guest。

  • GET /reservations/{stay_code}/guests:列出一张入住单上的住客,字段与 GET /reservations 的 guests[] 相同,预订人在前。列出的住客都能用 PATCH /reservations/{stay_code}/guests/{guest_id} 更新。若是多房订单中的一间,还会返回只关联到这间房的住客(GET /reservations 不显示),此时同一个人可能出现两条、id 不同。同时提供只读 MCP 工具 search_reservation_guests。

  • GET /reservations 新增 guests[].birthday(YYYY-MM-DD 或 null)。若存储的日期像是网页端编辑住客、未填生日时保存的占位值(住客建档或编辑那年往前 30 年的 1 月 1 日),同样返回 null;通过 PATCH /reservations/{stay_code}/guests/{guest_id} 写入的生日一律按写入值返回。guests[] 原有字段不变。

[3.18.1] - 2026-11-03

变更

  • POST /webhooks:OAuth 应用按「应用 + 账号」独立计配额,默认最多 50 条,百居易可按账号调整。应用创建的 webhook 不再占用账号自有配额;通过自助 access token 创建仍最多 5 条,网页端手动创建仍最多 3 条。
  • 应用创建的 webhook 接收端返回 410 Gone 时,百居易会删除该 webhook;恢复投递需重新创建。手动 webhook 及返回 404 的情况不会触发删除。
  • POST /oauth/authorizations:refresh token 轮换后,在默认 60 秒宽限期内再次使用旧 refresh token,只要新令牌记录仍存在,就返回同一对新令牌,以兼容并发刷新;宽限期结束后旧 refresh token 失效。若等待并发刷新超时,则返回 429 Token refresh in progress, retry later.,不轮换令牌,也不增加任何失败计数;请稍后重试。
  • POST /oauth/authorizations:无效或已用过的授权码、refresh token 不再计入凭据失败(未知客户端、client_secret 或 code_verifier 校验失败)。两类失败计数现在均按 client_id、grant_type 和请求 IP 独立分桶,IPv6 地址按 /64 归为同一来源;每个桶从第一次失败起固定计算窗口,凭据失败为 600 秒,无效 grant 默认为 600 秒,后续失败不会续期。凭据失败计数大于 10,或独立的无效 grant 计数达到配置上限(默认 200)时,返回 429 Too many attempts.。公共客户端(无 client_secret)另按 client_id 和请求 IP 限制不同的无效 refresh token 个数,在无效 grant 窗口内默认最多 30 个;同一个 refresh token 重试只计一次。
  • POST /tasks 未传 level 时,现在一律按 standard 保存,所有任务类型都如此,与百居易网页端和 App 创建的任务一致。因此 GET /tasks 对这些任务返回 level: "standard"(包括维护、接待等非清洁任务),此前返回 null。此次变更之前创建的任务不会更新,仍返回 null。展示等级的任务通知也会对这些任务显示标准等级。判断任务是否为清洁任务请看 type,不要看 level。

[3.18.0] - 2026-10-19

新增

  • 收支支持挂凭证图片。POST /transactions/{id}/attachments 以 multipart/form-data 上传一张 JPEG 或 PNG 图片(不超过 10 MB,字段名 file)并挂到该收支条目上,不接受 JSON 或 base64 请求体;DELETE /transactions/{id}/attachments/{attachment_id} 从该条目上移除一张凭证。GET /transactions 新增 attachments 字段,每条收支返回 {id, url} 列表(没有凭证时为空数组),包含在百居易网页端添加的凭证,url 为原图。每条收支最多 10 张凭证(网页端添加的也计入),每个账号每 10 分钟最多上传 60 次。添加或删除凭证不会改变该条目的 updated_at,也不会发送 webhook。删除凭证不会删除图片文件,原链接可能仍可打开。POST /transactions 与 PATCH /transactions/{id} 不变。

[3.17.2] - 2026-10-12

变更

  • Webhook 接收端返回 404 或 410 时,照旧不重试,但改为计一次投递失败:同一个 URL 连续失败达到阈值后会被暂停推送一段时间,暂停期间的通知直接丢弃、不补发。此前任何 HTTP 应答都算送达,已失效的地址会一直被推送。其他状态码(包括 401、403、429、5xx)仍算送达。见 Webhook 使用指南。
  • Webhook 的首次请求也可能来自与以往不同的 IP 地址(此前只有重试会换 IP)。请继续用 Hostex-Webhook-Secret-Token 校验来源,不要只放行单一 IP。

[3.17.1] - 2026-10-09

变更

  • POST /reservations(创建订单)文档中 rate_amount、commission_amount、received_amount 的类型由 integer 更正为 number。接口一直接受带小数的金额(例如 200.10),与百居易网页端创建手工单一致,也与 PATCH /reservations/{stay_code} 中同名字段的类型一致。接口行为没有变化,错的是文档。

[3.17.0] - 2026-10-09

新增

  • GET /reservations 新增 check_in_details.deposit_details:入住单的押金收退明细,包括 amount(应收)、paid_amount(已付)、deducted_amount(已扣)、pending_refund_amount(待退)、refunded_amount(已退),金额以押金自身的 currency 计;以及 status,取值 unpaid(未支付)、paid(已支付)、refunded(已退还)。判断是否还有钱要退给客人请看 pending_refund_amount > 0,不要看 status——房东全额扣除的押金会一直是 paid。refunded_amount 统计的是已提交的退还,不代表款项已到客人账上;国际版账号上,即使房东已在百居易后台退还押金,该字段也可能返回 0——这类退还在结算时会把它写成 0,此时各项金额不再相加吻合,因此不要把它作为对账的唯一依据:还需退给客人的金额以 pending_refund_amount 为准,实际退还金额以百居易后台押金页面为准。通过 Stripe 刷卡支付的押金,paid 表示金额已在客人卡上预授权、尚未实际扣款;预授权可能在房东扣除或退还之前失效,在百居易完成结算之前,这类押金仍按已支付、待退还显示,而此时卡上其实已经没有冻结的钱。百居易没有该入住单的押金记录,或无需押金且未支付时,deposit_details 为 null。check_in_details.deposit 不变。押金的支付、扣除、退还不会发送 webhook,请通过 GET /reservations 读取。

[3.16.0] - 2026-10-09

新增

  • 所有 v3 webhook 事件新增 ULID 字符串 event_id,同一事件在多个 webhook URL 和重试时共用。可用于通知去重,不保证送达或顺序。
  • 新增 GET /accounts/me,返回主账号及子账号授权共用的稳定字符串 account_id。
  • POST /webhooks 仅创建时返回 id 和 secret_token。请安全保存密钥;查询及更新响应不返回密钥。
  • OAuth 应用解除授权时,删除该账号下由该应用通过 API 创建的 webhook,并向保存的地址发送最后一条 authorization_revoked 通知。多设备 public client 仅在最后一个令牌撤销后断开整个应用。手工创建及其他应用的 webhook 保留。通知尽力投递;已发出的请求可能在解除授权后抵达。

[3.15.0] - 2026-09-27

新增

  • GET /reviews 新增 guest_review.private_feedback:Airbnb 房客在评价时单独留给房东的私密反馈。Airbnb 只把它展示给房东本人、不会公开,因此常包含公开评价里没有写的维修、清洁等问题。内容原样返回 Airbnb 给出的文本。房客没有留时为 null;airbnb 以外的渠道始终为 null。已有评价同样适用——Hostex 已经同步到的私密反馈会直接返回,不需要等评价再次变化。review_created、review_updated webhook 不变:仍然不携带评价内容,请照旧在收到 webhook 后调用 GET /reviews 读取该字段。
  • 房东 MCP 的 search_reviews、create_review 工具说明写明:guest_review.private_feedback 只属于房东,绝不能在公开的评价或回复中引用或转述,避免 AI 代房东起草回复时把私信内容发布出去。

[3.14.0] - 2026-09-18

新增

  • GET /listings/airbnb/price_and_rules 现在会返回 Airbnb 高评分房客折扣与移动端专享折扣的不可用日期及当年额度:high_rated_guest_discount_blackout_dates、high_rated_guest_discount_blackout_dates_quota、mobile_only_discount_blackout_dates、mobile_only_discount_blackout_dates_quota。这些日期仍可预订,只是对应折扣不生效。Airbnb 对每个房源、每种折扣按自然年最多允许 30 天。
  • POST /listings/airbnb/price_and_rules 新增 high_rated_guest_discount_blackout_dates 与 mobile_only_discount_blackout_dates(YYYY-MM-DD 数组)。省略字段表示不改;传 [] 表示清空。可以和原有的开关布尔值一起写,也可以在折扣已开启时单独改日期。

[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。