Transporte de pasajeros

La Mini App Transporte de pasajeros centraliza la operación de empresas, remiserías y prestadores de traslados programados. Combina una consola para administradores y transportistas con herramientas para que un agente de Atendium identifique clientes, genere reservas, consulte la agenda y acompañe cada viaje usando datos reales de la Mini App.

El flujo está pensado para reducir errores en direcciones y horarios: el agente conversa, identifica a la persona y entrega formularios personales con Google Maps. Una vez enviado el viaje, el sistema lo cotiza, evalúa las reglas, busca transportista y notifica el resultado en la misma conversación.

Qué problemas resuelve

Registra viajes de solo ida, ida y vuelta o regreso a otro destino.
Calcula distancia y duración estimadas a partir de direcciones georreferenciadas.
Cotiza por kilómetros facturables según la categoría y tarifa vigente.
Organiza clientes, pasajeros, responsables, empresas y transportistas.
Reutiliza domicilios y destinos frecuentes.
Define zonas de cobertura por radio o por un perímetro dibujado.
Aplica reglas de aceptación, autorización, asignación, modificación y cancelación.
Controla solicitudes pendientes, asignación y estados del viaje.
Asigna automáticamente al transportista preferido o al disponible más conveniente.
Controla disponibilidad semanal, ausencias, solapamientos y tiempos de traslado entre viajes.
Genera enlaces privados para alta, solicitud de viaje e itinerarios compartibles.
Mantiene una cuenta corriente de transportistas con créditos, débitos y ajustes.
Mantiene el contexto de la conversación para que el agente conozca viajes, horarios, precios y transportistas.
Permite que el agente atienda a clientes, administradores y transportistas según su identidad y permisos.

Secciones de la Mini App

Sección	Para qué se usa
Panel general	Indicadores, próximos viajes, situaciones que necesitan atención y acceso a las instrucciones ideales del agente.
Viajes	Agenda en lista o calendario, filtros, vista diaria por horas y detalle de cada traslado.
Solicitudes	Pedidos que requieren aprobación o asignación, con rechazo y asignación asistida.
Personas	Alta y edición de transportistas, clientes, pasajeros, responsables y empresas.
Cobranzas	Cuenta corriente y movimientos relacionados con transportistas.
Configuración	Estado de preparación, operación general y administradores de direcciones, categorías, zonas, tarifas y reglas.

Orden recomendado de configuración

Para poder cotizar y asignar correctamente, configurá la Mini App en este orden:

Ajustes generales de operación.
Revisá la Categoría por defecto, creada automáticamente.
Creá al menos una tarifa para esa categoría.
Direcciones frecuentes y zonas de operación.
Transportistas y sus puntos iniciales habituales.
Clientes y pasajeros, con domicilio y categoría predeterminada.
Reglas de aceptación, asignación y cancelación.
Vinculación del agente y aplicación de las instrucciones ideales.
Prueba completa desde cada canal que vayas a utilizar.

Configuración general

En Configuración → Operación → Editar definís:

Zona horaria: se usa para interpretar agenda, anticipación y horarios de regreso.
Duración predeterminada: respaldo operativo cuando todavía no existe un cálculo de ruta.
Margen entre viajes: tiempo adicional necesario antes de considerar libre al transportista.
Ventana de recurrencias: cantidad de días futuros que se materializan para viajes repetitivos.
Distancia máxima al origen: límite operativo para el recorrido del transportista hasta buscar al pasajero.
Aprobación humana fuera de WhatsApp: hace que los pedidos de webchat, chat de prueba u otros canales queden pendientes de aprobación administrativa.
Mostrar precio estimado al pasajero: permite decidir si el formulario público y la confirmación conversacional muestran el valor calculado. El administrador siempre conserva acceso al precio.

La aprobación humana no elimina la solicitud: la guarda con estado Pendiente de aprobación para que el operador pueda revisarla.

Categorías de viaje

Las categorías clasifican el servicio y determinan qué tarifa y reglas se aplican. Ejemplos: transporte escolar, traslado médico, viaje particular o traslado corporativo.

Para cada categoría configurá:

Nombre: debe ser fácil de reconocer tanto para operadores como para el agente.
Margen operativo posterior: minutos para descenso, asistencia, entrega o preparación luego del recorrido.
Descripción: explica cuándo corresponde utilizarla.

La duración del traslado no se define en la categoría. Se calcula para cada viaje usando la ruta y el tránsito previsto para el horario solicitado. El margen operativo sí se agrega después de esa duración.

Categoría predeterminada del cliente

En la ficha de cada cliente podés elegir una categoría predeterminada. El agente debe usarla automáticamente para precios y reglas, salvo que la persona pida expresamente otro tipo de viaje.

Toda instancia incluye una Categoría por defecto. Si el cliente no tiene otra categoría asignada, el viaje usa esa categoría automáticamente. El pasajero no necesita conocer esta clasificación interna y el agente no debe mencionarla.

Tarifas

Cada tarifa pertenece a una categoría y se guarda de forma versionada, para conservar qué condiciones se usaron en cotizaciones anteriores.

Precio por kilómetro: valor multiplicado por los kilómetros facturables.
Tarifa mínima: piso monetario aunque el recorrido sea corto.
Kilómetros mínimos: cantidad mínima que se factura.
Moneda: actualmente ARS o USD desde la interfaz.
Redondeo: el cálculo operativo redondea los kilómetros facturables hacia arriba según la configuración vigente.

Ejemplo: si Google calcula 12,1 km y el redondeo es de 1 km, se facturan 13 km. Luego se compara el resultado con la tarifa mínima y se utiliza el mayor valor.

Ajuste manual del precio por tramo

El cálculo automático funciona como valor inicial, pero un administrador puede corregir el precio de cada tramo mientras el viaje esté en borrador, pendiente de aprobación, pendiente de transportista o confirmado.

Abrí el viaje desde la vista Lista o Calendario.
En el tramo que corresponda, seleccioná Editar precio.
Ingresá el nuevo importe y guardá.

El total del viaje se recalcula automáticamente. El sistema conserva el precio calculado originalmente y registra quién hizo el cambio y en qué fecha y hora. La indicación de ajuste manual y su historial son exclusivamente administrativos: no se muestran al pasajero, al transportista ni en el itinerario compartido.

Una vez que el viaje está en curso, completado, cancelado o rechazado, el precio ya no puede modificarse.

Google Maps y direcciones

El origen, el destino, el domicilio del pasajero, el punto inicial del transportista y las direcciones frecuentes deben seleccionarse desde el autocompletado. La selección guarda dirección normalizada, latitud, longitud e identificador de Google.

Las direcciones frecuentes aparecen antes que los resultados generales de Google Maps. Usalas para escuelas, centros médicos, empresas o destinos visitados habitualmente.

El buscador incluye direcciones y lugares —por ejemplo, clínicas, aeropuertos o comercios— siempre que se elija una sugerencia de Google. Escribir texto sin seleccionar un resultado no alcanza para guardar una ubicación exacta.

Para el funcionamiento completo se necesitan:

Maps JavaScript API y la biblioteca Places, para autocompletado y mapa interactivo en el navegador.
Routes API, para distancia, duración y tránsito desde el servidor.
Facturación activa en el proyecto de Google Cloud.
Una clave web restringida por dominio para el frontend y, de ser posible, una clave de servidor restringida para Routes API.

Los mapas públicos de solicitud e itinerario utilizan el modo vial, una presentación en escala de grises y resaltan el recorrido y sus puntos de origen y destino.

Zonas de operación

Una zona representa el área habitual de cobertura. Puede definirse de dos maneras:

Dirección y radio

Seleccioná un punto central desde Google Maps y cargá el radio en kilómetros. Es apropiado para coberturas aproximadamente circulares.

Perímetro personalizado

Abrí el editor de mapa, hacé clic para marcar al menos tres puntos y cerrá el área. Los vértices se pueden arrastrar antes de confirmar. Es apropiado cuando la cobertura sigue barrios, rutas o límites irregulares.

Las zonas pueden activarse o desactivarse y luego utilizarse dentro de las reglas.

Transportistas

Cada transportista puede tener nombre, teléfono, email, documento, estado, vehículo, dominio o patente y punto inicial habitual. El punto inicial permite estimar la distancia no facturable hasta el origen del pasajero.

Estados habituales:

Disponible: puede recibir asignaciones.
No disponible: permanece registrado, pero no debe asignarse.
Inactivo: queda fuera de la operación corriente.

Un transportista autorizado por teléfono puede consultar su agenda y actualizar únicamente sus viajes. No obtiene acceso automático a la agenda de otros transportistas ni a toda la administración.

Disponibilidad semanal

En la ficha del transportista podés cargar varias franjas por día. Los horarios se eligen en intervalos de 15 minutos y muestran claramente a. m. o p. m.. El botón duplicar copia una franja al día siguiente para acelerar cargas repetitivas.

Si no se carga ninguna franja, la disponibilidad se considera abierta. Cuando existen franjas, una asignación debe quedar dentro de ellas.

Al volver a abrir un transportista, los campos Desde y Hasta muestran las horas guardadas. La interfaz también normaliza horarios provenientes de versiones anteriores para que valores con segundos no aparezcan vacíos.

Ausencias

Registrá vacaciones, enfermedad u otras ausencias con fecha de inicio, fecha de fin y motivo. Si la persona ya tiene viajes afectados, la operación permite decidir entre reasignarlos automáticamente o dejarlos sin asignar para revisión manual.

La disponibilidad efectiva también considera:

Viajes que se superponen.
Margen configurado entre servicios.
Tiempo para llegar desde el viaje anterior.
Tiempo necesario para alcanzar el viaje siguiente.
Distancia máxima permitida hasta el origen.

Clientes y pasajeros

Una persona puede representar al cliente que contrata, al pasajero que viaja, a un responsable o a una empresa pagadora. La ficha admite:

Nombre o razón social.
Función.
Teléfono, email y documento.
Domicilio georreferenciado.
Categoría predeterminada.
Transportista habitual.
Observaciones operativas necesarias.

Alta de un cliente nuevo desde el agente

Si el agente no encuentra a la persona, puede generar un enlace personal de alta. El formulario solicita nombre y apellido, teléfono, DNI y domicilio. El domicilio debe seleccionarse desde Google Maps.

El enlace de alta:

Es único y de un solo uso.
Vence según la configuración; el valor predeterminado es 24 horas.
Se invalida después de completar el alta.
Conserva la conversación y el agente que lo generaron.

Después de completar el alta, el sistema notifica al cliente por su nombre y le entrega automáticamente otro enlace para solicitar el viaje. No hace falta que escriba “Listo” ni que vuelva a informar sus datos.

Identificación según el canal

WhatsApp: el agente intenta identificar automáticamente a la persona por su teléfono.
Webchat, chat de prueba y otros canales: el agente no supone una identidad. En un mismo mensaje ofrece enviar el DNI si ya es cliente o completar el enlace de alta si es su primer viaje.
El nombre puede ayudar a encontrar una coincidencia, pero no habilita información privada hasta verificar el DNI.

Una vez usado un enlace de alta o de viaje, la conversación queda vinculada al cliente. Las consultas siguientes recuperan sus viajes sin volver a iniciar el proceso de registro.

Reglas operativas

Las reglas determinan cómo responder ante distintas condiciones. Configurá un nombre claro, tipo, decisión, prioridad y criterios.

Tipos disponibles:

Aceptación o rechazo.
Asignación.
Modificación.
Cancelación.

Decisiones posibles:

Aceptar automáticamente.
Rechazar automáticamente.
Solicitar autorización.

Una regla puede limitarse por categoría, zona, kilómetros mínimos o máximos, distancia del transportista, anticipación, cancelaciones previas y ventana de cancelación sin cargo. También puede notificar al transportista, al administrador, a ambos o a nadie.

Usá prioridades para resolver reglas superpuestas. Si no existe una regla que rechace o solicite autorización, el flujo continúa automáticamente.

Las condiciones de una misma regla se evalúan juntas. Para situaciones diferentes, creá reglas separadas. Ejemplos:

Avisar si el transportista está a más de 20 km: regla de asignación, distancia máxima al origen de 20 km, decisión de revisión y aviso al transportista o a ambos.
Revisar viajes menores a 10 km: regla de aceptación, kilómetros del viaje hasta 10, decisión de revisión y destinatario administrador.
Cobrar una cancelación tardía: regla de cancelación, ventana sin cargo, decisión y cargo administrativo correspondiente.

El editor presenta las reglas como Cuándo, Qué condiciones y Qué debe suceder, y muestra un resumen legible. Un número de prioridad menor se evalúa primero.

Los cargos definidos en este editor corresponden a cancelaciones. El precio base por distancia se configura en Tarifas; no uses una regla operativa para simular una tarifa escalonada.

Crear un viaje

El formulario Nuevo viaje solicita cliente o pasajero, categoría, origen, destino, modalidad y fecha de salida.

Modalidades:

Solo ida.
Ida y vuelta: el regreso vuelve al origen inicial.
Regreso a otro destino: requiere la dirección final del regreso.

Al seleccionar un cliente, el sistema puede sugerir su domicilio como origen, su categoría predeterminada y destinos utilizados anteriormente. Google Maps calcula distancia y duración; la tarifa determina el precio estimado.

Los horarios se eligen en intervalos de 15 minutos y comienzan en la próxima hora completa. El administrador también puede seleccionar un transportista en el mismo formulario para dejar el viaje confirmado desde el alta.

Si el transportista elegido no puede tomar el servicio —por ejemplo, porque queda fuera de sus franjas habituales— el formulario permanece abierto y muestra el motivo devuelto por el sistema. Corregí el horario, elegí otra persona o dejá el viaje sin asignar antes de volver a guardar.

Un viaje atraviesa estados como borrador, pendiente de aprobación, pendiente de transportista, confirmado, en curso, completado, cancelado o rechazado. No debe comunicarse como confirmado hasta que realmente alcance ese estado.

Solicitud mediante el agente

Para clientes, el agente no recopila direcciones y horarios por texto. Después de identificar a la persona genera un enlace personal y de un solo uso que:

Precarga al pasajero y su domicilio como origen.
Sugiere el destino del último viaje cuando existe.
Permite cambiar origen y destino mediante Google Maps.
Ofrece Solo ida, Ida y vuelta o Vuelta a otro destino.
Solicita los horarios necesarios para cada tramo.
Muestra u oculta el precio según la configuración.
Presenta el mapa, recorrido y confirmación final.

Al enviarlo, el agente recibe el resultado en la misma conversación y confirma inmediatamente si quedó aprobado, pendiente o confirmado.

Asignación automática

Si ninguna regla exige revisión y existe disponibilidad, el sistema intenta confirmar el viaje automáticamente:

Prioriza al transportista preferido del pasajero.
Si no puede cubrir todos los tramos, intenta asignarle al menos uno.
Para los restantes, busca transportistas activos y disponibles.
Ordena los candidatos por cercanía real al origen.
Verifica franjas semanales, ausencias, solapamientos, margen entre viajes y tiempo de llegada desde y hacia otros servicios.

Si no encuentra una opción válida, el viaje queda Sin transportista para resolución administrativa.

Asignación asistida

Desde Solicitudes o desde un viaje sin transportista, Asignar abre un asistente en lugar de un desplegable simple. Para cada candidato muestra disponibilidad, distancia al origen, viaje anterior, viaje siguiente, márgenes y motivos por los cuales podría no ser viable. La API vuelve a validar esas condiciones al confirmar para evitar asignaciones incorrectas por cambios simultáneos.

Lista y calendario

La agenda puede verse como lista o calendario y filtrarse por estado, pasajero y fechas.

En Lista, seleccioná cualquier parte libre de una fila para abrir el detalle completo del viaje. También podés hacerlo con teclado usando Enter o la barra espaciadora. Los enlaces de pasajero y transportista, y las acciones Asignar, Aprobar o Rechazar, siguen funcionando de manera independiente y no abren el viaje por accidente.

En Calendario:

Seleccionar un día abre la vista horaria completa.
Seleccionar un espacio vacío inicia un viaje con esa fecha y hora.
Seleccionar un viaje abre su detalle.

Desde ambas vistas, los nombres de pasajero y transportista abren sus fichas en modo consulta; Editar habilita cambios. Desde Personas se abren directamente en edición.

Cobranzas y cuenta corriente

La cuenta corriente registra créditos, débitos, pagos, adelantos y ajustes de cada transportista. Cada movimiento necesita importe, moneda, descripción y una clave de idempotencia para evitar duplicados.

Las correcciones se realizan mediante movimientos compensatorios; no conviene borrar el historial contable.

Itinerario compartible

Después de registrar el viaje, el pasajero puede usar Compartir itinerario. El enlace es de solo consulta y permanece activo hasta ocho horas después del horario previsto del viaje.

La página compartida muestra:

Estado real del viaje.
Fecha y horario.
Direcciones de origen y destino.
Mapa vial en escala de grises con el recorrido resaltado.
Nombre del transportista cuando está asignado.
Vehículo y últimos tres caracteres del dominio, sin exponer la patente completa.

El enlace puede enviarse a familiares, responsables o instituciones. No permite modificar ni cancelar el viaje.

Vincular un agente

Desde la configuración de tools del agente, agregá Transporte de pasajeros, elegí la instancia y guardá. La vinculación debe aparecer entre las tools activas del agente. Después definí permisos para:

Preparar la conversación e identificar al interlocutor.
Consultar información general, categorías y tarifas.
Registrar clientes o generar enlaces de alta.
Consultar viajes y agenda.
Cotizar y crear solicitudes.
Reprogramar o cancelar.
Buscar y asignar transportistas.
Cambiar estados.
Consultar cuentas corrientes.

La herramienta incluye operaciones específicas para preparar la conversación, consultar información, buscar agenda, listar viajes del cliente, cotizar, generar altas y formularios de viaje, reprogramar, cancelar, buscar transportistas, asignar, cambiar estados y consultar cuentas corrientes.

Instrucciones ideales

En el Panel general aparece Instrucciones ideales para tu agente hasta que se abre por primera vez. Luego queda disponible en Configuración. Desde allí podés:

Copiar el texto al portapapeles.
Aplicarlo directamente al agente vinculado.

Estas instrucciones complementan las descripciones de las tools y establecen que el agente debe usar la Mini App como fuente de verdad, verificar identidad, no inventar disponibilidad ni precios y no mencionar categorías internas a pasajeros.

Qué sabe el agente después de una solicitud

El enlace conserva agente, canal, conversación y cliente. Al completar el formulario se persiste y entrega una confirmación en esa misma conversación. Si el usuario pregunta después, el agente recupera:

Estado del viaje.
Origen y destino.
Fecha y horarios.
Precio, cuando esté permitido mostrarlo.
Transportista asignado.
Vehículo y terminación de patente.

No debe volver a pedir DNI ni ofrecer un alta nueva en una conversación ya vinculada.

Prueba recomendada del agente

Antes de publicarlo, realizá estos casos en el chat de test:

Cliente existente reconocido por teléfono en WhatsApp.
En web, mensaje único con alternativa de DNI o enlace de alta.
Cliente existente verificado por DNI y entrega inmediata del formulario de viaje.
Cliente nuevo: alta, confirmación automática y entrega del formulario sin escribir “Listo”.
Domicilio y último destino precargados.
Lugar de Google —por ejemplo, un sanatorio— encontrado y seleccionado.
Solo ida, ida y vuelta y regreso a otro destino.
Precio visible y precio oculto según la configuración.
Asignación automática del transportista preferido y alternativa más cercana.
Solicitud que queda pendiente por una regla o por canal.
Confirmación inmediata en el chat después de enviar el formulario.
Consulta posterior del viaje sin volver a pedir identidad.
Enlace de itinerario compartido y vigente.
Consulta de agenda de un transportista autorizado.
Intento de acceder a viajes ajenos, que debe ser rechazado.

Errores frecuentes

Situación	Qué revisar
No se puede calcular la ruta	Routes API, clave del servidor, facturación y coordenadas de ambos puntos.
No aparecen sugerencias de dirección	Maps JavaScript API, Places, clave web y restricciones de dominio.
El agente no reconoce al cliente	Vinculación activa, teléfono normalizado, DNI o nombre completo exacto.
La tool no aparece	Volvé a guardar la vinculación del agente y reiniciá el servicio MCP si hubo una actualización.
No se calcula el precio	Categoría seleccionada, tarifa vigente y ruta calculada.
No encuentro dónde editar el precio	Abrí el viaje desde Lista o Calendario y usá Editar precio en el tramo correspondiente. Solo está disponible antes de iniciar el viaje.
El viaje queda pendiente	Revisá reglas, asignación y aprobación humana por canal.
No se puede guardar con el transportista elegido	Leé el motivo visible en el formulario. Revisá sus franjas, ausencias, otros viajes y tiempo de traslado; luego cambiá el horario, elegí otro transportista o guardalo sin asignar.
Las franjas horarias aparecen vacías al editar	Volvé a cargar la ficha después de guardar. Los horarios deben mostrarse en intervalos de 15 minutos; si persiste, verificá que frontend y API estén actualizados a la misma versión.
El agente no confirma al enviar el formulario	Verificá que el enlace se haya generado en esa conversación y que API, MCP y el agente del canal estén activos. La confirmación también debe quedar persistida en el historial.
El agente vuelve a pedir DNI después del viaje	Confirmá que se esté usando la misma conversación y que el enlace figure utilizado; la tool recupera al cliente desde ese vínculo.
El itinerario figura vencido inmediatamente	Compartí solo la URL completa. El sistema tolera texto anexado por aplicaciones de compartir, pero no tokens cortados.
El itinerario abre pero no muestra mapa	Maps JavaScript API, clave web, dominio autorizado y coordenadas del recorrido.