API 总览

Veridien API 是访问你酒店数据的 REST 接口：房量与房价、客人与会员积分、预订，以及账单。它就是驱动 Veridien 自身预订流程的那套引擎，对外开放之后，你可以在它之上自建预订引擎、客人手机应用、会员积分集成，或任何后台自动化。

这是一套朴素的 HTTP/JSON API。你用 API 密钥认证，收发 JSON，并依赖标准状态码。所有内容都限定在单家酒店的范围内，因此一把密钥只能读取或修改它所属酒店的数据。

为真实应用而建

这套 API 端到端地驱动着 Veridien 酒店的线上预订与会员积分流程：查询房量、锁定库存、注册客人、带付款确认预订、向账单入账费用，以及赚取或兑换积分。跟着快速上手把整个流程自己跑一遍。

每个请求都发往同一个带版本号的基础地址：

https://veridien.app/api/v1

本参考中的每个路径都相对于该地址。例如健康检查就是 https://veridien.app/api/v1/health。

请求通过 Authorization 头中的 Bearer API 密钥认证：

Authorization: Bearer vrdn_live_xxxxxxxxxxxxxxxxxxxx

每把密钥绑定一家酒店，并带有一组权限范围，决定它可以调用哪些接口。在仪表盘的设置 → API 密钥中创建和管理密钥。公开的元信息接口（/health、/openapi.json）无需密钥，其余接口都需要。

密钥格式、完整的权限范围列表以及一个可运行的示例，参见身份认证。

收发都是 JSON。 带请求体的请求要发送 Content-Type: application/json。字段名是 snake_case（room_type_id、check_in_date）。
金额是字符串。 金额是保留两位小数的十进制字符串（"249.00"），以避免浮点舍入。币种是 3 位 ISO 代码。
日期是字符串。 日历日期为 YYYY-MM-DD。时间戳为 ISO 8601（2026-06-19T08:30:00.000Z）。
错误结构统一。 每次失败都返回同样的 error 结构，带有可被程序识别的 code 与 request_id。
重试是安全的。 变更类请求接受 Idempotency-Key，因此一次重试不会重复扣款或重复占房。

完整规则见接口约定。

领域	接口
商品目录	酒店信息、房型、房量，以及按可见性控制的房价。参见酒店与商品目录。
优惠	列出公开的房价方案与套餐，并在报价前校验促销码。参见优惠与促销码。
客人	注册或关联客人、读取与更新档案、读取会员积分、兑换积分。参见客人与会员积分。
预订	锁定库存、把锁房确认为已付款的预订、列出与读取预订、取消。参见预订。
账单	读取一条预订的账单，并向其入账费用。参见账单。

API 的版本体现在路径里（/api/v1）。不向后兼容的改动会以新版本发布；新增性的改动（新接口、新的可选字段）在 v1 内进行。请把未知的响应字段当作新增内容忽略掉，而不是直接报错。

每个接口都有一份可被程序读取的 OpenAPI 3.1 描述，无需认证即可获取：

GET https://veridien.app/api/v1/openapi.json

用它生成带类型的客户端，或确认线上究竟部署了哪些接口和数据结构。它是准确的依据，始终与运行中的 API 保持一致。

基础地址