Autenticación
Cada petición autenticada lleva una clave de API bearer. La clave identifica el establecimiento sobre el que actúas y los ámbitos que puedes usar. No hay nombres de usuario, ni contraseñas, ni flujos OAuth: una clave por integración.
Una clave de API de Veridien tiene este aspecto:
vrdn_live_xxxxxxxxxxxxxxxxxxxx- Lleva el prefijo
vrdn_live_. - Se muestra una sola vez, al crearla. Veridien guarda solo un hash SHA-256 de la clave; nunca se puede recuperar, solo revocar y sustituir.
- Está vinculada a un establecimiento. El establecimiento va implícito en la clave, así que ningún endpoint te pide un identificador de establecimiento.
Trata las claves como contraseñas
Una clave concede sus ámbitos sobre los datos reales de tu establecimiento. Guárdala en un almacén de secretos del servidor o en una variable de entorno, nunca en código de cliente ni en un repositorio público. Si una clave se filtra, revócala de inmediato y emite una nueva.
Crea las claves en el panel, en Ajustes → Claves de API:
- Haz clic en Crear clave y ponle un nombre descriptivo (por ejemplo,
Sunrise Bay booking engine). - Selecciona los ámbitos que necesita la integración, concediendo el mínimo imprescindible.
- Copia la clave que aparece en el cuadro de confirmación y guárdala en un sitio seguro. No se volverá a mostrar.
Las claves se pueden revocar en cualquier momento desde esa misma pantalla. Una clave revocada deja de funcionar al instante; las peticiones que la usen devuelven 401.
Pon la clave en la cabecera Authorization de cada petición:
curl https://veridien.app/api/v1/me \
-H "Authorization: Bearer vrdn_live_xxxxxxxxxxxxxxxxxxxx"Una llamada correcta a /me confirma que la clave funciona e informa de su establecimiento y sus ámbitos:
{
"property_id": "p_8f2a1c",
"property_slug": "sunrise-bay",
"scopes": ["availability:read", "reservations:write", "folio:write"],
"request_id": "req_a1b2c3d4e5"
}Si falta la cabecera o está mal formada, obtienes 401 missing_api_key; si la clave es desconocida, está desactivada o ha caducado, obtienes 401 invalid_api_key.
Una clave solo puede llamar a un endpoint si tiene el ámbito de ese endpoint. Llamar a un endpoint sin su ámbito devuelve 403 insufficient_scope. Los ámbitos siguen la forma resource:action.
| Ámbito | Concede |
|---|---|
availability:read | Leer disponibilidad y tarifas (/availability, /rates, /room-types, /services y las ofertas publicadas). |
rates:read | Leer los recursos de gestión de tarifas (GET /rate-plans/{id}/intervals, /inclusions, /promo-codes). Los endpoints de lectura de precios (/rates, /rate-plans) aceptan availability:read. |
rates:write | Crear, actualizar y borrar tarifas y promociones, intervalos de temporada, inclusiones y créditos, y códigos promocionales (/rate-plans, /intervals, /promo-codes). |
reservations:read | Listar y leer reservas (/reservations, /reservations/{id}). |
reservations:write | Crear bloqueos, confirmar reservas y cancelar (/holds, /holds/{id}/confirm, /reservations/{id}/cancel). |
guests:read | Leer perfiles de huéspedes, sin los datos personales. |
guests:read:pii | Devolver además los datos personales del huésped (correo, teléfono, dirección, documento). |
guests:write | Registrar, vincular y actualizar huéspedes (POST /guests, PATCH /guests/{id}). |
loyalty:read | Leer el saldo de fidelidad, el nivel y el histórico de un huésped. |
loyalty:write | Canjear puntos de fidelidad (/loyalty/redemptions). |
folio:read | Leer la cuenta de una reserva. |
folio:write | Anotar cargos en una cuenta (/reservations/{id}/folio/charges). |
webhooks:manage | Reservado para la futura gestión de suscripciones a webhooks. |
Mínimo privilegio
Concede solo los ámbitos que necesita una integración. Un widget de disponibilidad de solo lectura necesita únicamente availability:read; un motor de reservas completo suele necesitar availability:read, guests:write, reservations:write y folio:write, además de loyalty:* si muestra puntos.
Los perfiles de huésped se dividen en una vista base y una vista con datos personales. Con guests:read recibes los identificadores y los campos no sensibles (nombre, nacionalidad, estado, indicador de verificación como residente local). Para recibir además email, phone, address y los campos del documento, la clave debe tener también guests:read:pii. Esto te permite construir, por ejemplo, un widget público que lea el estado del huésped sin exponer nunca sus datos de contacto.
Dos endpoints meta no necesitan clave ni ámbito:
GET /health: una sonda de vida que devuelve{ "status": "ok" }.GET /openapi.json: el esquema OpenAPI 3.1 de toda la API.
Todo lo demás requiere una clave válida con el ámbito correspondiente.
- Convenciones: errores, idempotencia, paginación y límites de uso.
- Inicio rápido: un flujo de reserva completo, de la clave a la reserva confirmada.