API REST para el motor de reservas de tu camping

¿Qué hace la API REST?

La API REST v1 de AutoSES permite a cualquier motor de reservas, PMS o backend propio crear y gestionar reservas de camping de forma programática, delegando en la plataforma todo el cumplimiento legal ante SES.hospedajes del Ministerio del Interior.

Tu motor llama a POST /api/v1/camping/reservations. En esa misma llamada, la plataforma:

• Registra la reserva vinculada a tu cuenta.
• Envía la notificación de reserva a SES.hospedajes automáticamente.
• Devuelve la checkin_url para que el campista complete su parte de viajeros.

El resto del ciclo —check-in digital, validaciones, parte de viajeros, alojamiento y recibo final— funciona exactamente igual que si hubieras creado la reserva desde el panel.

Ejemplo de petición

Incluye la cabecera Authorization: Bearer as_live_… en todas las llamadas. La clave se genera en Mi cuenta → API REST y solo se muestra una vez.

POST /api/v1/camping/reservations
Authorization: Bearer as_live_…
Content-Type: application/json
Idempotency-Key: pedido-abc-123

{
  "parcela_id": 12,
  "check_in": "2026-09-01",
  "check_out": "2026-09-05",
  "adults": 2,
  "children": 1,
  "pets": 1,
  "guest": {
    "first_name": "María",
    "last_name": "García",
    "email": "maria@example.com"
  },
  "send_email": false
}

Respuesta exitosa (HTTP 201):

{
  "id": 4471,
  "estado": "G",
  "checkin_url": "https://autoses.com/check-in/abc123xyz",
  "envio_ses_pendiente": false,
  "mensaje": "Reserva creada y notificación enviada a SES."
}

Si SES está caído en el momento de la llamada, envio_ses_pendiente será true y el scheduler reintentará el envío cada 2 horas de forma automática.

Cómo funciona paso a paso

1. Genera la clave API. En Mi cuenta → pestaña API REST, pulsa «Generar clave». Recibirás una clave con formato as_live_… que solo se muestra una vez. Guárdala en una variable de entorno de tu servidor.
2. Crea la reserva. Llama a POST /api/v1/camping/reservations desde tu backend con los datos de la reserva. La plataforma intenta enviar la notificación a SES y te devuelve la checkin_url.
3. Comparte la URL de check-in con el campista. Puedes incluir checkin_url en tu propio email de confirmación de reserva, o bien activar "send_email": true para que AutoSES lo envíe por ti.
4. El campista completa el parte. Accede a la URL, rellena sus datos en su idioma y escanea su documento con la cámara. El parte pasa a estado F (completado) y después a E (enviado a SES).
5. La estancia sigue el ciclo normal. Al llegar el campista pasa a I (alojado) y al marcharse a O (finalizada), momento en que se emite el recibo en el idioma del campista.

Modo transparente

Por defecto, cuando el campista completa el check-in, AutoSES le envía un email de confirmación. Cuando la estancia finaliza, recibe el recibo. Si tu plataforma gestiona la comunicación con el huésped y prefieres que AutoSES no contacte al campista bajo ningún concepto, activa el modo transparente en Mi cuenta → API REST.

Con el modo transparente activado:

• No se envían emails de check-in ni recibo al campista (la copia al propietario se mantiene si está activada).
• El envío a SES.hospedajes se realiza siempre, sin excepción.
• Tu motor gestiona en exclusiva la comunicación con el huésped.

El modo transparente es independiente del parámetro send_email en la petición: el parámetro controla el email de check-in inicial; el modo transparente suprime también el recibo final y cualquier otra comunicación automática.

Idempotencia

Las redes fallan. Si tu servidor no recibe respuesta y reintenta la petición, sin protección crearías reservas duplicadas. La API resuelve esto con la cabecera Idempotency-Key: una cadena única que identifica el intento de tu sistema (por ejemplo, el id interno del pedido).

Idempotency-Key: pedido-reserva-7821

Si la misma clave llega una segunda vez, la API devuelve exactamente la misma respuesta que en el primer intento exitoso, sin crear ningún registro adicional. Las claves de idempotencia son únicas por propietario y se conservan 24 horas.

Cancelaciones y reembolso del cargo de servicio

Para cancelar una reserva, llama a POST /api/v1/camping/reservations/{id}/cancel. La plataforma anula la notificación en SES.hospedajes si la reserva ya fue enviada.

El cargo de servicio de AutoSES (el coste de la estancia, no el pago del campista) se reembolsa al saldo del propietario según el estado en el momento de la cancelación:

• Estado G o P (el campista aún no ha completado el parte): reembolso completo.
• Estado F, E, I u O (el campista ya completó el check-in): sin reembolso.

Endpoints disponibles

Control de acceso por matrícula (barrera automática)

Conecta un lector de matrículas (cámara LPR/ANPR) con la barrera de entrada de tu camping. Cuando un vehículo llega, la cámara detecta su matrícula y la consulta con POST /api/v1/camping/access/plate; AutoSES responde si esa matrícula pertenece a una reserva activa y tu sistema abre —o no— la barrera. Tus campistas entran solos, sin pasar por recepción.

Se autoriza el acceso cuando la matrícula corresponde a una reserva en estado E (parte enviado, huésped esperado) o I (huésped alojado) con la fecha de hoy dentro de la estancia. Cada reserva admite hasta 3 matrículas (los tres vehículos) y cualquiera de ellas abre la barrera. La matrícula se normaliza automáticamente, así que da igual mayúsculas, espacios o guiones. El filtro por estado y fecha evita que una reserva antigua de un cliente habitual con la misma matrícula abra la barrera por error.

POST /api/v1/camping/access/plate
Authorization: Bearer as_live_...
Content-Type: application/json

{"plate": "1234ABC"}

→ {"authorized": true, "plate": "1234ABC",
   "reservation": {"id": 42, "parcela": "A-14", "status": "I", ...}}

Webhooks: notificaciones en tiempo real

Además de la API entrante, AutoSES puede avisar a tu sistema cada vez que ocurre algo en una reserva: se crea, cambia de estado, el huésped completa el parte, se envía a SES.hospedajes, baja el saldo o se emite el recibo. En lugar de consultar continuamente, registras una URL HTTPS y AutoSES te envía un POST firmado en cuanto sucede el evento.

Se configuran desde Mi cuenta → Integraciones: URL destino, secreto de firma HMAC-SHA256, filtro de los eventos que quieres recibir, un botón de ping de prueba y el registro de las últimas entregas. Cada petición incluye la cabecera X-Autoses-Signature (t=<timestamp>,v1=<hmac>) para que verifiques que el evento proviene de AutoSES y no ha sido alterado.

Eventos disponibles: reservation.created, reservation.status_changed, reservation.updated, reservation.cancelled, guest.checked_in, ses.submission_succeeded, ses.submission_failed, balance.low, receipt.sent y webhook.ping.

La entrega es at-least-once (deduplica por el campo id del evento), con hasta 8 reintentos en backoff exponencial y 30 días de retención. El detalle completo, con ejemplos de verificación de firma en Python, PHP y Node.js, está en el manual de la API (PDF) y en /api/v1/docs.

Documentación interactiva

Todos los endpoints están documentados con Swagger UI en /api/v1/docs. Desde ahí puedes explorar los parámetros, ejecutar peticiones reales contra tu cuenta y ver ejemplos de respuesta sin escribir una sola línea de código.

El esquema OpenAPI completo está disponible en /api/v1/openapi.json para importarlo en Postman, Insomnia u otras herramientas.

Preguntas frecuentes sobre la API

¿Puedo recibir avisos automáticos cuando cambia una reserva (webhooks)?

Sí. Desde Mi cuenta → Integraciones registras una URL HTTPS y AutoSES te envía un POST firmado (HMAC-SHA256) cada vez que ocurre un evento: reserva creada, cambio de estado, check-in del huésped, envío a SES, saldo bajo, recibo emitido, etc. Así no necesitas consultar la API continuamente. Incluye reintentos con backoff, deduplicación por id y un ping de prueba. Ver el manual de la API.

¿La API funciona con campings en Cataluña (Mossos d'Esquadra)?

Sí. La API detecta automáticamente si el camping usa el canal Mossos por código postal (08, 17, 25, 43). El flujo de la API es idéntico; la diferencia interna es que en lugar de enviar a SES.hospedajes, la plataforma genera el fichero TXT para los Mossos y lo envía al propietario por email.

¿Puedo crear varias reservas para el mismo campista (grupo) en una sola llamada?

Sí. La API admite la creación de múltiples reservas vinculadas mediante el campo grupo_id, útil cuando un grupo ocupa más de una parcela con una única estancia y un único parte de viajeros compartido.

¿Hay límite de peticiones por minuto?

Actualmente no se aplica un límite estricto de rate-limit en la API v1. Para usos de alto volumen o integraciones de gran escala, contacta con soporte para coordinar la configuración más adecuada.

¿Qué pasa si revoco mi clave API?

Al revocar la clave, todas las peticiones que la usen recibirán un error 401 Unauthorized de inmediato. Las reservas ya creadas no se ven afectadas. Puedes generar una nueva clave en cualquier momento desde Mi cuenta → API REST.