Cuentas
Una cuenta es el registro de cobro en curso de una reserva. Recoge cargos (noches de habitación, impuestos, servicios) y pagos, y su saldo es lo que el huésped todavía debe. Cada reserva tiene exactamente una cuenta, a la que se accede mediante el identificador de la reserva.
Una cuenta puede llevar más de una moneda: un cargo de habitación en USD con una línea de restaurante en MVR es lo normal. Los importes en monedas distintas nunca se suman entre sí. Cada respuesta informa de balances, los importes reales por moneda, y esa es la cifra fiable. Los campos planos total_charges, total_payments y balance son una valoración de conveniencia en la moneda base del establecimiento.
GET /reservations/{id}/folioÁmbito: folio:read
El libro completo: cada línea, cada pago y los totales calculados. {id} es el identificador de la reserva.
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" }
]
}| Campo | Tipo | Notas |
|---|---|---|
status | string | settled solo cuando no se debe nada en ninguna moneda; open en los demás casos. |
currency | string | La moneda de visualización de la cuenta (la moneda de la reserva). |
base_currency | string | La moneda base del establecimiento, en la que se valoran los totales planos. |
balances | array | Importes reales por moneda, con la moneda de visualización primero. La verdad de referencia en una cuenta multidivisa. |
balances[].balance | string | charges − payments dentro de esa única moneda. |
total_charges | string | null | Cargos no incluidos en el precio y no anulados, valorados en base_currency. |
total_payments | string | null | Pagos valorados en base_currency. |
balance | string | null | total_charges − total_payments, en base_currency. |
inclusive_tax_total | string | Impuestos incluidos en el precio, mostrados aparte; no se suman al saldo. |
line_items[].quantity | integer | Unidades cobradas (noches / cantidad). Por defecto, 1. |
line_items[].unit_price | string | null | Precio por unidad; amount = quantity × unit_price. null en líneas antiguas (trátalas como amount). |
line_items[].tax_rate | string | null | Solo en las líneas de impuesto: el tipo configurado, p. ej. "12.0000" para el 12 %. null en el resto. |
line_items[].voided | boolean | Si la línea se anuló o se revirtió. |
Cómo se calcula el saldo
Los cargos solo se añaden, nunca se modifican. Un cargo anulado se registra como un asiento de reversión en lugar de borrarse, así que el libro siempre es auditable. El saldo cuenta los cargos no incluidos en el precio y no anulados menos todos los pagos; los impuestos incluidos se informan en inclusive_tax_total pero no cambian el saldo.
En una cuenta multidivisa, mira balances. Una cuenta está liquidada solo cuando cada moneda queda a cero, así que una deuda en USD nunca se cancela con un crédito en MVR.
Los totales planos pueden ser null
total_charges, total_payments y balance son valoraciones construidas a partir del tipo de cambio congelado en cada línea cuando se anotó. Si una línea está en una moneda para la que el establecimiento no tiene tipo configurado, no se puede valorar, y esos tres campos son null en lugar de un número equivocado. balances siempre está presente. Trata el caso null antes de hacer cuentas con ellos.
POST /reservations/{id}/folio/chargesÁmbito: folio:write · admite Idempotency-Key
Añade un cargo personalizado a la cuenta de una reserva: un tratamiento de spa, una comanda de restaurante cargada a la habitación, un producto del minibar. {id} es el identificador de la reserva.
Envía un amount plano, o bien un unit_price (con un quantity opcional) y el total se calcula como quantity × unit_price.
| Campo del cuerpo | Obligatorio | Notas |
|---|---|---|
description | sí | Hasta 200 caracteres. |
amount | uno de los dos | Total de la línea, cadena decimal con hasta dos decimales, p. ej. "120.00". Envía este o unit_price. |
unit_price | uno de los dos | Precio por unidad; total de la línea = unit_price × quantity. Envía este o amount. |
quantity | no | Entero ≥ 1, se usa con unit_price. Por defecto, 1. |
category | no | Una etiqueta corta (p. ej. service, restaurant). Por defecto, custom. |
currency | no | Código ISO de 3 letras. Por defecto, la moneda de la reserva. El valor en moneda base se congela al tipo vigente del establecimiento cuando se anota el cargo, así que los cambios de tipo posteriores nunca alteran el valor declarado de este cargo. |
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" }]
}La respuesta devuelve el identificador de la línea nueva y el saldo actualizado de la cuenta. folio_balance es la valoración en moneda base y es null cuando alguna línea no se puede valorar; balances lleva los importes reales por moneda. Envía una Idempotency-Key para que una petición reintentada no anote el cargo dos veces.