Huéspedes

Registro y consulta de los viajeros de cada check-in, con la validación que exige SES.

Lo habitual es que cada huésped se registre a sí mismo desde el enlace del check-in: así los datos se validan en vivo (letra del DNI, formato NIE, municipio INE, parentesco de menores…) y su firma queda dentro del flujo con evidencia. Si tu sistema ya tiene la ficha del viajero, también puedes darlo de alta por API — pero eso precarga datos, no sustituye a su firma.

Listar huéspedes de un check-in

GET/checkins/{reservationId}/guests

curl

curl https://api.kinapi.es/api/v1/checkins/R-2026-0412/guests \
  -H "ocp-apim-subscription-key: TU_API_KEY"

200 OK

{
  "results": [
    {
      "id": "5f0c33f1-…",
      "nombre": "María",
      "apellido1": "García",
      "apellido2": "López",
      "tipoDocumento": "NIF",
      "numeroDocumento": "12345678Z",
      "soporteDocumento": "ABC123456",
      "sexo": "M",
      "parentesco": null,
      "direccion": { "direccion": "Gran Vía 1", "codigoMunicipio": "28079", "nombreMunicipio": null, "codigoPostal": "28013", "pais": "ESP" },
      "nacionalidad": "ESP",
      "fechaNacimiento": "1990-04-12",
      "esMenor": false,
      "isLead": true,
      "telefono": "+34600111222",
      "correo": "maria@example.com",
      "registeredAt": "2026-08-10T18:03:11.000Z",
      "signedAt": "2026-08-10T18:05:40.000Z"
    }
  ]
}

La lectura devuelve todo lo que hace falta para volver a dar de alta a ese huésped, domicilio incluido. Es lo que permite rehacer una reserva —cambian las fechas sobre un contrato ya firmado, así que hay que cancelar y crear otra— rellenando los huéspedes con lo que ya dieron, para que sólo tengan que firmar. Antes faltaban el domicilio, el número de soporte y el parentesco, y el alta los exige: había que pedirle al huésped que lo tecleara todo otra vez.

signedAt indica si ese huésped ya firmó su parte del contrato; cuando todos tienen firma, el check-in pasa a signed y se genera el contrato definitivo.

Campos del huésped

Los nombres de campo siguen la nomenclatura del parte de viajeros de SES (nombre, apellido1, tipoDocumento…), de modo que lo que ves por API es exactamente lo que se comunica al Ministerio. La nacionalidad va en ISO 3166-1 alpha-3.

Registrar un huésped desde tu sistema

POST/checkins/{reservationId}/guests

Si tu PMS ya tiene la ficha del viajero, puedes darlo de alta directamente y ahorrarle el formulario. Se aplican exactamente las mismas reglas que en el flujo del huésped: documento válido según nacionalidad, plazas disponibles en la reserva y documento no repetido entre viajeros del mismo grupo.

Dar de alta a un huésped por API no produce su firma. El contrato sigue necesitando que cada viajero firme desde el enlace del check-in, y si tienes activado submitRequiresSignature el parte no saldrá a SES hasta que lo hagan. Esta vía precarga datos; no sustituye al consentimiento.

El idioma lo decide la reserva, no el huésped que se registra. El formulario y el contrato salen en el locale del check-in (ver Check-ins). El huésped puede cambiar la bandera para leerlo en otro idioma, pero eso solo afecta a lo que ve él: el contrato que se archiva es el de la reserva, igual para todos los firmantes.

Menores de 14 años

El corte del RD 933/2021 está en los 14 años a fecha de entrada. Por debajo, parentesco es obligatorio (código del catálogo TIPO_PARENTESCO, p. ej. HJ para hijo/a) y el documento es opcional: puedes omitir tipoDocumento y numeroDocumento. Lo que decide es el número: si mandas un tipoDocumento sin número, se descarta en vez de rechazar el alta, porque a SES no puede comunicársele un tipo huérfano. Desde los 14 el documento es obligatorio igual que en un adulto.

curl

curl -X POST https://api.kinapi.es/api/v1/checkins/R-2026-0412/guests \
  -H "ocp-apim-subscription-key: TU_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "nacionalidad": "ESP",
    "nombre": "María", "apellido1": "García", "apellido2": "López",
    "fechaNacimiento": "1990-04-03",
    "tipoDocumento": "NIF", "numeroDocumento": "12345678Z", "soporteDocumento": "ABC123456",
    "direccion": { "direccion": "Calle Mayor 1", "codigoMunicipio": "29067",
                   "codigoPostal": "29005", "pais": "ESP" },
    "correo": "maria@example.com"
  }'

Eliminar un huésped

DELETE/checkins/{reservationId}/guests/{guestId}

Responde 409 si el parte ya se comunicó a SES: lo enviado a la policía no se deshace borrando el registro aquí.