Hostex API 技能（Node）

认证（PAT）

• 设置环境变量：HOSTEX_ACCESS_TOKEN
• 请求需携带请求头：Hostex-Access-Token:
• OpenAPI 安全机制名称：HostexAccessToken

默认建议：使用 只读 的 PAT。

日期 / 时区

• 所有日期参数格式均为 YYYY-MM-DD
• 日期按 房源所在时区 解析（不使用 UTC 时间戳）

OpenAPI 权威来源

稳定版 OpenAPI JSON 地址：

• https://hostex.io/open_api/v3/config.json

可运行 scripts/openapi-sync.mjs 将其缓存至本地 references/openapi.json。

常用命令（脚本）

所有脚本均要求已设置 HOSTEX_ACCESS_TOKEN。

只读操作（安全）

列出房源：

node skills/hostex/scripts/hostex-read.mjs list-properties --limit 20

按入住日期范围列出预订：

node skills/hostex/scripts/hostex-read.mjs list-reservations --start-check-in-date 2026-02-01 --end-check-in-date 2026-02-28 --limit 20

按预订编号列出预订：

node skills/hostex/scripts/hostex-read.mjs list-reservations --reservation-code 0-1234567-abcdef

获取可订状态：

node skills/hostex/scripts/hostex-read.mjs get-availabilities --start 2026-02-10 --end 2026-02-20 --property-id 123

写入操作（受保护）

写入功能默认禁用，启用需同时满足以下条件：

• HOSTEX_ALLOW_WRITES=true

且必须显式传入 --confirm 参数。

发送消息：

HOSTEX_ALLOW_WRITES=true node skills/hostex/scripts/hostex-write.mjs send-message --conversation-id 123 --text "Hello!" --confirm

更新房源价格（单区间示例）：

HOSTEX_ALLOW_WRITES=true node skills/hostex/scripts/hostex-write.mjs update-listing-prices 
  --channel-type airbnb 
  --listing-id 456 
  --start 2026-02-10 
  --end 2026-02-15 
  --price 199 
  --confirm

更新房源价格（单次请求多区间示例）：

HOSTEX_ALLOW_WRITES=true node skills/hostex/scripts/hostex-write.mjs update-listing-prices 
  --channel-type booking_site 
  --listing-id 100541-10072 
  --prices "2026-02-03..2026-02-05:599,2026-02-06..2026-02-07:699,2026-02-08..2026-02-09:599" 
  --confirm

创建预订（直连预订，示例）：

HOSTEX_ALLOW_WRITES=true node skills/hostex/scripts/hostex-write.mjs create-reservation 
  --property-id 123 
  --custom-channel-id 77 
  --check-in-date 2026-02-10 
  --check-out-date 2026-02-12 
  --guest-name "Alice" 
  --currency USD 
  --rate-amount 200 
  --commission-amount 0 
  --received-amount 200 
  --income-method-id 3 
  --confirm

更新房源可订状态（关闭/开启，示例）：

# 关闭某房源在指定日期范围内的可订状态
HOSTEX_ALLOW_WRITES=true node skills/hostex/scripts/hostex-write.mjs update-availabilities 
  --property-ids "11322075" 
  --available false 
  --start-date 2026-02-03 
  --end-date 2027-02-02 
  --confirm

运维防护措施（强制要求）

执行任何写入操作时，必须遵守以下规则：

1. 明确摘要变更内容（涉及对象、变更类型、生效时间、影响范围等）。
2. 必须由用户显式确认（例如输入 CONFIRM）。
3. 如支持，应优先使用 --dry-run 进行预演。

备注

• 分页：接口通常支持 offset 与 limit 参数（limit 最大值为 100）。
• 切勿在日志中打印访问令牌；脚本会自动对敏感信息进行脱敏处理。