Escenarios de Alquiler: aplicación, API y webhooks

Antes de empezar: ¿quién crea cada cosa?

Puedes ejecutar el escenario 1 de principio a fin en el TrakarIA Integration Lab. Empieza en modo de simulación o utiliza una clave API de grupo para enviar datos de prueba al entorno seleccionado por el Lab desplegado. La interfaz del Lab está en inglés.

Tu software de alquiler gestiona la reserva, los precios, los pagos y las decisiones comerciales. TrakarIA gestiona la inspección física: salida, devolución, pruebas, comparación e informes. Un mismo vehículo puede participar en muchos alquileres sucesivos.

Al conectar los sistemas intervienen dos accesos diferentes:

Acceso	Quién lo usa	Para qué sirve
Clave API del grupo	El servidor de tu software de alquiler	Sincronizar vehículo y expediente, abrir inspecciones y leer resultados. Nunca se envía al navegador del agente.
Cuenta TrakarIA	El empleado que realiza la inspección	Iniciar sesión, tomar fotos y validar. La clave API no sustituye esta cuenta.

Sincronizar exige llamadas concretas: tu servidor envía PUT /v1/vehicles/by-external/{external_id} para el vehículo y PUT /v1/rentals/by-external/{external_id} para el expediente asociado a la reserva. El expediente aparece inmediatamente en el planning de TrakarIA. Para crearlo solo se necesitan el identificador externo de la ruta y vehicle_external_id; fechas, referencias, ubicaciones, contacto y conductores pueden enviarse con antelación, durante la entrega física o más tarde con una revisión de origen superior. Sin salida prevista se usa la hora de creación y sin retorno previsto la entrada queda abierta. TrakarIA devuelve los identificadores públicos del expediente y de la entrada del planning. Reutiliza los mismos identificadores externos para actualizar los mismos recursos. Sin esas llamadas, ninguna reserva se sincroniza por sí sola.

Para asociar un expediente sincronizado a una inspección utilizable por la API pública, tu servidor llama también a POST /v1/rentals/{rental_id}/inspections para la salida y, después, para la devolución. El launch_url devuelto solo sirve para abrir el flujo correcto en TrakarIA. El agente puede encontrarlo en la aplicación sin hacer clic en el enlace, pero la creación del expediente y la asociación de la inspección siguen siendo pasos de la API.

Una vez validada la inspección, pueden existir dos informes oficiales: departure tras la salida y comparison tras la devolución. Ambos están disponibles en JSON y PDF; el PDF puede estar listo después del JSON. No hay un tercer tipo de informe return. GET /v1/rentals/{rental_id}/report muestra los identificadores disponibles; GET /v1/reports/{report_id} lee el JSON y GET /v1/reports/{report_id}/pdf descarga el PDF.

Los webhooks son opcionales. Si quieres avisos automáticos, configura un destino HTTP o HTTPS en la clave API en Organización → Integraciones → Claves API → Gestionar webhooks. Selecciona rental.departure.completed, rental.return.completed y, si lo necesitas, rental.report.pdf_ready. TrakarIA envía un POST firmado a esa URL; tu servidor comprueba la firma y lee el informe por API. El webhook no contiene el informe completo. Sin un destino webhook, puedes consultar GET /v1/events y las rutas de informes. Sin integración API, tu software no recibe estos eventos ni informes por API. Consulta webhooks y recuperación.

Escenario 1: software conectado con botón «Abrir inspección»

Requisitos: un administrador creó una clave API que tu servidor guarda. Para avisos automáticos, también configuró un destino webhook. Ejemplo: el vehículo FLEET-42 se reserva como RES-1042 en tu software.

Tu servidor envía PUT /v1/vehicles/by-external/FLEET-42 y después PUT /v1/rentals/by-external/RES-1042 con vehicle_external_id: FLEET-42. La reserva aparece inmediatamente en el planning. Guarda el id público del expediente y planning.entry_id. En cambios posteriores envía un source_revision estrictamente mayor; la asignación del vehículo queda fija al empezar la inspección.
En la salida, llama a POST /v1/rentals/{rental_id}/inspections con {"type":"departure"} y un Idempotency-Key. Guarda el identificador de inspección y muestra un botón que abre el launch_url recibido.
El empleado abre el enlace, inicia sesión con su cuenta TrakarIA, comprueba el vehículo, toma fotos y valida la salida. El enlace por sí solo no autoriza la inspección: TrakarIA comprueba sus permisos.
Si existe un webhook configurado, tu servidor recibe rental.departure.completed. Verifica la firma, consulta GET /v1/rentals/{rental_id}/report y lee el JSON departure por su report_id. Recupera el PDF cuando esté listo. Sin webhook, consulta la API para conocer el resultado.
En la devolución, llama a la misma ruta de inspección con {"type":"return"} y un nuevo Idempotency-Key; después abre el nuevo launch_url. El empleado valida la comparación en TrakarIA.
Si existe un webhook configurado, rental.return.completed avisa de que el JSON comparison está listo. Tu servidor lee el índice de informes, archiva el report_id y la versión, y descarga el PDF cuando esté listo. Las decisiones de cobro permanecen en tu software.

Escenario 2: software conectado sin botón de lanzamiento

La clave API sigue siendo necesaria. Solo desaparece el botón de navegación; el servidor sigue sincronizando el vehículo y la reserva.

Tu servidor realiza las dos llamadas PUT del escenario 1 y llama a POST /v1/rentals/{rental_id}/inspections para preparar la salida. Puede ignorar el launch_url.
El empleado abre la aplicación TrakarIA, selecciona el grupo y el vehículo correctos y reanuda la inspección de salida ya preparada. No crea un segundo alquiler para esa reserva.
Tras validar, el servidor recupera el informe de salida como en el escenario 1. Para la devolución, prepara {"type":"return"} por API; el empleado reanuda la devolución del mismo vehículo en TrakarIA. Los webhooks e informes siguen el mismo recorrido si hay un destino configurado.

Este modelo sirve a los equipos que ya trabajan en TrakarIA. Abrir la aplicación manualmente no sustituye las llamadas de sincronización y preparación de tu servidor.

Escenario 3: todo ocurre en TrakarIA, sin integración API

Aquí no hay clave API de socio ni sincronización con el software de alquiler. El empleado usa únicamente su cuenta TrakarIA y los permisos de su grupo.

En el espacio de Alquiler, elige un vehículo existente o lo crea en la aplicación e inicia la salida. TrakarIA crea el ciclo de inspección; el empleado introduce la información necesaria, como una referencia de reserva si existe.
Captura las pruebas y valida la salida. Más adelante encuentra el mismo vehículo y el mismo ciclo, inicia la devolución y valida la comparación.
El equipo consulta los resultados en TrakarIA. Ninguna reserva de tu software se importó automáticamente y ese software no recibe webhooks ni informes por la API pública.

Un ciclo creado solo en la aplicación no se vincula automáticamente a un expediente /v1/rentals. Si incorporas una integración después, planifica expresamente la conciliación de vehículos y alquileres; no supongas que los ciclos antiguos aparecerán en la API.

Escenario 4: cambia la reserva o el informe

Antes de la primera inspección: para un expediente conectado, tu servidor actualiza los campos permitidos con PUT .../by-external/{external_id} o PATCH /v1/rentals/{rental_id} y un marcador de origen más reciente. Después de un 409, lee el expediente actual antes de reintentar.
Cancelación antes de la salida: POST /v1/rentals/{rental_id}/cancel cancela tanto el expediente como su entrada del planning.
Tras empezar la inspección: la asignación del vehículo queda fija. Tras validar la salida, también quedan fijas algunas fechas y ubicaciones previstas. Una corrección admitida por el flujo puede crear una nueva versión inmutable del informe de salida o de comparación.
Tras la corrección: tu servidor archiva cada report_id y versión nuevos; no reemplaza silenciosamente el informe anterior. rental.report.corrected puede notificarlo si se configuró un destino.

Consulta informes y pruebas para distinguir las versiones actuales del historial. Estas rutas se aplican a expedientes creados y asociados mediante la API pública.

Escenario 5: el receptor webhook no está disponible

Este escenario se aplica a una integración API con destino webhook configurado. Los envíos pueden repetirse o llegar fuera de orden: verifica cada firma, deduplica por webhook-id y vuelve a consultar el informe actual. Tras una interrupción, llama a GET /v1/events con el cursor guardado o un created_after apropiado; avanza el cursor solo después de procesar la página. Los eventos se conservan 30 días. Consulta webhooks y recuperación.

Escenario 6: ha caducado un enlace de inspección

En los escenarios conectados, consulta GET /v1/inspections/{inspection_id}. Si sigue abierta, llama a POST /v1/inspections/{inspection_id}/launch con un nuevo Idempotency-Key y abre el nuevo enlace. Se reanuda la misma inspección; el agente aún debe iniciar sesión y tener los permisos necesarios.

Datos que debe conservar la integración

Dato	Utilidad
Grupo e identificadores externos de vehículo y reserva	Encontrar exactamente los mismos expedientes tras reintentos o cambios de personal
Identificadores públicos de alquiler e inspección	Abrir y seguir el flujo correcto sin usar identificadores privados de Kernel
Identificador de entrada del planning	Confirmar qué ocupación del calendario representa la reserva sincronizada
Una clave de idempotencia por comando	Repetir una llamada si se pierde su respuesta
Cursor de eventos e identificadores ya procesados	Recuperar y deduplicar notificaciones webhook
Identificador, tipo, versión y hash del informe	Archivar por separado las versiones de salida y comparación

En los escenarios conectados, guarda la clave API y el secreto webhook en tu servidor. No uses el enlace de lanzamiento como identificador permanente: renuévalo cuando haga falta. La guía de primeros pasos muestra las primeras peticiones y la referencia API de Alquiler define los campos exactos.