变更日志
[3.23.0] - 2026-11-16
新增
POST /reservations/{reservation_code}/charges为订单创建一笔一次性收款,返回收款 IDcharge_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、付款后跳回你的网站、未付款订单自动取消、周期或分期收款。
- 客人可以用房东所有已连接、开启「用于收款」且能收这个币种的收款账户付款(微信支付账户只收人民币,Flywire 账户只收它自己的币种,PayPal 账户只收 PayPal 支持的币种),调用方不能指定账户。房东没有这样的账户时返回
[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_updatedwebhook 不变:仍然不携带评价内容,请照旧在收到 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_updatedwebhook 通知,不会为补上该值单独发送 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。
