Autenticación de API (TrackServiceKey)

Las API de TrackRoad usan una clave API llamada TrackServiceKey. Para REST, envíela como X-API-Key. Para SOAP, envíela en SessionIDHeader como SessionID.

Flujo de autenticación de la API de TrackRoad que muestra TrackServiceKey usado como X-API-Key para REST y SessionIDHeader para SOAP
Resumen de autenticación: TrackServiceKey es su clave API; envíela como X-API-Key para REST y como SessionIDHeader/SessionID para SOAP.

¿Necesita endpoints y modelos?

Swagger proporciona los esquemas completos de solicitud y respuesta para Dispatch, Routes, Route, Geocode, Credit y Distance.

Ver Swagger UI Resumen de la referencia API

Tabla de contenidos

  1. Cómo funciona la autenticación
  2. Genere su TrackServiceKey
  3. Autenticación REST (X-API-Key)
  4. Autenticación SOAP (SessionIDHeader)
  5. Login / Logout (legado)
  6. Buenas prácticas de seguridad
  7. Errores comunes (401/403)
  8. Endpoints relacionados
  9. FAQ

Cómo funciona la autenticación#

TrackRoad utiliza un único concepto de autenticación en toda su superficie API: su TrackServiceKey a nivel de cuenta.

  • El TrackServiceKey se genera en su cuenta de TrackRoad.
  • REST: envíelo en X-API-Key en cada solicitud.
  • SOAP: envíelo en SessionIDHeader como SessionID en cada llamada.

Recomendación para nuevas integraciones: use REST siempre que sea posible y deje SOAP solo para sistemas heredados.

Genere su TrackServiceKey#

Antes de llamar a la API de TrackRoad, cree o copie su clave de autenticación desde su cuenta.

  1. Inicie sesión en su cuenta de TrackRoad.
  2. Abra Manage Users (o la configuración de la API, si está disponible).
  3. Genere o copie su TrackServiceKey.
  4. Guárdelo de forma segura solo en el servidor.

Si no puede encontrar su TrackServiceKey, contacte con el soporte de TrackRoad para habilitar o confirmar el acceso a la API.

Autenticación REST (X-API-Key)#

Envíe su TrackServiceKey en el encabezado X-API-Key en cada solicitud REST a TrackRoad.

curl -X POST "https://trackservice.trackroad.com/rest/credit" \
  -H "X-API-Key: YOUR_TRACKSERVICEKEY"

Mantenga las claves API en el servidor. No incluya TrackServiceKey en JavaScript del navegador, aplicaciones móviles ni código cliente público.

Autenticación SOAP (SessionIDHeader)#

Las llamadas SOAP se autentican mediante SessionIDHeader. Para los servicios SOAP de TrackRoad, envíe su TrackServiceKey como valor de SessionID en cada solicitud.

Login y Logout aún pueden aparecer en documentación SOAP antigua, pero no son necesarios para integraciones modernas que ya usan TrackServiceKey.

<soap:Header>
  <SessionIDHeader xmlns="http://TrackService.TrackRoad.com/">
    <SessionID>YOUR_TRACKSERVICEKEY</SessionID>
  </SessionIDHeader>
</soap:Header>

Endpoints Login / Logout (legado)#

Login y Logout se mantienen solo por compatibilidad con versiones anteriores. Las nuevas integraciones de TrackRoad deben autenticarse con TrackServiceKey: REST mediante X-API-Key y SOAP mediante SessionIDHeader.

Buenas prácticas de seguridad#

Proteger su clave API es esencial para integraciones de producción seguras y confiables.

  • Nunca exponga claves API en JavaScript del front-end.
  • Use integraciones seguras de servidor a servidor o backend.
  • Guarde las claves en variables de entorno, gestores de secretos o almacenes de configuración seguros.
  • Rote la clave inmediatamente si sospecha que ha sido comprometida.
  • Nunca registre ni envíe por correo claves API en texto plano.

Errores comunes (401/403)#

Si la autenticación falla, verifique el nombre del encabezado, el valor de la clave, el entorno y el estado de la cuenta.

  • 401 Unauthorized: clave faltante o no válida. En REST, revise X-API-Key. En SOAP, revise SessionIDHeader y SessionID.
  • 403 Forbidden: la clave puede ser válida, pero el acceso está bloqueado, ha expirado o está limitado por crédito o permisos.

FAQ#

¿Cómo autentico llamadas a la API REST de TrackRoad?
Envíe su TrackServiceKey en el encabezado X-API-Key en cada solicitud REST.
¿Cómo autentico llamadas SOAP de TrackRoad?
Para SOAP, envíe su TrackServiceKey en SessionIDHeader como SessionID en cada solicitud SOAP.
¿Necesito Login/Logout?
No. Los endpoints Login y Logout son heredados. Las nuevas integraciones deben usar autenticación con TrackServiceKey.
¿Por qué recibo 401 Unauthorized?
Las causas comunes incluyen un encabezado X-API-Key ausente, una clave no válida, espacios en blanco adicionales o el uso del entorno o host incorrecto.

Siguiente paso: pruebe un endpoint

Cuando tenga su TrackServiceKey, comience con Credit para validar la autenticación y luego continúe con Geocode, Route, Routes o Dispatch.

Comprobar Credit Ir a Dispatch