Portal del huésped

Hasta ahora el enlace de cada reserva servía para una cosa: que el huésped se registrara y firmara. Con el portal encendido, ese mismo enlace es también la guía de la estancia, con tu marca y en el idioma del huésped. No hay un segundo enlace ni una app: lo que ya reparte tu PMS, o lo que mandan nuestros correos, lleva al portal.

Qué ve el huésped

El portal se reparte en cuatro secciones, con una barra de iconos abajo en el móvil y un menú lateral en escritorio. Solo salen las que tienen contenido, y la sección va en el enlace (#casa), así que un mensaje puede llevar directo a una de ellas.

Cada texto va por idioma: el huésped lee el suyo, si falta, el castellano, y si tampoco, el que haya. Las categorías, los temas del manual y los tipos de teléfono se traducen solos; los nombres propios (un restaurante, un taxi) no.

Cuándo se abren los códigos

Las instrucciones de acceso, los códigos y el wifi van detrás de un candado que se abre cuando se cumplen dos condiciones a la vez:

Los códigos no viajan con la página: el huésped pulsa «Mostrar los códigos» y se piden en ese momento. Cada vez queda apuntada —cuándo, desde qué red (recortada: sin el último octeto) y por qué se pudo— durante 90 días, y se consulta por API. Lo que no se guarda nunca en ese registro son los códigos en sí.

Desbloquear ya. El huésped está en la puerta y no ha firmado: un botón en la ficha de la reserva —y una llamada a la API— abre el acceso sin esperar al registro ni a la ventana. Queda registrado quién lo abrió y cuándo, se cierra igual al acabar el día de salida, y se puede deshacer.

Encenderlo y ajustarlo

En el panel, Portal del huésped → Ajustes. Por API, el objeto guestPortal de /settings. Como el resto de los ajustes, solo cambia lo que mandes.

curl -X PATCH https://api.kinapi.es/api/v1/settings \
  -H "ocp-apim-subscription-key: TU_API_KEY" \
  -H "content-type: application/json" \
  -d '{"guestPortal":{"enabled":true,"hoursBefore":24,"phone":"+34600000000"}}'

Lo común, los bloques y lo propio

Cincuenta propiedades no se rellenan una a una. Siete secciones del portal se pueden compartir —la llegada, el aparcamiento, el manual de la casa, las normas, la zona, la salida y los teléfonos útiles— y se escriben en tres sitios:

Para cada sección de cada propiedad se decide de dónde sale, y la regla es siempre la misma:

En el panel, el apartado Portal del huésped del menú tiene tres pestañas: Propiedades (una tabla con el estado de cada sección en cada propiedad —✓ propio, ≡ común, ⧉ bloque— y la asignación en bloque de una variante a varias propiedades), Común y Ajustes. En cada propiedad, cada sección compartible lleva su selector —común, una variante, propio o escondida—, y la ficha tiene «Copiar de otra propiedad» (todo menos códigos y wifi) y «Anterior / Siguiente» para recorrer el parque sin volver a la lista.

Lo común de la cuenta

El PUT sustituye todo lo común: la sección que no mandes se borra. Lee, cambia y escribe. En la lectura solo vienen las secciones con contenido.

curl -X PUT https://api.kinapi.es/api/v1/portal/common \
  -H "ocp-apim-subscription-key: TU_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "departure": { "es": "Deja las llaves en la caja y cierra la puerta al salir.", "en": "Leave the keys in the box and shut the door behind you." },
    "showHouseRules": true,
    "usefulNumbers": [
      { "type": "taxi", "name": "Radio Taxi", "number": "+34 956 000 000" },
      { "type": "centroSalud", "number": "+34 956 111 111" }
    ]
  }'

Bloques

curl -X POST https://api.kinapi.es/api/v1/portal/blocks \
  -H "ocp-apim-subscription-key: TU_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "section": "parking",
    "name": "Parking Alameda",
    "content": {
      "parking": { "es": "Plaza 14 del parking de la Alameda, a 200 m. El mando abre la barrera.", "en": "Bay 14 at the Alameda car park, 200 m away. The remote opens the barrier." },
      "parkingMapUrl": "https://maps.app.goo.gl/…"
    },
    "propertyIds": ["b8f3a2c1-…", "5c7d9e01-…"]
  }'

{
  "id": "3f9c…",
  "section": "parking",
  "name": "Parking Alameda",
  "content": { "parking": { "es": "…", "en": "…" }, "parkingMapUrl": "https://maps.app.goo.gl/…" },
  "propertyIds": ["b8f3a2c1-…", "5c7d9e01-…"],
  "updatedAt": "2026-10-23T10:00:00.000Z"
}

El id es lo que va en los origins de una propiedad como block:3f9c…. Borrar un bloque devuelve sus propiedades a lo suyo o a lo común; no borra nada de ellas.

El portal de una propiedad

Lo propio de cada alojamiento: las secciones compartibles de arriba, más lo que solo puede ser suyo y de dónde sale cada sección. El PUT sustituye el portal entero, códigos y wifi incluidos: lo que no mandes se borra.

curl -X PUT https://api.kinapi.es/api/v1/properties/b8f3a2c1-…/portal \
  -H "ocp-apim-subscription-key: TU_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "houseMapUrl": "https://maps.app.goo.gl/…",
    "arrival": { "es": "Portal verde junto a la farmacia. 2.º izquierda.", "en": "Green street door next to the pharmacy. 2nd floor, left." },
    "access": { "es": "La caja de llaves está a la derecha del portal; el código del portal abre también el garaje." },
    "codes": [ { "type": "portal", "value": "4821" }, { "type": "cajaLlaves", "value": "0719" } ],
    "wifi": { "network": "Sol3B", "password": "tarifa-2026" },
    "manual": { "climatizacion": { "es": "El termostato está en el pasillo; 21 ºC es suficiente." } },
    "origins": { "parking": "block:3f9c…", "area": "hidden" }
  }'

{
  "propertyId": "b8f3a2c1-…",
  "houseMapUrl": "https://maps.app.goo.gl/…",
  "arrival": { "es": "…", "en": "…" },
  "access": { "es": "…" },
  "codes": [ { "type": "portal", "value": "4821" }, { "type": "cajaLlaves", "value": "0719" } ],
  "wifi": { "network": "Sol3B", "password": "tarifa-2026" },
  "manual": { "climatizacion": { "es": "…" } },
  "origins": {
    "arrival": { "source": "own" },
    "parking": { "source": "block", "blockId": "3f9c…" },
    "manual": { "source": "own" },
    "houseRules": { "source": "common" },
    "area": { "source": "hidden" },
    "departure": { "source": "common" },
    "usefulNumbers": { "source": "common" }
  },
  "updatedAt": "2026-10-23T10:05:00.000Z"
}

El acceso de una reserva

Si el huésped de una reserva ya puede ver los códigos, desde o hasta cuándo, si alguien lo desbloqueó a mano y cuándo los ha visto. El POST es «Desbloquear ya» —queda firmado api: más la etiqueta de tu clave— y el DELETE lo deshace. Los tres devuelven el mismo objeto; nunca los códigos, que son de la propiedad.

{
  "enabled": true,
  "state": "open",
  "closesAt": "2026-08-18T21:59:59.999Z",
  "openedBy": "unlock",
  "unlocked": { "at": "2026-08-14T13:02:11.000Z", "by": "api:PMS" },
  "reveals": [
    { "at": "2026-08-14T15:40:02.000Z", "network": "83.45.12.0", "reason": "unlock" }
  ]
}

Una reserva cancelada no se desbloquea: 409 cancelled. No hay eventos nuevos de webhook: checkin.completed sigue siendo el momento en que el acceso se abre, si la reserva ya está en ventana.

Las horas de entrada y salida

La ventana de los códigos y lo que lee el huésped en Estancia dependen de la hora de entrada y de salida de la reserva, y esa hora se resuelve en cascada: la reserva → la propiedad → la cuenta → 16:00 / 11:00. Una reserva que trae su hora la conserva; la que no, hereda la de la propiedad (checkInTime y checkOutTime en /properties), y si la propiedad no tiene, la de la cuenta (stay en /settings).

Desde un agente

El servidor MCP tiene una herramienta por cada operación de arriba, para configurar el portal hablando:

«Pon en lo común que las llaves se dejan en la caja y que se enseñen las normas de la casa»
«Crea un bloque de aparcamiento “Parking Alameda” con este texto y asígnalo a los seis pisos de la calle Alameda»
«¿Ha visto ya los códigos el huésped de la reserva 4821?»
«El huésped de la 4821 está en la puerta y no ha firmado: ábrele el acceso»