Integración PMS por SFTP

Conexión SFTP, contrato de ficheros y ejemplos de intercambio con el PMS.

SFTP · Intercambio de ficheros

Conexión y puesta en marcha

Solicita al responsable de la integración el servidor, puerto, usuario, contraseña y carpeta SFTP del hotel, su zona horaria y los números de habitación que debes utilizar.
Conecta mediante SFTP. La cuenta accede únicamente al directorio del hotel. Utiliza la carpeta de intercambio indicada para tu cuenta.
Lee ENVIO.txt y escribe las órdenes en RECEPCION.txt. Ambos nombres son exactos y distinguen mayúsculas.
Envía una orden de prueba, espera el siguiente ciclo de procesamiento y comprueba el resultado en ENVIO.txt. Coordina esta prueba con el responsable de la integración.

Formato y escritura

UTF-8, una línea completa por orden, terminada en salto de línea (LF o CRLF). Claves CLAVE=VALOR separadas por |. No incluyas | ni saltos de línea dentro de un valor. Las claves se normalizan a mayúsculas y los espacios exteriores se eliminan.

Abre, añade las nuevas líneas completas en modo append y cierra el fichero en cada envío. No mantengas el fichero abierto entre lotes; vuelve a abrirlo para cada envío. El ciclo nominal es de 15 segundos.

Resumen

ENVIO.txt

Archivo generado por Hospitality. Contiene eventos en orden cronológico ascendente, de arriba a abajo.

RECEPCION.txt

Archivo escrito por el PMS del hotel. Cada línea es una orden que el sistema lee y aplica automáticamente.

Codificación

UTF-8, una orden o evento por línea, formato CLAVE=VALOR|CLAVE=VALOR.

ENVIO.txt

El sistema publica un único flujo histórico de eventos con las categorias stay, services y cdr. Solo se incluyen los campos necesarios para la operativa del PMS.

Reglas

Orden cronológico ascendente: la primera línea es la más antigua y la ultima la más reciente.
Una línea = un evento.
Los eventos de estancias, servicios y CDR conviven en el mismo fichero.
Cada evento incluye solo los campos que le aplican; no se rellenan columnas vacías.
El PMS debe interpretarlo como histórico. El fichero puede regenerarse: no debe asumir que cada descarga contiene solo novedades ni deduplicar únicamente por número de línea.

Campos base

Campo	Descripción
`OCCURRED_AT`	Fecha y hora ISO del evento en la zona horaria del hotel, con offset.
`CATEGORY`	`stay`, `services` o `cdr`.
`EVENT`	Tipo de evento. Ejemplos: `checkin`, `checkout`, `room_change_in`, `wakeup_set`, `cdr`.
`ROOM`	Número de habitación.

Catálogo de eventos

Categoría	Evento	Descripción
`stay`	`checkin`	Entrada de habitación.
`stay`	`checkin_update`	Actualización de una estancia ya abierta.
`stay`	`room_change_out`	Salida operativa de una estancia por traslado a otra habitación.
`stay`	`room_change_in`	Entrada operativa de una estancia trasladada desde otra habitación.
`stay`	`checkout`	Salida de habitación, con factura/recibo si aplica.
`stay`	`stay_snapshot`	Evento legacy de reconstrucción histórica.
`services`	`housekeeping`	Cambio del estado de limpieza de la habitación.
`services`	`housekeeping_snapshot`	Estado heredado al inicializar el histórico.
`services`	`housekeeping_reset`	Reset diario de limpieza a `pending` a las 05:00.
`services`	`wakeup_set`	Alta de despertador con fecha y hora.
`services`	`wakeup_clear`	Borrado manual o cierre automatico de despertadores fallidos/vencidos.
`services`	`wakeup_triggered`	Solicitud de despertador ejecutada por la centralita. No equivale por sí sola a una confirmación de que el huésped haya contestado.
`services`	`wakeup_pending`	Resultado de la solicitud pendiente de confirmar por CDR. `CODE=PENDING_CONFIRMATION`.
`services`	`wakeup_result`	Resultado confirmado por CDR: `CODE=ANSWERED` o `CODE=NO_ANSWER`.
`cdr`	`cdr`	Registro de llamada con tarificacion y estado de cobro.

Campos habituales por tipo

Estancias: GUEST (debe contener nombre y apellidos), STAY_CHECKIN_DATE, STAY_CHECKOUT_DATE, CHECKIN_AT, CHECKOUT_AT, OUTBOUND_ENABLED, SOURCE.
Traslados de estancia: FROM_ROOM, FROM_EXTENSION, TO_ROOM, TO_EXTENSION, MOVED_CALLS, MOVED_WAKEUPS.
Servicios: HOUSEKEEPING, WAKEUP_ENABLED, WAKEUP_DATE, WAKEUP_TIME, SOURCE, CODE.
Llamadas: CALLDATE, SRC, DST, DISPOSITION, BILLSEC, OUTBOUND, RATE, AMOUNT, BILLED, UNIQUEID, LINKEDID.

En wakeup_clear, el campo opcional CODE=FAILED indica que el sistema ha cerrado automáticamente un wakeup vencido o no ejecutable. Si CODE no aparece, el borrado fue operativo/manual.

Ejemplos

OCCURRED_AT=2026-03-10T09:12:00.000+01:00|CATEGORY=stay|EVENT=checkin|ROOM=101|GUEST=Juan Pérez|STAY_CHECKIN_DATE=2026-03-10|STAY_CHECKOUT_DATE=2026-03-12|OUTBOUND_ENABLED=1|SOURCE=pms
OCCURRED_AT=2026-03-10T09:14:00.000+01:00|CATEGORY=services|EVENT=wakeup_set|ROOM=101|WAKEUP_ENABLED=1|WAKEUP_DATE=2026-03-11|WAKEUP_TIME=07:30|SOURCE=pms
OCCURRED_AT=2026-03-10T09:15:00.000+01:00|CATEGORY=services|EVENT=housekeeping|ROOM=101|HOUSEKEEPING=clean|SOURCE=pbx-code
OCCURRED_AT=2026-03-10T09:20:00.000+01:00|CATEGORY=cdr|EVENT=cdr|ROOM=101|CALLDATE=2026-03-10T09:20:00.000+01:00|SRC=101|DST=0971123456|DISPOSITION=ANSWERED|BILLSEC=64|OUTBOUND=1|RATE=Móvil nacional|AMOUNT=0.51|BILLED=0
OCCURRED_AT=2026-03-11T08:05:00.000+01:00|CATEGORY=services|EVENT=wakeup_clear|ROOM=101|WAKEUP_ENABLED=0|WAKEUP_DATE=2026-03-11|WAKEUP_TIME=07:30|SOURCE=scheduler|CODE=FAILED
OCCURRED_AT=2026-03-11T18:20:00.000+01:00|CATEGORY=stay|EVENT=room_change_in|ROOM=202|GUEST=Juan Pérez|FROM_ROOM=101|FROM_EXTENSION=101|MOVED_CALLS=2|MOVED_WAKEUPS=1|SOURCE=pms
OCCURRED_AT=2026-03-11T18:20:00.000+01:00|CATEGORY=stay|EVENT=room_change_out|ROOM=101|GUEST=Juan Pérez|TO_ROOM=202|TO_EXTENSION=202|MOVED_CALLS=2|MOVED_WAKEUPS=1|SOURCE=pms
OCCURRED_AT=2026-03-12T10:00:00.000+01:00|CATEGORY=stay|EVENT=checkout|ROOM=101|GUEST=Juan Pérez|CHECKOUT_AT=2026-03-12T10:00:00.000+01:00|OUTBOUND_ENABLED=0|SOURCE=pms

RECEPCION.txt

El PMS debe escribir órdenes en este fichero. Hospitality las procesa automáticamente. El fichero es una bandeja temporal: su contenido puede vaciarse tras la lectura.

Reglas

Una línea = una orden.
Formato obligatorio CLAVE=VALOR|CLAVE=VALOR|....
Escribe únicamente órdenes nuevas al final del fichero y no reenvíes lotes ya aplicados.
El integrador debe tratar RECEPCION.txt como cola transitoria de append, no como histórico ni como snapshot completo.
No usar el caracter | dentro de valores.
El sistema procesa las lineas por orden de aparicion en el fichero.
Las acciones validas afectan a estancia y despertador. La limpieza es solo de lectura.
Las lineas de traslado deben identificar claramente origen y destino; no se recomienda reutilizar ROOM para ambos.

Acciones soportadas

ACTION	Descripción	Campos requeridos
`CHECKIN`	Abre una estancia o actualiza una ya abierta. Marca la habitación como ocupada y habilita permisos de salida segun `OUTBOUND_ENABLED`.	`ROOM`, nombre/apellidos o `GUEST` (debe contener nombre y apellidos), `STAY_CHECKIN_DATE`, `STAY_CHECKOUT_DATE`
`CHECKOUT`	Cierra la estancia, factura llamadas y libera la habitación. Los wakeups pendientes se conservan.	`ROOM`
`ROOM_MOVE`	Mueve una estancia activa a otra habitación libre y arrastra sus wakeups pendientes y llamadas no facturadas.	`FROM_ROOM` y `TO_ROOM`
`WAKEUP_SET`	Programa un despertador. Se pueden crear varios por habitación. No requiere que la habitación tenga check-in activo en Hospitality.	`ROOM`, `DATE`, `TIME`
`WAKEUP_CLEAR`	Elimina despertadores pendientes. Si se informa `DATE` y `TIME`, borra solo ese; si no, borra todos los pendientes de la habitación.	`ROOM`

También se aceptan como alias de traslado: ROOM_CHANGE, CHANGE_ROOM, MOVE_ROOM y TRANSFER_ROOM.

Identificación de habitación

Para acciones simples se admite ROOM, ROOM_NUMBER, EXT o EXTENSION. Recomendado usar siempre ROOM.

Para traslados se admite identificar origen con FROM_ROOM o FROM_EXT/OLD_EXT, y destino con TO_ROOM o TO_EXT/NEW_EXT.

Formatos

Fechas: YYYY-MM-DD
Horas: HH:MM
Lectura de limpieza en ENVIO.txt: HOUSEKEEPING=clean o HOUSEKEEPING=pending
Permiso de salida: OUTBOUND_ENABLED=1 o 0
Un mismo cuarto puede tener varios wakeups pendientes en fechas y horas distintas.
Los wakeups se intentan ejecutar a su hora aunque la habitación siga libre en Hospitality.
Un traslado solo se aplica si la habitación origen está ocupada y la destino está libre.
Un traslado se rechaza si la habitación destino ya tiene wakeups pendientes o llamadas sin facturar.

Ejemplos

ACTION=CHECKIN|ROOM=101|GUEST_FIRST_NAME=Juan|GUEST_LAST_NAME=Pérez|STAY_CHECKIN_DATE=2026-03-10|STAY_CHECKOUT_DATE=2026-03-12|OUTBOUND_ENABLED=1
ACTION=WAKEUP_SET|ROOM=101|DATE=2026-03-11|TIME=07:30
ACTION=WAKEUP_SET|ROOM=101|DATE=2026-03-12|TIME=08:00
ACTION=WAKEUP_CLEAR|ROOM=101|DATE=2026-03-11|TIME=07:30
ACTION=ROOM_MOVE|FROM_ROOM=101|TO_ROOM=202
ACTION=CHECKOUT|ROOM=101

Campos admitidos de CHECKIN

Campo	Descripción
`GUEST`	Nombre completo. Solo se usa si no vienen `GUEST_FIRST_NAME` y `GUEST_LAST_NAME`.
`GUEST_FIRST_NAME`	Nombre del huésped.
`GUEST_LAST_NAME`	Apellidos del huésped.
`CHECKIN_DATE`	Alias aceptado de `STAY_CHECKIN_DATE`.
`CHECKOUT_DATE`	Alias aceptado de `STAY_CHECKOUT_DATE`.
`OUTBOUND_ENABLED`	`1` o `0`. Si no se informa, se asume `1`.
`ALLOW_OUTBOUND`	Alias aceptado de `OUTBOUND_ENABLED`.

Campos admitidos de ROOM_MOVE

Campo	Descripción
`FROM_ROOM`	Habitacion origen recomendada.
`TO_ROOM`	Habitacion destino recomendada.
`FROM_EXT`	Alias aceptado para identificar la extension origen.
`TO_EXT`	Alias aceptado para identificar la extension destino.
`OLD_ROOM`	Alias aceptado de `FROM_ROOM`.
`NEW_ROOM`	Alias aceptado de `TO_ROOM`.
`OLD_EXT`	Alias aceptado de `FROM_EXT`.
`NEW_EXT`	Alias aceptado de `TO_EXT`.
`TARGET_ROOM`	Alias aceptado de `TO_ROOM`.
`TARGET_EXT`	Alias aceptado de `TO_EXT`.

Observaciones operativas

Hospitality procesa RECEPCION.txt automáticamente en ciclos de 15 segundos.
Una línea inválida no impide procesar las demás órdenes del lote.
Las órdenes aplicadas por el PMS aparecen despues reflejadas en ENVIO.txt.
El PMS debe considerar RECEPCION.txt una bandeja temporal de entrada y escribir siempre en modo append.
Los wakeups del PMS se ejecutan aunque no exista check-in local. Si vencen sin ejecutarse o la PBX no está disponible, el sistema los cierra y publica wakeup_clear con CODE=FAILED.
El checkout conserva los despertadores pendientes. Esto permite cerrar la línea antes de la salida sin perder el despertador del dia siguiente.
En un cambio de habitación, los wakeups pendientes y las llamadas no facturadas siguen a la estancia y cambian de habitación.

Casos de uso

1. Check-in de habitación

El PMS escribe en RECEPCION.txt:

ACTION=CHECKIN|ROOM=101|GUEST_FIRST_NAME=Juan|GUEST_LAST_NAME=Pérez|STAY_CHECKIN_DATE=2026-03-10|STAY_CHECKOUT_DATE=2026-03-12|OUTBOUND_ENABLED=1

El sistema aplica el check-in y despues publica en ENVIO.txt un evento similar a:

OCCURRED_AT=2026-03-10T09:12:00.000+01:00|CATEGORY=stay|EVENT=checkin|ROOM=101|GUEST=Juan Pérez|STAY_CHECKIN_DATE=2026-03-10|STAY_CHECKOUT_DATE=2026-03-12|OUTBOUND_ENABLED=1|SOURCE=pms

2. Programación de despertador

El PMS escribe en RECEPCION.txt:

ACTION=WAKEUP_SET|ROOM=101|DATE=2026-03-11|TIME=07:30
ACTION=WAKEUP_SET|ROOM=101|DATE=2026-03-12|TIME=08:00

El sistema programa los wakeups y publica en ENVIO.txt. La ejecucion no depende de que la habitación tenga check-in activo en Hospitality:

OCCURRED_AT=2026-03-10T09:14:00.000+01:00|CATEGORY=services|EVENT=wakeup_set|ROOM=101|WAKEUP_ENABLED=1|WAKEUP_DATE=2026-03-11|WAKEUP_TIME=07:30|SOURCE=pms
OCCURRED_AT=2026-03-10T09:14:05.000+01:00|CATEGORY=services|EVENT=wakeup_set|ROOM=101|WAKEUP_ENABLED=1|WAKEUP_DATE=2026-03-12|WAKEUP_TIME=08:00|SOURCE=pms

Cuando la centralita confirma la ejecución de la solicitud, el sistema publica el siguiente evento. Este evento no garantiza por sí solo que la habitación haya contestado:

OCCURRED_AT=2026-03-11T07:30:00.000+01:00|CATEGORY=services|EVENT=wakeup_triggered|ROOM=101|WAKEUP_ENABLED=0|WAKEUP_DATE=2026-03-11|WAKEUP_TIME=07:30|SOURCE=scheduler

Si un wakeup vence sin ejecutarse o no puede lanzarse en PBX, el sistema lo cierra y publica:

OCCURRED_AT=2026-03-11T08:05:00.000+01:00|CATEGORY=services|EVENT=wakeup_clear|ROOM=101|WAKEUP_ENABLED=0|WAKEUP_DATE=2026-03-11|WAKEUP_TIME=07:30|SOURCE=scheduler|CODE=FAILED

3. Cambio de limpieza

La limpieza es de consulta para el PMS. Los cambios de estado se reciben en ENVIO.txt:

OCCURRED_AT=2026-03-10T09:15:00.000+01:00|CATEGORY=services|EVENT=housekeeping|ROOM=101|HOUSEKEEPING=clean|SOURCE=pbx-code

4. Salida de habitación

El PMS escribe en RECEPCION.txt:

ACTION=CHECKOUT|ROOM=101

El sistema cierra la estancia, marca llamadas como facturadas, conserva los wakeups pendientes y publica en ENVIO.txt un evento de salida similar a:

OCCURRED_AT=2026-03-12T10:00:00.000+01:00|CATEGORY=stay|EVENT=checkout|ROOM=101|GUEST=Juan Pérez|CHECKOUT_AT=2026-03-12T10:00:00.000+01:00|OUTBOUND_ENABLED=0|SOURCE=pms

5. Cambio de habitación

El PMS puede mover una estancia abierta a otra habitación libre:

ACTION=ROOM_MOVE|FROM_ROOM=101|TO_ROOM=202

El sistema libera la habitación origen, ocupa la destino, mueve wakeups pendientes y llamadas no facturadas, y publica eventos similares a:

OCCURRED_AT=2026-03-11T18:20:00.000+01:00|CATEGORY=stay|EVENT=room_change_in|ROOM=202|GUEST=Juan Pérez|FROM_ROOM=101|FROM_EXTENSION=101|MOVED_CALLS=2|MOVED_WAKEUPS=1|SOURCE=pms
OCCURRED_AT=2026-03-11T18:20:00.000+01:00|CATEGORY=stay|EVENT=room_change_out|ROOM=101|GUEST=Juan Pérez|TO_ROOM=202|TO_EXTENSION=202|MOVED_CALLS=2|MOVED_WAKEUPS=1|SOURCE=pms

Si la habitación destino no está libre, ya tiene wakeups pendientes o tiene llamadas sin facturar, el traslado se rechaza y no se aplica parcialmente.

6. Recepción de llamadas tarificadas

Cuando la PBX reporta una llamada, el PMS la recibe en ENVIO.txt como evento cdr. AMOUNT es el importe final en euros con IVA del 21% incluido, redondeado a dos decimales por llamada. El PMS debe cobrar este importe sin añadir IVA de nuevo. Por ejemplo, una base de 0.42 EUR se envía como AMOUNT=0.51:

OCCURRED_AT=2026-03-10T09:20:00.000+01:00|CATEGORY=cdr|EVENT=cdr|ROOM=101|CALLDATE=2026-03-10T09:20:00.000+01:00|SRC=101|DST=0971123456|DISPOSITION=ANSWERED|BILLSEC=64|OUTBOUND=1|RATE=Móvil nacional|AMOUNT=0.51|BILLED=0|UNIQUEID=1772798166.0|LINKEDID=1772798166.0

Despues del checkout, las llamadas ya facturadas aparecen con BILLED=1.

Despertadores y confirmación por CDR

La fecha y hora programadas se interpretan en la zona horaria del hotel. Programa con antelación; una hora pasada puede cerrarse como fallida. El checkout conserva los despertadores pendientes y un traslado mueve los pendientes con la estancia.

Evento / código	Interpretación para el PMS
`wakeup_set`	Programado. `WAKEUP_ENABLED=1`.
`wakeup_pending` `PENDING_CONFIRMATION`	La solicitud se envió pero falta confirmar el resultado. No equivale a fallo y no debe provocar una repetición automática.
`wakeup_triggered`	La centralita ha ejecutado la solicitud. La atención del huésped requiere evidencia adicional.
`wakeup_result` `ANSWERED`	Confirmación por un CDR que corresponde a la habitación, destino y ventana del despertador.
`wakeup_result` `NO_ANSWER`	El CDR asociado confirma que no se atendió.
`wakeup_clear` `FAILED`	No pudo ejecutarse o había vencido. Un borrado operativo puede no llevar código.

La ausencia de un CDR no confirma que el huésped no haya contestado. Mantén el resultado sin confirmar hasta recibir evidencia y contempla la llegada tardía de eventos. No generes un NO_ANSWER por tu cuenta.

OCCURRED_AT=2026-10-16T07:30:05.000+02:00|CATEGORY=services|EVENT=wakeup_pending|ROOM=401|WAKEUP_ENABLED=0|WAKEUP_DATE=2026-10-16|WAKEUP_TIME=07:30|SOURCE=scheduler|CODE=PENDING_CONFIRMATION
OCCURRED_AT=2026-10-16T07:31:00.000+02:00|CATEGORY=services|EVENT=wakeup_result|ROOM=401|WAKEUP_ENABLED=0|WAKEUP_DATE=2026-10-16|WAKEUP_TIME=07:30|SOURCE=fibwi_api|CODE=ANSWERED

WAKEUP_ENABLED=0 significa que ese despertador ya no está pendiente de lanzar. No significa que todos los demás despertadores de la habitación se hayan cancelado.

Reintentos y resolución de problemas

No hay una clave de idempotencia en las órdenes del fichero. No repitas un lote a ciegas. Comprueba antes el resultado en ENVIO.txt y, si hay dudas, consulta al responsable de la integración: las acciones, especialmente checkouts y traslados, no son intercambiables con un reintento seguro.
Una línea inválida se registra como error y el resto del lote continúa. El vaciado de RECEPCION confirma su consumo, no el éxito de todas las órdenes.
ENVIO puede reconstruirse y reflejar cambios en llamadas ya facturadas. UNIQUEID y LINKEDID ayudan a correlacionar CDR, pero no son claves de todos los eventos de estancia o servicio.
Los importes AMOUNT ya incluyen IVA del 21 %, redondeado por llamada; no lo añadas de nuevo.
Para problemas de acceso, comprueba el servidor, puerto, credenciales y carpeta SFTP facilitados. Para errores de órdenes, facilita al responsable de la integración la fecha y hora del envío, la habitación, la acción y el resultado esperado. No envíes contraseñas ni datos personales innecesarios.
Para una integración por HTTPS, consulta la documentación API.