Uwierzytelnianie API (TrackServiceKey)

Interfejsy API TrackRoad używają klucza API o nazwie TrackServiceKey. W przypadku REST wyślij go jako X-API-Key. W przypadku SOAP wyślij go w SessionIDHeader jako SessionID.

Przepływ uwierzytelniania API TrackRoad pokazujący użycie TrackServiceKey jako X-API-Key dla REST i SessionIDHeader dla SOAP
Przegląd uwierzytelniania: TrackServiceKey to Twój klucz API — wysyłaj go jako X-API-Key dla REST oraz jako SessionIDHeader/SessionID dla SOAP.

Potrzebujesz endpointów i modeli?

Swagger udostępnia pełne schematy żądań i odpowiedzi dla Dispatch, Routes, Route, Geocode, Credit i Distance.

Zobacz Swagger UI Przegląd dokumentacji API

Spis treści

  1. Jak działa uwierzytelnianie
  2. Wygeneruj swój TrackServiceKey
  3. Uwierzytelnianie REST (X-API-Key)
  4. Uwierzytelnianie SOAP (SessionIDHeader)
  5. Login / Logout (starsze)
  6. Najlepsze praktyki bezpieczeństwa
  7. Typowe błędy (401/403)
  8. Powiązane endpointy
  9. FAQ

Jak działa uwierzytelnianie#

TrackRoad używa jednej koncepcji uwierzytelniania w całym swoim API: Twojego klucza TrackServiceKey na poziomie konta.

  • TrackServiceKey jest generowany na Twoim koncie TrackRoad.
  • REST: wysyłaj go w nagłówku X-API-Key przy każdym żądaniu.
  • SOAP: wysyłaj go w SessionIDHeader jako SessionID przy każdym wywołaniu.

Zalecane dla nowych integracji: używaj REST wszędzie tam, gdzie to możliwe, a SOAP pozostaw tylko dla systemów starszego typu.

Wygeneruj swój TrackServiceKey#

Przed wywołaniem API TrackRoad utwórz lub skopiuj swój klucz uwierzytelniający z konta.

  1. Zaloguj się do swojego konta TrackRoad.
  2. Otwórz Manage Users (lub ustawienia API, jeśli są dostępne).
  3. Wygeneruj lub skopiuj swój TrackServiceKey.
  4. Przechowuj go bezpiecznie wyłącznie po stronie serwera.

Jeśli nie możesz znaleźć swojego TrackServiceKey, skontaktuj się z pomocą techniczną TrackRoad, aby włączyć lub potwierdzić dostęp do API.

Uwierzytelnianie REST (X-API-Key)#

Wysyłaj swój TrackServiceKey w nagłówku X-API-Key przy każdym żądaniu REST do TrackRoad.

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

Przechowuj klucze API po stronie serwera. Nie umieszczaj TrackServiceKey w JavaScript uruchamianym w przeglądarce, aplikacjach mobilnych ani publicznym kodzie po stronie klienta.

Uwierzytelnianie SOAP (SessionIDHeader)#

Wywołania SOAP są uwierzytelniane za pomocą SessionIDHeader. W przypadku usług SOAP TrackRoad wysyłaj swój TrackServiceKey jako wartość SessionID w każdym żądaniu.

Login i Logout mogą nadal pojawiać się w starszej dokumentacji SOAP, ale nie są wymagane w nowoczesnych integracjach, które już używają TrackServiceKey.

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

Endpointy Login / Logout (starsze)#

Login i Logout są utrzymywane wyłącznie ze względu na zgodność wsteczną. Nowe integracje TrackRoad powinny uwierzytelniać się za pomocą TrackServiceKey: REST przez X-API-Key oraz SOAP przez SessionIDHeader.

Najlepsze praktyki bezpieczeństwa#

Ochrona klucza API jest niezbędna dla niezawodnych i bezpiecznych integracji produkcyjnych.

  • Nigdy nie ujawniaj kluczy API w frontendowym JavaScript.
  • Używaj bezpiecznych integracji serwer-serwer lub backendowych.
  • Przechowuj klucze w zmiennych środowiskowych, menedżerach sekretów lub zabezpieczonych magazynach konfiguracji.
  • Natychmiast zmień klucz, jeśli podejrzewasz jego kompromitację.
  • Nigdy nie zapisuj ani nie wysyłaj kluczy API e-mailem w postaci jawnego tekstu.

Typowe błędy (401/403)#

Jeśli uwierzytelnianie się nie powiedzie, sprawdź nazwę nagłówka, wartość klucza, środowisko oraz status konta.

  • 401 Unauthorized: brakujący lub nieprawidłowy klucz. Dla REST sprawdź X-API-Key. Dla SOAP sprawdź SessionIDHeader oraz SessionID.
  • 403 Forbidden: klucz może być prawidłowy, ale dostęp jest zablokowany, wygasł lub jest ograniczony przez kredyt albo uprawnienia.

FAQ#

Jak uwierzytelniać wywołania REST API TrackRoad?
Wysyłaj swój TrackServiceKey w nagłówku X-API-Key przy każdym żądaniu REST.
Jak uwierzytelniać wywołania SOAP TrackRoad?
W przypadku SOAP wysyłaj swój TrackServiceKey w SessionIDHeader jako SessionID przy każdym żądaniu SOAP.
Czy potrzebuję Login/Logout?
Nie. Endpointy Login i Logout są starszego typu. Nowe integracje powinny używać uwierzytelniania TrackServiceKey.
Dlaczego otrzymuję 401 Unauthorized?
Najczęstsze przyczyny to brak nagłówka X-API-Key, nieprawidłowy klucz, dodatkowe spacje lub użycie niewłaściwego środowiska albo hosta.

Następny krok: wypróbuj endpoint

Gdy masz już swój TrackServiceKey, zacznij od Credit, aby zweryfikować uwierzytelnianie, a następnie przejdź do Geocode, Route, Routes lub Dispatch.

Sprawdź Credit Przejdź do Dispatch