Conectar Samsara: llevar el GPS de los vehículos a tracking
Genere un API Token en el Samsara Dashboard en Settings → API Tokens con acceso de lectura a fleet, vehicles y stats, péguelo en Integration, elija la URL base de EE. UU. o de la UE según su región, pruebe, mapee y active.
El conector de Samsara lee el GPS de los vehículos de su flota de Samsara (para cada vehículo, la hora GPS, la latitud y la longitud, el rumbo, la velocidad y el nombre del lugar buscado para esa posición) y convierte esas posiciones en eventos de tracking en TMS, para seguir un envío en tránsito por vehículo. Ese es su único trabajo: solo lee ubicaciones de vehículos. No trae pedidos, no crea despachos ni cargas, no lee registros del conductor ni horas de servicio y no escribe nada de vuelta en Samsara. Una conexión trabaja con un API Token de Samsara.
Requisitos previos#
- Una cuenta de flota de Samsara con vehículos que reportan GPS, y los vehículos que quiere seguir ya configurados en Samsara.
- Permiso en el Samsara Dashboard para abrir Settings → API Tokens y generar un token. Generar un token es una tarea del lado del administrador: si no puede ver esa página, pida a su administrador de Samsara que cree el token por usted.
- El token debe tener acceso de lectura a fleet, vehicles y stats. Un token generado sin el acceso de lectura a stats no puede leer las stats GPS de las que vive esta conexión, y la prueba y las lecturas fallarán por permiso.
- Usted sabe a qué región pertenece su cuenta de Samsara. Las cuentas de EE. UU. usan https://api.samsara.com; las cuentas de la UE usan https://api.eu.samsara.com. La región decide base_url, y la región equivocada no responderá para su flota.
Obtener credenciales#
- Inicie sesión en el Samsara Dashboard con una cuenta que pueda gestionar API tokens y abra Settings → API Tokens.
- Genere un API Token nuevo para esta integración. Al generarlo, conceda acceso de lectura a fleet, vehicles y stats, los tres, porque la conexión lee el GPS de los vehículos desde las stats de la flota.
- Copie el token que Samsara le muestra, completo. Empieza con samsara_api_ seguido de una larga cadena de caracteres. Cópielo en el momento de generarlo y téngalo listo para pegar: trátelo como una contraseña desde este momento.
- Al mismo tiempo, confirme una vez más su región: EE. UU. si su cuenta está en el lado estadounidense, UE si está en el lado europeo. Usará esa respuesta para base_url en el paso siguiente.
Completar en Integration#
- Abra Integration → Marketplace → Samsara → Nueva conexión.
- api_token, obligatorio, API Token: pegue el token completo que generó en el Samsara Dashboard en Settings → API Tokens, que empieza con samsara_api_. Es un campo de tipo contraseña y se guarda como secreto.
- base_url, opcional, Base URL: este campo es su selector de región. Déjelo vacío, o complete https://api.samsara.com, para una cuenta de EE. UU. Los clientes de la UE deben completar https://api.eu.samsara.com en su lugar: con una dirección de EE. UU., una flota de la UE no responderá.
Probar la conexión#
Haga clic en Probar la conexión. Con un token completado, la prueba envía una solicitud real de solo lectura: GET {base_url}/fleet/vehicles/stats?types=gps con su token como credencial Bearer, con un tiempo límite de 12 segundos. Cuando aprueba, el resultado lo confirma con palabras: la autenticación con Bearer token pasó y el endpoint de ubicaciones de vehículos responde. Una respuesta 401 o 403 significa que el token fue rechazado: es incorrecto, ya no es válido o le falta el acceso de lectura que el endpoint necesita. Una solicitud que no responde a tiempo se reporta como timeout. Corrija la causa y pruebe de nuevo: la prueba no cambia ningún dato en Samsara.
Mapping / elegir plantilla#
Elija el mapping estándar de Samsara. Toma cada registro GPS de vehículo (hora, latitud y longitud, rumbo, velocidad y el nombre del lugar de la posición) y lo convierte en un evento de tracking de TMS para ese vehículo, de modo que las posiciones coinciden con el vehículo y el envío que sigue en TMS. Tras aprobar la prueba, ejecute una lectura y compare un vehículo que sepa que está en ruta: contraste su última posición, rumbo y velocidad aquí con el mismo vehículo en Samsara. Si coinciden, el mapping es correcto y puede activar.
Activar#
Tras activar, la conexión lee el GPS de los vehículos de Samsara con su token y mantiene el tracking de TMS actualizado con las últimas posiciones, rumbos y velocidades de la flota. Vigile las primeras lecturas en Runs / Logs y compare algunos vehículos con Samsara antes de dejar la conexión sin supervisión.
Lo que esta conexión no hace: no trae pedidos ni cargas de Samsara, no crea ni cambia despachos, no lee registros del conductor, horas de servicio, registros de cámaras ni de sensores, y no envía posiciones ni ningún otro dato de vuelta a Samsara. Siga gestionando eso en el propio Samsara o en los sistemas donde el trabajo ocurre realmente.
Preguntas frecuentes#
La prueba falla con 401: el token es rechazado
Samsara no aceptó el valor de api_token. Las causas habituales están en el propio valor: se pegó solo en parte, se pegó un token antiguo que ya no es válido, o se pegó en el campo un valor que no es un API Token de Samsara.
Vaya al Samsara Dashboard → Settings → API Tokens, genere un token nuevo con acceso de lectura a fleet, vehicles y stats, cópielo completo (empieza con samsara_api_), péguelo en api_token, guarde y pruebe de nuevo.
La prueba falla con 403: al token le falta acceso de lectura
El token llegó a Samsara, pero no tiene permiso para leer lo que la prueba pide. Esta conexión lee el GPS de los vehículos desde las stats de la flota, así que un token generado sin acceso de lectura a fleet, vehicles y stats es rechazado en este endpoint aunque el token en sí exista.
Genere un token nuevo en el Samsara Dashboard → Settings → API Tokens y esta vez conceda acceso de lectura a fleet, vehicles y stats antes de copiarlo. Pegue el token nuevo en api_token, guarde y pruebe de nuevo: el token antiguo no se puede editar, su acceso quedó fijado cuando se generó.
La prueba agota el tiempo y nunca responde
La solicitud de stats GPS no respondió en 12 segundos. Es un problema de alcance en el camino a la API de Samsara, la mayoría de las veces una base_url que apunta a la región equivocada para su flota, o una lentitud temporal de la API de Samsara, no una prueba de que el token esté mal.
Revise primero base_url contra su región: https://api.samsara.com para EE. UU., https://api.eu.samsara.com para la UE. Corríjala si apunta a la otra región y pruebe de nuevo. Si el timeout se repite con la región correcta, espere un poco y reinténtelo, y conserve la hora del fallo de Runs / Logs cuando pida ayuda.
Flota de la UE: todo parece correcto, pero la prueba sigue fallando
La conexión sigue apuntando a la dirección de API de EE. UU. base_url usa por defecto https://api.samsara.com, y una cuenta de la UE no responde allí: el token y su acceso pueden ser perfectos y aun así la flota de la UE no responderá en la dirección estadounidense.
Ajuste base_url a https://api.eu.samsara.com, guarde y pruebe la misma conexión de nuevo con el mismo token: no genere un token nuevo ni cambie nada más primero.
Conectado, pero un vehículo no muestra GPS
La conexión devuelve el GPS que Samsara tiene de la flota: si el propio Samsara no tiene un GPS actual para ese vehículo (vehículo apagado, fuera de cobertura o sin reportar), no hay nada que este sistema pueda mostrar para él. Una conexión sana no puede inventar una posición que Samsara no tiene.
Revise primero ese mismo vehículo en Samsara. Si Samsara muestra una posición actual y este sistema no, ejecute una lectura manual, compare el vehículo en Runs / Logs y pruebe la conexión de nuevo. Si Samsara tampoco muestra nada, corrija el reporte de ese vehículo en el lado de Samsara.
¿Por qué no llegan pedidos ni despachos por Samsara?
Porque este conector solo lee ubicaciones GPS de vehículos. Los pedidos, las cargas y los despachos no forman parte de lo que puede leer de Samsara, así que una lista de pedidos vacía aquí es el comportamiento esperado, no una conexión rota.
Siga creando y gestionando pedidos y despachos en los sistemas donde ese trabajo ocurre, y use esta conexión para lo que hace: seguir en el tracking de TMS a los vehículos que llevan esos envíos, con posición, rumbo y velocidad.