Autenticação da API (TrackServiceKey)

As APIs TrackRoad utilizam uma chave de API chamada TrackServiceKey. Para REST, envie-a como X-API-Key. Para SOAP, envie-a em SessionIDHeader como SessionID.

Fluxo de autenticação da API TrackRoad que mostra a TrackServiceKey usada como X-API-Key para REST e SessionIDHeader para SOAP
Visão geral da autenticação: a TrackServiceKey é a sua chave de API — envie-a como X-API-Key para REST e como SessionIDHeader/SessionID para SOAP.

Precisa de endpoints e modelos?

O Swagger fornece os esquemas completos de pedido e resposta para Dispatch, Routes, Route, Geocode, Credit e Distance.

Ver Swagger UI Visão geral da referência da API

Índice

  1. Como funciona a autenticação
  2. Gere a sua TrackServiceKey
  3. Autenticação REST (X-API-Key)
  4. Autenticação SOAP (SessionIDHeader)
  5. Login / Logout (legado)
  6. Boas práticas de segurança
  7. Erros comuns (401/403)
  8. Endpoints relacionados
  9. Perguntas frequentes

Como funciona a autenticação#

O TrackRoad utiliza um único conceito de autenticação em toda a sua superfície de API: a sua TrackServiceKey ao nível da conta.

  • A TrackServiceKey é gerada na sua conta TrackRoad.
  • REST: envie-a em X-API-Key em todos os pedidos.
  • SOAP: envie-a em SessionIDHeader como SessionID em todas as chamadas.

Recomendado para novas integrações: utilize REST sempre que possível e mantenha SOAP apenas para sistemas legados.

Gere a sua TrackServiceKey#

Antes de chamar a API TrackRoad, crie ou copie a sua chave de autenticação a partir da sua conta.

  1. Inicie sessão na sua conta TrackRoad.
  2. Abra Gerir Utilizadores (ou definições da API, se disponível).
  3. Gere ou copie a sua TrackServiceKey.
  4. Guarde-a de forma segura apenas do lado do servidor.

Se não conseguir encontrar a sua TrackServiceKey, contacte o Suporte TrackRoad para ativar ou confirmar o acesso à API.

Autenticação REST (X-API-Key)#

Envie a sua TrackServiceKey no cabeçalho X-API-Key em todos os pedidos REST ao TrackRoad.

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

Mantenha as chaves API no lado do servidor. Não incorpore a TrackServiceKey em JavaScript do navegador, aplicações móveis ou código público do lado do cliente.

Autenticação SOAP (SessionIDHeader)#

As chamadas SOAP autenticam-se usando SessionIDHeader. Para os serviços SOAP do TrackRoad, envie a sua TrackServiceKey como o valor SessionID em todos os pedidos.

Login e Logout podem ainda aparecer em documentação SOAP mais antiga, mas não são necessários para integrações modernas que já utilizam TrackServiceKey.

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

Endpoints Login / Logout (legado)#

Login e Logout são mantidos apenas por compatibilidade retroativa. As novas integrações TrackRoad devem autenticar-se com a TrackServiceKey: REST através de X-API-Key e SOAP através de SessionIDHeader.

Boas práticas de segurança#

Proteger a sua chave API é essencial para integrações de produção fiáveis e seguras.

  • Nunca exponha chaves API em JavaScript de front-end.
  • Utilize integrações seguras servidor-para-servidor ou backend.
  • Armazene as chaves em variáveis de ambiente, gestores de segredos ou repositórios de configuração protegidos.
  • Rode a chave imediatamente se suspeitar de compromisso.
  • Nunca registe nem envie por e-mail chaves API em texto simples.

Erros comuns (401/403)#

Se a autenticação falhar, verifique o nome do cabeçalho, o valor da chave, o ambiente e o estado da conta.

  • 401 Unauthorized: chave em falta ou inválida. Para REST, verifique X-API-Key. Para SOAP, verifique SessionIDHeader e SessionID.
  • 403 Forbidden: a chave pode ser válida, mas o acesso está bloqueado, expirado ou limitado por crédito ou permissões.

Perguntas frequentes#

Como autentico chamadas REST da API TrackRoad?
Envie a sua TrackServiceKey no cabeçalho X-API-Key em todos os pedidos REST.
Como autentico chamadas SOAP do TrackRoad?
Para SOAP, envie a sua TrackServiceKey em SessionIDHeader como SessionID em cada pedido SOAP.
Preciso de Login/Logout?
Não. Os endpoints Login e Logout são legados. As novas integrações devem usar autenticação com TrackServiceKey.
Porque recebo 401 Unauthorized?
As causas comuns incluem um cabeçalho X-API-Key em falta, uma chave inválida, espaços em branco extra ou a utilização do ambiente ou host errado.

Próximo passo: experimente um endpoint

Depois de obter a sua TrackServiceKey, comece por Credit para validar a autenticação e depois continue com Geocode, Route, Routes ou Dispatch.

Verificar Credit Ir para Dispatch