酒店与商品目录

商品目录相关接口都是只读的，描述你能卖什么：酒店本身、它的房型、实时房量，以及客人有资格预订的房价方案。

GET /property

返回密钥所绑定酒店的基本信息。任何通过认证的密钥都可以调用。

curl "$VRDN_BASE/property" -H "Authorization: Bearer $VRDN_KEY"

{
  "id": "p_8f2a1c",
  "slug": "sunrise-bay",
  "name": "Sunrise Bay Resort",
  "currency": "USD",
  "timezone": "Pacific/Fiji",
  "child_max_age": 12,
  "infant_max_age": 2
}

字段	类型	说明
`id`	string	酒店标识符。
`slug`	string	URL 短标识。
`name`	string	显示名称。
`currency`	string	酒店的本位币（ISO 4217）。
`timezone`	string	IANA 时区，用于确定房价窗口里的「今天」。
`child_max_age`	integer	年龄不超过该值的客人按儿童计价。
`infant_max_age`	integer	年龄不超过该值的客人按婴儿计价。

GET /room-types

权限范围： availability:read

返回每个房型及其销售展示数据：描述、可住人数、设施、床型配置和图片（主图在前）。

curl "$VRDN_BASE/room-types" -H "Authorization: Bearer $VRDN_KEY"

{
  "data": [
    {
      "id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
      "name": "Deluxe Ocean Villa",
      "description": "A private villa over the lagoon.",
      "max_occupancy": 3,
      "currency": "USD",
      "amenities": ["Ocean view", "Private deck"],
      "bed_configs": [{ "id": "bc_king", "label": "1 King" }],
      "photos": ["https://cdn.veridien.app/p_8f2a1c/deluxe-1.jpg"]
    }
  ]
}

GET /availability

权限范围： availability:read

按房型返回该日期区间内每一晚都有的最少可用房数。只返回 max_occupancy 装得下这批客人的房型。

查询参数	必填	说明
`check_in`	是	`YYYY-MM-DD`。
`check_out`	是	`YYYY-MM-DD`，晚于 `check_in`。住宿最长 30 晚。
`adults`	是	整数 ≥ 1。
`children`	否	整数 ≥ 0，默认 `0`。
`child_ages`	否	逗号分隔的儿童年龄（例如 `5,7`）。

curl "$VRDN_BASE/availability?check_in=2026-08-01&check_out=2026-08-04&adults=2" \
  -H "Authorization: Bearer $VRDN_KEY"

{
  "check_in": "2026-08-01",
  "check_out": "2026-08-04",
  "data": [
    {
      "room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
      "name": "Deluxe Ocean Villa",
      "description": "A private villa over the lagoon.",
      "max_occupancy": 3,
      "available": 4,
      "currency": "USD",
      "amenities": ["Ocean view", "Private deck"],
      "bed_configs": [{ "id": "bc_king", "label": "1 King" }],
      "photos": ["https://cdn.veridien.app/p_8f2a1c/deluxe-1.jpg"]
    }
  ]
}

available 是你还能订出的房数。0 表示该区间内至少有一晚已售罄。

GET /rates

权限范围： availability:read

返回每个房型下可见的房价方案，以及该区间逐晚的价格拆解。这就是预订引擎要渲染的接口。

查询参数	必填	说明
`check_in`	是	`YYYY-MM-DD`。
`check_out`	是	`YYYY-MM-DD`，晚于 `check_in`。
`adults`	是	整数 ≥ 1。
`children`	否	整数 ≥ 0，默认 `0`。
`child_ages`	否	逗号分隔的儿童年龄（例如 `5,7`）。一旦传了它，它就是准确的儿童人数，并据此按年龄段计价。
`guest_id`	否	解锁与客人相关的房价（本地居民已核验、会员等级）。
`promo_code`	否	解锁需要促销码的房价。

可见性在服务端强制执行

房价方案可以带规则：仅限本地居民、需要促销码、最短住宿天数、提前预订窗口，或某个会员等级。API 会结合请求上下文评估这些规则，只返回客人有资格预订的方案。创建锁房时会重新校验同样的规则，所以一个从未展示过的方案，也无法靠 id 直接订走。

curl "$VRDN_BASE/rates?check_in=2026-08-01&check_out=2026-08-04&adults=2&promo_code=SUMMER" \
  -H "Authorization: Bearer $VRDN_KEY"

{
  "check_in": "2026-08-01",
  "check_out": "2026-08-04",
  "data": [
    {
      "room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
      "name": "Deluxe Ocean Villa",
      "description": "A private villa over the lagoon.",
      "max_occupancy": 3,
      "base_occupancy": 2,
      "amenities": ["Ocean view", "Private deck"],
      "bed_configs": [{ "id": "bc_king", "label": "1 King" }],
      "photos": ["https://cdn.veridien.app/p_8f2a1c/deluxe-1.jpg"],
      "rate_plans": [
        {
          "rate_plan_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02",
          "name": "Flexible",
          "currency": "USD",
          "total": "1260.00",
          "room_subtotal": "1260.00",
          "base_occupancy": 2,
          "extra_guest_charge": "0.00",
          "single_occupancy_discount": "0.00",
          "extra_guest_total": "0.00",
          "taxes_total": "0.00",
          "tax_breakdown": [
            { "title": "GST", "amount": "135.00", "is_inclusive": true, "rate": "12", "kind": "percent" }
          ],
          "nightly_rates": [
            { "date": "2026-08-01", "day_of_week": 6, "rate": "420.00", "source": "base_price" },
            { "date": "2026-08-02", "day_of_week": 0, "rate": "420.00", "source": "base_price" },
            { "date": "2026-08-03", "day_of_week": 1, "rate": "420.00", "source": "base_price" }
          ]
        }
      ]
    }
  ]
}

每一晚的房价都会报告它的 source：某个季节区间给这一天定了价时是 interval，回落到方案基础价时是 base_price。

房型上带有 base_occupancy（触发加人计价之前已包含的人数）和它的 bed_configs。每个房价方案都会给出完整的价格拆解：

字段	类型	说明
`total`	string	完整定价后的住宿总额，含各项外加税费。它等于锁房时的总额。
`room_subtotal`	string	各晚房价之和，未含入住人数调整与税费。
`base_occupancy`	integer	基础房价已包含的人数；超过这个人数按加人计价。
`extra_guest_charge`	string	超出 `base_occupancy` 后，每位客人每晚的加收金额。
`single_occupancy_discount`	string	单人入住时适用的折扣总额。
`extra_guest_total`	string	整段住宿的加人补收总额。
`taxes_total`	string	加进 `total` 的外加税费合计。价内税不计入这里。
`tax_breakdown`	array	逐项费用明细：`title`、`amount`、`is_inclusive`、`rate`、`kind`。价内项列出来只是为了透明，不会加进 `total`。

因为锁房用的是同一套费用引擎定价，这里的 total 始终等于 POST /holds 返回给你的总额。

GET /services

权限范围： availability:read

返回客人可预订的附加项（例如接送机），供预订引擎的「为你的房间加点服务」这一步使用。只返回启用且客人可订的服务，并带上它们的 modifiers（客人要填写的选项与信息采集字段）。传 ?category= 可按分类筛选。

查询参数	必填	说明
`category`	否	只返回该分类下的服务（例如 `transport`）。

curl "$VRDN_BASE/services?category=transport" -H "Authorization: Bearer $VRDN_KEY"

{
  "data": [
    {
      "id": "f1c8e5a3-6b2d-4c9f-8a7e-3d0b5c2f6e94",
      "name": "Airport transfer",
      "category": "transport",
      "provider_name": "Harbour Transfers",
      "image_url": "https://cdn.veridien.app/p_8f2a1c/transfer.jpg",
      "short_description": "Private speedboat from the international airport.",
      "currency": "USD",
      "is_taxable": true,
      "modifiers": []
    }
  ]
}

字段	类型	说明
`id`	string	服务标识符，在锁房的 `add_ons` 中以 `service_id` 引用。
`name`	string	显示名称。
`category`	string \| null	分类标签，供 `?category=` 筛选使用。
`provider_name`	string \| null	提供该服务的供应商。
`image_url`	string \| null	展示图片。
`short_description`	string \| null	一句话描述。
`currency`	string	计价币种，默认取酒店的本位币。
`is_taxable`	boolean	该附加项是否计税。
`modifiers`	array	客人把它加进锁房时需要填写的选项与信息采集字段（带价选项、日期时间/文本输入）。

通过 POST /holds 上的 add_ons 字段，把选中的服务挂到一次预订上。

预订：把一个房价变成锁房，再变成已确认的预订。
房价方案：房价方案与季节区间是怎么配置的。

获取酒店信息

列出房型

查询房量

查询房价

列出服务

相关页面

本页内容