Gestión de tarifas

Los endpoints de catálogo y de ofertas son de solo lectura. Estos endpoints permiten que una integración gestione el conjunto de tarifas: crear tarifas, superponer precios de temporada, agrupar inclusiones y créditos, y lanzar promociones con códigos. Son la forma que tiene un hotel de dirigir sus precios de Veridien desde su propia web o su back office.

Todos los endpoints de esta página requieren el ámbito rates:write, salvo las lecturas de gestión (GET), que requieren rates:read.

Una promoción es una tarifa

Una promoción es una tarifa con kind: "promotion" y una derivación a partir de una tarifa base. No hay un endpoint de promociones aparte: creas y editas una a través de los mismos endpoints /rate-plans, indicando kind, derived_from_id, derivation_type y derivation_value.

Idempotencia

Cada escritura de aquí es una petición que modifica datos. Envía una cabecera Idempotency-Key para que los reintentos sean seguros, como se describe en Convenciones.

POST /rate-plans

Campo	Obligatorio	Notas
`room_type_id`	sí	El tipo de habitación al que pone precio esta tarifa.
`name`	sí	Nombre interno (de 1 a 100 caracteres).
`base_price`	sí	Precio por noche como cadena decimal, por ejemplo `"120.00"`.
`currency`	no	Debe ser la moneda base del establecimiento o una moneda configurada. Por defecto, la base.
`public_name`	no	Nombre visible para el huésped.
`description`	no	Texto comercial para el huésped.
`image_url`	no	URL absoluta.
`extra_guest_charge`	no	Cargo por noche por cada huésped por encima de la ocupación base. Por defecto, `"0.00"`.
`single_guest_discount`	no	Por defecto, `"0.00"`.
`single_guest_discount_type`	no	`fixed` o `percent`. Por defecto, `fixed`.
`min_los` / `max_los`	no	Límites de duración de la estancia, en noches.
`booking_window_start` / `_end`	no	Cuándo se puede reservar la tarifa (`YYYY-MM-DD`).
`stay_window_start` / `_end`	no	Cuándo se puede disfrutar la estancia con esta tarifa.
`active_for_booking_engine`	no	Por defecto, `false`.
`active_for_channels`	no	Por defecto, `false`.
`kind`	no	`standard` (por defecto) o `promotion`.
`derived_from_id`	no	Para una promoción: la tarifa base de la que deriva.
`derivation_type`	no	`percent`, `fixed` o `perPerson`. Obligatorio junto con `derived_from_id`.
`derivation_value`	no	Cadena decimal con signo. Un valor negativo es un descuento, por ejemplo `"-20.00"`. Obligatorio junto con `derived_from_id`.

curl -X POST "$VRDN_BASE/rate-plans" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
    "name": "Bed & Breakfast",
    "base_price": "120.00",
    "public_name": "Bed & Breakfast",
    "description": "A full breakfast for two each morning.",
    "active_for_booking_engine": true
  }'

{ "rate_plan_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02" }

Indica kind, la tarifa madre y una derivación negativa. Protégela con un código añadiendo uno (más abajo) y poniendo requires_promo_code: true.

curl -X POST "$VRDN_BASE/rate-plans" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "room_type_id": "9b2f6c3e-8d1a-4f5b-a7c9-4e0d2b8f1a63",
    "name": "Advance Purchase, save 20%",
    "base_price": "120.00",
    "kind": "promotion",
    "derived_from_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02",
    "derivation_type": "percent",
    "derivation_value": "-20.00",
    "active_for_booking_engine": true
  }'

Una tarifa derivada necesita a la vez derivation_type y derivation_value, o la petición se rechaza. Su precio es siempre el precio actual de la tarifa madre con la derivación aplicada, así que sigue automáticamente los precios de temporada de la madre.

PATCH /rate-plans/{id}

Envía solo los campos que quieres cambiar. Acepta los mismos campos que la creación (salvo room_type_id), más is_active.

{ "rate_plan_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02", "updated": true }

DELETE /rate-plans/{id}

La tarifa por defecto no se puede borrar (403). Las reservas ya hechas con una tarifa borrada conservan el precio que se les dio.

{ "rate_plan_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02", "deleted": true }

Los intervalos superponen precios y reglas de estancia por fechas sobre el precio base de una tarifa. Los intervalos de una misma tarifa no pueden solaparse; un rango que se solape devuelve 409.

GET /rate-plans/{id}/intervals

Requiere rates:read.

POST /rate-plans/{id}/intervals

Campo	Obligatorio	Notas
`name`	sí	Por ejemplo "High Season".
`start_date` / `end_date`	sí	`YYYY-MM-DD`. El inicio debe ser anterior al fin.
`price_mon` … `price_sun`	no	Precio por día de la semana. Un día en blanco vuelve al precio base.
`min_stay` / `max_stay`	no	Reglas de duración de la estancia para este rango.
`closed_to_arrival` / `closed_to_departure` / `stop_sell`	no	Indicadores de disponibilidad. Por defecto, `false`.
`extra_guest_charge` / `single_guest_discount`	no	Valores propios de la temporada. Por defecto, `"0.00"`.

curl -X POST "$VRDN_BASE/rate-plans/5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02/intervals" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High Season",
    "start_date": "2026-12-01",
    "end_date": "2027-03-31",
    "price_mon": "180.00", "price_fri": "210.00",
    "min_stay": 3
  }'

{ "interval_id": "d8a4c2f6-5e9b-4d7a-8f1c-3b6e0a9d5c28" }

PATCH /intervals/{id}
DELETE /intervals/{id}

PATCH acepta cualquier campo del intervalo y vuelve a comprobar la regla de no solapamiento.

Una inclusión es una ventaja (un elemento incluido fijo) o un crédito (un saldo gastable en una categoría, como un crédito de spa). Las inclusiones se fijan como lista completa: un POST sustituye todo el conjunto de inclusiones de la tarifa.

GET /rate-plans/{id}/inclusions

Requiere rates:read.

POST /rate-plans/{id}/inclusions

Campo	Obligatorio	Notas
`label`	sí	Etiqueta visible para el huésped, por ejemplo "Spa credit".
`allocated_amount`	sí	Valor como cadena decimal. `"0.00"` para una ventaja gratuita.
`frequency`	sí	`perStay`, `perNight`, `perGuest` o `perGuestPerNight`.
`inclusion_kind`	no	`perk` (por defecto) o `credit`.
`revenue_category`	sí	`room`, `fnb`, `spa`, `excursions`, `activities` u `other`. En un crédito, es la categoría a la que se aplica.
`service_item_id`	no	Enlace a un servicio del catálogo.
`currency`	no	Por defecto, la moneda de la tarifa.
`included_quantity`	no	Por defecto, 1.

curl -X POST "$VRDN_BASE/rate-plans/5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02/inclusions" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "inclusions": [
      { "label": "Daily breakfast for two", "allocated_amount": "20.00", "frequency": "perGuestPerNight", "revenue_category": "fnb" },
      { "label": "Spa credit", "allocated_amount": "150.00", "frequency": "perStay", "inclusion_kind": "credit", "revenue_category": "spa" }
    ]
  }'

{ "rate_plan_id": "5c1e8f4a-2b7d-4a9c-8e6f-1d3b9a5c7e02", "count": 2 }

Un código desbloquea una promoción. El descuento vive en la promoción, así que un código nunca lleva un ahorro propio. Asocia los códigos a la tarifa que desbloquean.

GET /rate-plans/{id}/promo-codes

Requiere rates:read.

POST /rate-plans/{id}/promo-codes

Campo	Obligatorio	Notas
`code`	sí	De 3 a 40 caracteres. Se guarda y se compara en mayúsculas.
`valid_from` / `valid_to`	no	Ventana `YYYY-MM-DD`.
`max_redemptions`	no	Tope de usos totales. Omítelo para dejarlo sin límite.
`max_per_guest`	no	Tope por huésped.

curl -X POST "$VRDN_BASE/rate-plans/e2a9d7c4-3f6b-4c1e-9a8d-7b5f0c2e4a19/promo-codes" \
  -H "Authorization: Bearer $VRDN_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "code": "EARLYBIRD25", "max_redemptions": 100 }'

{ "promo_code_id": "a5e2c8f1-7d4b-4a6e-b9c3-0f8d2a5e7c41", "code": "EARLYBIRD25" }

PATCH /promo-codes/{id}
DELETE /promo-codes/{id}

PATCH acepta valid_from, valid_to, max_redemptions, max_per_guest e is_active. La cadena del código en sí no se puede cambiar, porque las reservas congelan el código con el que se hicieron; bórralo y crea uno nuevo en su lugar. Borrar un código no afecta a las reservas ya hechas con él.

Crear una tarifa

Crear una promoción

Actualizar una tarifa

Borrar una tarifa

Intervalos de temporada

Listar los intervalos

Crear un intervalo

Actualizar y borrar un intervalo

Inclusiones y créditos

Listar las inclusiones

Sustituir las inclusiones

Códigos promocionales

Listar los códigos

Crear un código

Actualizar y borrar un código

En esta página