SES.Hospedajes — Developer Docs (API v1)

🔐 Autenticación

Envía siempre la cabecera X-Api-Key: TU_API_KEY. Alternativas aceptadas: Api-Key o query ?api_key=.

curl -s 'https://seshospedajes.es/app/api/v1/ping' -H 'X-Api-Key: TU_API_KEY'

<?php
$r = file_get_contents('https://seshospedajes.es/app/api/v1/establishments', false,
  stream_context_create(['http'=>['header'=>'X-Api-Key: TU_API_KEY']]));
echo $r;

const r = await fetch('https://seshospedajes.es/app/api/v1/establishments', {
  headers: { 'X-Api-Key': 'TU_API_KEY' }
}); console.log(await r.json());

import requests
r = requests.get('https://seshospedajes.es/app/api/v1/establishments', headers={'X-Api-Key':'TU_API_KEY'})
print(r.json())

🔎 Listados y filtros

Todos los listados soportan paginación page, limit y filtros:

q: búsqueda textual (campos útiles por recurso).
from / to: fechas (YYYY-MM-DD). En huéspedes filtran por fecha_entrada, en contratos por fecha_contrato, en precheckins por fecha_envio.

GET /v1/guests?page=1&limit=50&q=garcia&from=2025-01-01&to=2025-01-31

👤 Huéspedes (CRUD)

`GET /v1/guests`

Devuelve data, page, limit, total. Filtros: q, from, to.

`POST /v1/guests`

Campos obligatorios: nombre, apellido1, establecimiento_id. Idempotencia: uuid (si la columna existe) o combinación numero_documento + fecha_entrada + establecimiento_id.

{
  "nombre":"Ana","apellido1":"García","establecimiento_id":12,
  "numero_documento":"X1234567","fecha_entrada":"2025-09-27","hora_entrada":"15:00:00"
}

`GET /v1/guests/{id}`, `PUT /v1/guests/{id}`, `DELETE /v1/guests/{id}`

Se valida propiedad por usuario mediante el establecimiento.

📄 Contratos (CRUD)

`GET /v1/contracts`

Filtros: q (referencia / número_establecimiento), from/to sobre fecha_contrato.

`POST /v1/contracts`

Obligatorios: establecimiento_id, referencia. Idempotencia por uuid (si existe) o referencia+usuario.

{
  "establecimiento_id":12,"referencia":"RC-2025-0007",
  "fecha_contrato":"2025-09-27","fecha_recogida":"2025-09-28","fecha_devolucion":"2025-10-01"
}

`GET/PUT/DELETE /v1/contracts/{id}`

🏨 Establecimientos (CRUD)

`GET /v1/establishments`

Filtro q (nombre, número_establecimiento).

`POST /v1/establishments`

{ "nombre":"Hotel Atlántico", "numero_establecimiento":"H1234" }

`GET/PUT/DELETE /v1/establishments/{id}`

✉️ Precheckins (solo lectura)

`GET /v1/precheckins`

Filtros: q (nombre_hotel, email_cliente, uuid), from/to sobre fecha_envio.

❗ Errores y validación

HTTP	code	message	Detalle
401	auth_missing	Falta API Key.
401	auth_invalid	API Key no válida.
403	plan_required	El plan no permite usar la API.
403	api_disabled	La API no está habilitada para este usuario.
405	method_not_allowed	Método no permitido.
422	validation_error	Datos con formato inválido.	`{"fields":{"fecha_entrada":"YYYY-MM-DD","contacto_email":"Email inválido"}}`
404	not_found	Ruta no encontrada.
500	db_error	Error de base de datos.

📄 OpenAPI & Postman

Publica tus ficheros en /app/api/docs/ y enlázalos aquí:

📝 Changelog

v1.1

Docs separadas del router. Endpoints y ejemplos sincronizados con la API real.
Incluye filtros q/from/to, paginación y reglas de idempotencia.
Botón de tema y snippets cURL/PHP/Node/Python.

Integra tu PMS con SES.Hospedajes

🔐 Autenticación

🔎 Listados y filtros

👤 Huéspedes (CRUD)

GET /v1/guests

POST /v1/guests

GET /v1/guests/{id}, PUT /v1/guests/{id}, DELETE /v1/guests/{id}

📄 Contratos (CRUD)

GET /v1/contracts

POST /v1/contracts

GET/PUT/DELETE /v1/contracts/{id}