SES.Hospedajes API

Primeros pasos

1. El propietario de la cuenta debe disponer de plan Premium con la API habilitada.
2. Desde el panel de la cuenta puede generarse una API Key de producción y, opcionalmente, una API Key de sandbox para pruebas (ver Entorno de pruebas).
3. Toda llamada incluye la cabecera X-Api-Key: <tu_api_key>.
4. La base URL es https://seshospedajes.es/app/api/v1.
5. Para validar la integración, llamar primero a GET /v1/ping.

Primera llamada

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

Respuesta esperada:

{
  "ok": true,
  "ts": "2026-06-25T12:00:00+00:00",
  "userId": 123,
  "sandbox": false,
  "env": "production"
}

Autenticación

Toda petición a la API debe incluir una API Key válida. Se acepta en tres formas, por orden de prioridad:

1. Cabecera X-Api-Key: <clave> recomendado
2. Cabecera Api-Key: <clave>
3. Parámetro de query ?api_key=<clave> — solo para pruebas; no usar en producción

Ejemplos en distintos lenguajes

curl -sS https://seshospedajes.es/app/api/v1/establishments \
  -H 'X-Api-Key: TU_API_KEY'

<?php
$ch = curl_init('https://seshospedajes.es/app/api/v1/establishments');
curl_setopt_array($ch, [
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => ['X-Api-Key: TU_API_KEY'],
]);
$response = curl_exec($ch);
$data = json_decode($response, true);
curl_close($ch);

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

import requests

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

Códigos de error de autenticación

Entorno de pruebas

La plataforma ofrece un modo sandbox a través de API Keys marcadas como tal. Una API Key de sandbox permite ejercitar todos los endpoints exactamente igual que en producción (mismos campos, mismas validaciones, mismos códigos de respuesta), con una única diferencia operativa:

Cómo identificar una key de sandbox

La respuesta de GET /v1/ping incluye los campos sandbox (booleano) y env ("production" o "sandbox"). Es la forma fiable de saber contra qué entorno está ejecutando la integración.

// Respuesta con API Key de sandbox
{
  "ok": true,
  "ts": "2026-06-25T12:00:00+00:00",
  "userId": 123,
  "sandbox": true,
  "env": "sandbox"
}

Buenas prácticas de pruebas

• Realizar la integración completa contra sandbox antes de cambiar a la API Key de producción.
• Probar tanto el camino feliz (alta atómica) como los caminos de error (campos faltantes, formatos inválidos, reenvío idempotente).
• Confirmar que la integración lee correctamente env en ping y muestra al operador en qué entorno está trabajando.
• Los registros sandbox pueden eliminarse con DELETE /v1/contracts/{id} sin afectar a producción.

URLs base y versionado

La API mantiene una única versión pública estable, identificada en la ruta:

https://seshospedajes.es/app/api/v1/{recurso}

La numeración semántica de la API se publica en la respuesta de GET /v1/ping mediante la cabecera de versión del OpenAPI (openapi.yaml). Los cambios incompatibles siempre implican una nueva versión mayor (/v2); las versiones en uso se mantienen al menos 12 meses tras la publicación de la siguiente.

Paginación y filtros

Todos los listados (GET sobre una colección) aceptan los siguientes parámetros de query:

Forma de la respuesta paginada

{
  "ok": true,
  "data": [ /* registros */ ],
  "page": 1,
  "limit": 20,
  "total": 137
}

Idempotencia

Para evitar duplicados en caso de reintentos por timeout o errores de red, todos los endpoints POST aceptan un campo uuid opcional en el cuerpo. Si una llamada posterior llega con el mismo uuid bajo la misma cuenta, la respuesta es 200 OK con "idempotent": true y los datos del registro existente, sin crear duplicados.

Adicionalmente, algunos endpoints usan claves naturales como respaldo:

Si una llamada se considera idempotente, la respuesta incluye idempotent: true y los identificadores del registro previo. Es seguro reintentar cualquier POST tras un error transitorio.

Fechas, horas y zonas horarias

• Fechas en formato ISO 8601 YYYY-MM-DD (ejemplo: 2026-07-15).
• Horas en formato HH:MM:SS en 24h (ejemplo: 15:00:00).
• Datetime compuesto YYYY-MM-DD HH:MM:SS (ejemplo: 2026-07-15 15:00:00).
• Zona horaria: todas las fechas y horas se interpretan en Europe/Madrid. Las fechas se devuelven en el mismo formato.
• Códigos de país en ISO 3166-1 alpha-3 (ejemplo: ESP, FRA, GBR).
• Códigos de municipio según el padrón del INE (5 dígitos, ejemplo: 28079 para Madrid).

Códigos de error

Todas las respuestas de error siguen el mismo formato JSON:

{
  "ok": false,
  "code": "validation_error",
  "message": "Datos con formato inválido",
  "fields": {
    "fecha_entrada": "Formato esperado YYYY-MM-DD",
    "contacto_email": "Email inválido"
  }
}

Límites de uso

No se aplican límites estrictos por defecto. Para integraciones de alta frecuencia (carga inicial, sincronización masiva), se recomienda:

• Limitar la concurrencia a 5 peticiones simultáneas por API Key.
• Implementar reintentos con exponential backoff ante respuestas 5xx, comenzando en 1 segundo y duplicando hasta un máximo de 60 segundos.
• Reutilizar uuid en los reintentos para garantizar idempotencia.
• Para cargas iniciales de más de 10.000 registros, espaciar las cargas en lotes con pausa entre lotes.

Health check

{
  "ok": true,
  "ts": "2026-06-25T12:00:00+00:00",
  "userId": 123,
  "sandbox": false,
  "env": "production"
}

Establecimientos

Un establecimiento representa una unidad operativa (hotel, oficina de rent-a-car, agencia, etc.) registrada ante el Ministerio del Interior. Toda alta de huésped o contrato debe asociarse a un establecimiento de la cuenta autenticada.

{
  "nombre": "Oficina Aeropuerto T1",
  "numero_establecimiento": "R12345"
}

Huéspedes (hospedaje)

Recurso aplicable únicamente a hospedaje. Para rent-a-car, las personas (titulares y conductores) se gestionan a través de /v1/persons.

Contratos (cabecera)

Endpoints de bajo nivel sobre la tabla común de contratos. Cubre la cabecera de cualquier alquiler. Para rent-a-car se recomienda usar el endpoint atómico POST /v1/rentacar/contracts, que crea contrato, vehículo, personas, permisos y direcciones en una sola transacción.

Precheckins (solo lectura)

Rent-a-Car — Modelo de datos

El alta de un contrato de alquiler de vehículo se compone de los siguientes recursos:

Roles de persona

Cada rol puede aparecer como máximo una vez por contrato.

Alta de contrato rent-a-car (transacción única)

POST /v1/rentacar/contracts
Content-Type: application/json
X-Api-Key: TU_API_KEY

{
  "uuid": "8d2e1c0a-7b21-4f0a-9a91-8b22d3f3a001",
  "contract": {
    "establecimiento_id": 12,
    "referencia": "RC-2026-0007",
    "fecha_contrato": "2026-06-25",
    "fecha_recogida": "2026-06-26 10:00:00",
    "fecha_devolucion": "2026-06-30 18:00:00",
    "tipo_pago": "TARJETA",
    "fecha_pago": "2026-06-25",
    "medio_pago": "VISA",
    "titular_pago": "Ana García",
    "caducidad_tarjeta": "12/28"
  },
  "vehicle": {
    "categoria": "TURISMO_M1",
    "tipo": "TURISMO",
    "marca": "SEAT",
    "modelo": "Ibiza",
    "matricula": "1234ABC",
    "numero_bastidor": "VSSZZZ6JZNR123456",
    "color": "BLANCO",
    "km_recogida": 12030
  },
  "pickup_address": {
    "direccion": "Aeropuerto T1, Mostrador 4",
    "codigo_municipio": "28079",
    "nombre_municipio": "Madrid",
    "codigo_postal": "28042",
    "pais": "ESP"
  },
  "dropoff_address": {
    "direccion": "Aeropuerto T4, Devolución",
    "codigo_municipio": "28079",
    "nombre_municipio": "Madrid",
    "codigo_postal": "28042",
    "pais": "ESP"
  },
  "persons": [
    {
      "rol": "TI",
      "nombre": "Ana", "apellido1": "García", "apellido2": "López",
      "tipo_documento": "NIF", "numero_documento": "12345678Z",
      "fecha_nacimiento": "1985-03-12", "nacionalidad": "ESP", "sexo": "M",
      "telefono": "+34600111222", "correo": "ana@example.com",
      "license": { "tipo": "B", "validez": "2030-01-01", "numero": "B12345678" },
      "address": {
        "direccion": "Calle Mayor 1",
        "codigo_municipio": "28079", "nombre_municipio": "Madrid",
        "codigo_postal": "28013", "pais": "ESP"
      }
    },
    {
      "rol": "CP",
      "nombre": "Luis", "apellido1": "Pérez",
      "tipo_documento": "NIF", "numero_documento": "87654321X",
      "fecha_nacimiento": "1990-07-08", "nacionalidad": "ESP", "sexo": "H",
      "license": { "tipo": "B", "validez": "2031-06-01", "numero": "L7654321" },
      "address": {
        "direccion": "Av. Diagonal 100",
        "codigo_municipio": "08019", "nombre_municipio": "Barcelona",
        "codigo_postal": "08018", "pais": "ESP"
      }
    }
  ]
}

HTTP/1.1 201 Created

{
  "ok": true,
  "id": 4567,
  "vehicle_id": 89,
  "person_ids": [121, 122],
  "license_ids": [55, 56],
  "person_address_ids": [201, 202],
  "address_ids": { "pickup": 203, "dropoff": 204 },
  "mir_status": "pending"
}

HTTP/1.1 200 OK

{
  "ok": true,
  "id": 4567,
  "idempotent": true,
  "vehicle": { /* ... */ },
  "persons": [ /* ... */ ]
}

Vehículos

Cada contrato rent-a-car tiene exactamente un vehículo asociado.

Personas

Titulares y conductores asociados a un contrato rent-a-car.

Permisos de conducir

Permiso de conducir asociado a una persona del contrato.

Direcciones

Las direcciones de tipo recogida y devolucion se asocian al contrato; las de tipo persona se asocian a la persona.

Envío al Ministerio del Interior

La API es asíncrona respecto al envío al MIR. Una vez creado un contrato o un alta de huésped, la respuesta es inmediata y los datos quedan registrados en la plataforma. Un proceso interno se encarga de comunicarlos a la sede electrónica del Ministerio del Interior (SES.Hospedajes / Sistema VUD) siguiendo los mismos plazos y reglas que los registros creados desde la interfaz web.

Estados posibles del campo enviado_ministerio:

La respuesta de POST /v1/rentacar/contracts incluye también mir_status como información de conveniencia:

• "pending" en producción — el envío al MIR se procesa de forma diferida.
• "sandbox" cuando la API Key es de sandbox.

Seguimiento de estado

Para conocer el estado actual de un contrato o huésped, basta con consultar su detalle:

GET /v1/contracts/{id}
GET /v1/guests/{id}

La respuesta incluye el campo enviado_ministerio con los valores descritos arriba. Una integración robusta puede polear el detalle tras crear un registro para confirmar la transición a 1.

Changelog