账单 — Veridien Docs

账单是一条预订的实时账目。它汇集各项费用（房晚、税费、服务）与付款，余额就是客人还欠的钱。每条预订只有一张账单，通过预订 id 访问。

一张账单可以同时挂着多种币种：美元的房费加上一条马尔代夫拉菲亚的餐厅明细，很常见。不同币种的金额永远不会相加。每个响应都会给出 balances，也就是各币种的实际数字，那才是可信的数字。汇总的 total_charges、total_payments 与 balance 字段，只是按酒店本位币折算的便捷估值。

GET /reservations/{id}/folio

权限范围： folio:read

返回完整账目：每一条明细、每一笔付款，以及算好的合计。{id} 是预订 id。

curl "$VRDN_BASE/reservations/7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27/folio" -H "Authorization: Bearer $VRDN_KEY"

{
  "folio_id": "1a6c3e9f-4d2b-4e8a-b5c7-9f0e6d4a2c81",
  "reservation_id": "7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27",
  "status": "settled",
  "currency": "USD",
  "base_currency": "USD",
  "balances": [
    { "currency": "USD", "charges": "1310.40", "payments": "1310.40", "balance": "0.00" }
  ],
  "total_charges": "1310.40",
  "total_payments": "1310.40",
  "balance": "0.00",
  "inclusive_tax_total": "0.00",
  "line_items": [
    { "id": "8e3b5d1c-7a9f-4b2e-a6c4-0d8f2e5b7a93", "description": "Room charge - Night 1", "amount": "420.00", "quantity": 1, "unit_price": "420.00", "date": "2026-08-01", "category": "room", "revenue_type": "hotel", "is_inclusive": false, "tax_rate": null, "currency": "USD", "voided": false },
    { "id": "4f9a1c7e-2d6b-4a3f-8b9e-6c0d5f3a8e12", "description": "GST", "amount": "50.40", "quantity": 1, "unit_price": "50.40", "date": "2026-08-01", "category": "tax", "revenue_type": "hotel", "is_inclusive": false, "tax_rate": "12.0000", "currency": "USD", "voided": false }
  ],
  "payments": [
    { "id": "b7d2f8a5-1e4c-4d9b-a3f6-8c1e0b6d4f25", "amount": "1310.40", "method": "card", "reference": "pay_abc123", "currency": "USD" }
  ]
}

字段	类型	说明
`status`	string	只有在任何币种下都不欠款时才是 `settled`，否则是 `open`。
`currency`	string	账单的显示币种（即预订的币种）。
`base_currency`	string	酒店的本位币，汇总数字按它折算。
`balances`	array	各币种的实际数字，显示币种排在最前。多币种账单上的准确依据。
`balances[].balance`	string	该币种内部的 `charges − payments`。
`total_charges`	string \| null	非价内、未作废的费用，按 `base_currency` 折算。
`total_payments`	string \| null	付款，按 `base_currency` 折算。
`balance`	string \| null	`total_charges − total_payments`，以 `base_currency` 计。
`inclusive_tax_total`	string	价内税，单独列出；不计入余额。
`line_items[].quantity`	integer	计费单位数（晚数 / 件数）。默认为 `1`。
`line_items[].unit_price`	string \| null	单价；`amount` = `quantity × unit_price`。历史明细上为 `null`（按 `amount` 处理）。
`line_items[].tax_rate`	string \| null	仅税费明细才有：配置的税率，例如 12% 记为 `"12.0000"`。其余为 `null`。
`line_items[].voided`	boolean	该明细是否已作废/冲销。

余额是怎么算出来的

费用只增不改。作废一笔费用是记一条冲销分录，而不是删除，因此账目始终可审计。余额等于非价内、未作废的费用减去全部付款；价内税在 inclusive_tax_total 中报告，但不改变余额。

在多币种账单上，请读 balances。只有每种币种都轧平到零，账单才算结清，所以一笔美元欠款绝不会被一笔拉菲亚的贷方抵消。

汇总数字可能是 null

total_charges、total_payments 与 balance 是按入账时冻结在每一行上的汇率折算出来的估值。如果某一行的币种在这家酒店没有配置汇率，它就无法折算，这三个字段会是 null，而不是一个错的数字。balances 始终存在。对它们做算术之前先处理 null。

POST /reservations/{id}/folio/charges

权限范围： folio:write · 支持 Idempotency-Key

往一条预订的账单上追加一笔自定义费用：一次水疗、一笔记到房间的餐厅订单、一件迷你吧商品。{id} 是预订 id。

要么给一个总额 amount，要么给一个 unit_price（可搭配 quantity），总额按 quantity × unit_price 算出。

请求体字段	必填	说明
`description`	是	最多 200 个字符。
`amount`	二选一	明细总额，最多两位小数的十进制字符串，例如 `"120.00"`。它与 `unit_price` 二选一。
`unit_price`	二选一	单价；明细总额 = `unit_price × quantity`。它与 `amount` 二选一。
`quantity`	否	整数 ≥ 1，与 `unit_price` 搭配使用。默认为 `1`。
`category`	否	一个简短标签（例如 `service`、`restaurant`）。默认为 `custom`。
`currency`	否	3 位 ISO 代码。默认取预订的币种。入账时会按酒店当前汇率冻结本位币金额，因此之后的汇率变动绝不会改变这笔费用的报告金额。

curl -X POST "$VRDN_BASE/reservations/7d5dc2ea-1f4e-4bfa-9a52-6c3f08b41e27/folio/charges" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: c4f8a2d1-7e9b-4c36-a1d8-3f6e0b9a2c75" \
  -d '{ "description": "Minibar - Sparkling water", "unit_price": "4.00", "quantity": 3, "category": "service" }'

{
  "line_item_id": "6d4f8b2a-9c1e-4f7d-b8a3-2e5c9f0a1d74",
  "folio_balance": "120.00",
  "balances": [{ "currency": "USD", "balance": "120.00" }]
}

响应会返回新明细的 id 和账单更新后的余额。folio_balance 是本位币估值，当某一行无法折算时为 null；balances 给出各币种的实际数字。请发送 Idempotency-Key，这样重试的请求就不会把同一笔费用入账两次。

预订：账单所归属的那条预订。
账单：账单在 Veridien 仪表盘里是怎么用的。

账单

获取一条预订的账单

入账一笔费用

相关页面

本页内容