API de Lista de Rotas (Listar Rotas Guardadas)

Q: Qual é o equivalente SOAP da API de Lista de Rotas?

O nome do método SOAP é GetRouteList.

Q: Como faço a autenticação?

Para SOAP, envie a sua TrackServiceKey em SessionIDHeader como SessionID. Login e Logout não são necessários quando utiliza TrackServiceKey.

Use a API de Lista de Rotas da TrackRoad para obter rotas anteriormente guardadas usando filtros como intervalo de datas, proprietário e nome da rota. Para integrações SOAP, o método equivalente é GetRouteList.

Liste e filtre rotas anteriormente guardadas para relatórios, dashboards e pesquisas no histórico de rotas.

Precisa do contrato completo?

O Swagger inclui modelos de endpoint e campos para REST, enquanto o WSDL expõe o contrato SOAP para GetRouteList e métodos relacionados.

Ver Swagger UI Ver WSDL SOAP Visão geral da Referência da API

O que faz a API de Lista de Rotas#

A API de Lista de Rotas devolve uma lista de rotas guardadas para a sua conta. É normalmente usada em vistas de histórico de rotas, dashboards e ecrãs de pesquisa onde os utilizadores precisam de encontrar rotas previamente geradas.

Os filtros típicos incluem intervalo de datas de criação, proprietário e nome da rota. Isto ajuda a manter as pesquisas de rotas rápidas, focadas e mais fáceis de gerir em frotas maiores.

Se precisar dos detalhes completos de uma rota, incluindo paragens, direções e tempos, use a API de Rota .

Endpoints e URLs base#

A documentação da Lista de Rotas abaixo centra-se no padrão de integração SOAP mostrado por GetRouteList. Siga a documentação da sua conta e o Swagger quando os detalhes específicos da implementação forem diferentes.

SOAP

Item	Valor
Endpoint	https://trackservice.trackroad.com/TrackService.asmx
WSDL	https://trackservice.trackroad.com/TrackService.asmx?WSDL
Método	`GetRouteList`
SOAPAction	http://TrackService.TrackRoad.com/GetRouteList

Autenticação#

Para SOAP, envie a sua TrackServiceKey em SessionIDHeader como SessionID. Login e Logout não são necessários quando utiliza TrackServiceKey.

Mantenha as chaves de API no lado do servidor e evite expor valores de autenticação no código do browser ou de clientes móveis.

Esquema do pedido#

O pedido descreve os filtros usados para encontrar rotas guardadas. Em SOAP, estes valores são passados como parâmetros de GetRouteList.

Campos do filtro da lista de rotas

Campo	Tipo	Obrigatório	Descrição
`FromDate`	string (date-time)	Não	Filtra rotas criadas ou atualizadas nesta data/hora ou depois dela, no formato ISO 8601.
`ToDate`	string (date-time)	Não	Filtra rotas criadas ou atualizadas nesta data/hora ou antes dela, no formato ISO 8601.
`Owner`	string	Não	Filtra por proprietário ou nome de utilizador, se isso for suportado pela configuração da sua conta.
`RouteName`	string	Não	Filtra pelo nome da rota usando correspondência exata ou parcial, consoante a implementação.

Se a sua implementação expuser filtros adicionais como estado, paginação ou número máximo de resultados, documente também esses campos adicionais aqui.

Esquema da resposta#

Uma resposta com sucesso devolve uma lista de rotas que correspondem aos seus filtros e qualquer informação de estado ou erro devolvida pelo serviço.

Resultado das rotas

Propriedade	Tipo	Descrição
`Routes`	RouteSummary[]	Lista de registos de resumo de rota correspondentes.
`Errors`	Error[]	Erros ou avisos opcionais devolvidos pelo serviço.
`Status`	int (enum)	Código de estado, normalmente 0=None, 1=Success, 2=Failed, 3=SuccessWithErrors.

Resumo da rota

Propriedade	Tipo	Descrição
`RouteID`	string / int	Identificador da rota usado posteriormente para obter os detalhes completos da rota.
`RouteName`	string	Nome da rota legível para humanos.
`Distance`	double	Distância total da rota.
`Time`	int	Tempo total da rota, normalmente em segundos, salvo configuração diferente.
`Owner`	string	Identificador do proprietário ou criador, quando disponível.
`DateCreated`	string (date-time)	Marca temporal que mostra quando a rota foi criada.

SOAP devolve o mesmo conceito de lista de rotas dentro de um envelope SOAP, com o resultado encapsulado por elementos de resposta GetRouteList.

Exemplos#

Coloque nesta secção o pedido SOAP de exemplo, a resposta de exemplo e amostras de código em várias linguagens. O próprio código de exemplo não precisa de ser localizado.

SOAP: request examples (multiple languages)#

SOAP requires SessionIDHeader (SessionID = TrackServiceKey) and the SOAPAction header http://TrackService.TrackRoad.com/GetRouteList.

<!-- POST https://trackservice.trackroad.com/TrackService.asmx -->
<!-- Content-Type: text/xml; charset=utf-8 -->
<!-- SOAPAction: "http://TrackService.TrackRoad.com/GetRouteList" -->

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">

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

  <soap:Body>
    <GetRouteList xmlns="http://TrackService.TrackRoad.com/">
      <FromDate>2026-01-01T00:00:00Z</FromDate>
      <ToDate>2026-01-31T23:59:59Z</ToDate>
      <Owner>dispatcher@company.com</Owner>
      <RouteName>January</RouteName>
    </GetRouteList>
  </soap:Body>
</soap:Envelope>

curl -X POST "https://trackservice.trackroad.com/TrackService.asmx" \
  -H "Content-Type: text/xml; charset=utf-8" \
  -H "SOAPAction: \"http://TrackService.TrackRoad.com/GetRouteList\"" \
  --data-binary @getroutelist.soap.xml

using System.Net.Http;
using System.Text;

var url = "https://trackservice.trackroad.com/TrackService.asmx";

var soap = @"

  
    
      YOUR_TRACKSERVICEKEY
    
  
  
    
      2026-01-01T00:00:00Z
      2026-01-31T23:59:59Z
      dispatcher@company.com
      January
    
  
";

using var http = new HttpClient();
using var content = new StringContent(soap, Encoding.UTF8, "text/xml");

content.Headers.Clear();
content.Headers.TryAddWithoutValidation("Content-Type", "text/xml; charset=utf-8");

var req = new HttpRequestMessage(HttpMethod.Post, url);
req.Headers.TryAddWithoutValidation("SOAPAction", "\"http://TrackService.TrackRoad.com/GetRouteList\"");
req.Content = content;

var resp = await http.SendAsync(req);
Console.WriteLine(await resp.Content.ReadAsStringAsync());

const url = "https://trackservice.trackroad.com/TrackService.asmx";

const soap = `

  
    
      YOUR_TRACKSERVICEKEY
    
  
  
    
      2026-01-01T00:00:00Z
      2026-01-31T23:59:59Z
      dispatcher@company.com
      January
    
  
`;

const res = await fetch(url, {
  method: "POST",
  headers: {
    "Content-Type": "text/xml; charset=utf-8",
    "SOAPAction": "\"http://TrackService.TrackRoad.com/GetRouteList\""
  },
  body: soap
});

console.log(await res.text());

import okhttp3.*;

public class Main {
  public static void main(String[] args) throws Exception {
    OkHttpClient client = new OkHttpClient();

    String soap = ""
      + ""
      + ""
      + ""
      + "YOUR_TRACKSERVICEKEY"
      + ""
      + ""
      + ""
      + ""
      + "2026-01-01T00:00:00Z"
      + "2026-01-31T23:59:59Z"
      + "dispatcher@company.com"
      + "January"
      + ""
      + ""
      + "";

    RequestBody body = RequestBody.create(soap, MediaType.parse("text/xml; charset=utf-8"));
    Request request = new Request.Builder()
      .url("https://trackservice.trackroad.com/TrackService.asmx")
      .post(body)
      .addHeader("SOAPAction", "\"http://TrackService.TrackRoad.com/GetRouteList\"")
      .build();

    try (Response response = client.newCall(request).execute()) {
      System.out.println(response.body().string());
    }
  }
}

import requests

url = "https://trackservice.trackroad.com/TrackService.asmx"
soap = """

  
    
      YOUR_TRACKSERVICEKEY
    
  
  
    
      2026-01-01T00:00:00Z
      2026-01-31T23:59:59Z
      dispatcher@company.com
      January
    
  
"""

headers = {
  "Content-Type": "text/xml; charset=utf-8",
  "SOAPAction": "\"http://TrackService.TrackRoad.com/GetRouteList\""
}

r = requests.post(url, data=soap.encode("utf-8"), headers=headers)
print(r.text)

<?php
$url = "https://trackservice.trackroad.com/TrackService.asmx";

$soap = '<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema"
               xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
  <soap:Header>
    <SessionIDHeader xmlns="http://TrackService.TrackRoad.com/">
      <SessionID>YOUR_TRACKSERVICEKEY</SessionID>
    </SessionIDHeader>
  </soap:Header>
  <soap:Body>
    <GetRouteList xmlns="http://TrackService.TrackRoad.com/">
      <FromDate>2026-01-01T00:00:00Z</FromDate>
      <ToDate>2026-01-31T23:59:59Z</ToDate>
      <Owner>dispatcher@company.com</Owner>
      <RouteName>January</RouteName>
    </GetRouteList>
  </soap:Body>
</soap:Envelope>';

$ch = curl_init($url);
curl_setopt_array($ch, [
  CURLOPT_POST => true,
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_HTTPHEADER => [
    "Content-Type: text/xml; charset=utf-8",
    "SOAPAction: \"http://TrackService.TrackRoad.com/GetRouteList\""
  ],
  CURLOPT_POSTFIELDS => $soap
]);

echo curl_exec($ch);
curl_close($ch);

require "net/http"

uri = URI("https://trackservice.trackroad.com/TrackService.asmx")
http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

soap = <<~XML


  
    
      YOUR_TRACKSERVICEKEY
    
  
  
    
      2026-01-01T00:00:00Z
      2026-01-31T23:59:59Z
      dispatcher@company.com
      January
    
  

XML

req = Net::HTTP::Post.new(uri)
req["Content-Type"] = "text/xml; charset=utf-8"
req["SOAPAction"] = "\"http://TrackService.TrackRoad.com/GetRouteList\""
req.body = soap

res = http.request(req)
puts res.body

package main

import (
  "bytes"
  "fmt"
  "io"
  "net/http"
)

func main() {
  url := "https://trackservice.trackroad.com/TrackService.asmx"

  soap := []byte(`

  
    
      YOUR_TRACKSERVICEKEY
    
  
  
    
      2026-01-01T00:00:00Z
      2026-01-31T23:59:59Z
      dispatcher@company.com
      January
    
  
`)

  req, _ := http.NewRequest("POST", url, bytes.NewBuffer(soap))
  req.Header.Set("Content-Type", "text/xml; charset=utf-8")
  req.Header.Set("SOAPAction", "\"http://TrackService.TrackRoad.com/GetRouteList\"")

  resp, err := http.DefaultClient.Do(req)
  if err != nil { panic(err) }
  defer resp.Body.Close()

  b, _ := io.ReadAll(resp.Body)
  fmt.Println(string(b))
}

import java.net.URI
import java.net.http.HttpClient
import java.net.http.HttpRequest
import java.net.http.HttpResponse

fun main() {
  val url = "https://trackservice.trackroad.com/TrackService.asmx"
  val soap = """
    
    
      
        
          YOUR_TRACKSERVICEKEY
        
      
      
        
          2026-01-01T00:00:00Z
          2026-01-31T23:59:59Z
          dispatcher@company.com
          January
        
      
    
  """.trimIndent()

  val client = HttpClient.newHttpClient()
  val req = HttpRequest.newBuilder()
    .uri(URI.create(url))
    .header("Content-Type", "text/xml; charset=utf-8")
    .header("SOAPAction", "\"http://TrackService.TrackRoad.com/GetRouteList\"")
    .POST(HttpRequest.BodyPublishers.ofString(soap))
    .build()

  val resp = client.send(req, HttpResponse.BodyHandlers.ofString())
  println(resp.body())
}

#include <stdio.h>
#include <curl/curl.h>

int main(void) {
  CURL *curl = curl_easy_init();
  if(!curl) return 1;

  const char *url = "https://trackservice.trackroad.com/TrackService.asmx";
  const char *soap =
    ""
    ""
    ""
    ""
    "YOUR_TRACKSERVICEKEY"
    ""
    ""
    ""
    ""
    "2026-01-01T00:00:00Z"
    "2026-01-31T23:59:59Z"
    "dispatcher@company.com"
    "January"
    ""
    ""
    "";

  struct curl_slist *headers = NULL;
  headers = curl_slist_append(headers, "Content-Type: text/xml; charset=utf-8");
  headers = curl_slist_append(headers, "SOAPAction: \"http://TrackService.TrackRoad.com/GetRouteList\"");

  curl_easy_setopt(curl, CURLOPT_URL, url);
  curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
  curl_easy_setopt(curl, CURLOPT_POSTFIELDS, soap);

  CURLcode res = curl_easy_perform(curl);

  curl_slist_free_all(headers);
  curl_easy_cleanup(curl);

  return (res == CURLE_OK) ? 0 : 1;
}

#include <curl/curl.h>
#include <string>

int main() {
  CURL* curl = curl_easy_init();
  if(!curl) return 1;

  std::string url = "https://trackservice.trackroad.com/TrackService.asmx";
  std::string soap =
    ""
    ""
    ""
    ""
    "YOUR_TRACKSERVICEKEY"
    ""
    ""
    ""
    ""
    "2026-01-01T00:00:00Z"
    "2026-01-31T23:59:59Z"
    "dispatcher@company.com"
    "January"
    ""
    ""
    "";

  struct curl_slist* headers = NULL;
  headers = curl_slist_append(headers, "Content-Type: text/xml; charset=utf-8");
  headers = curl_slist_append(headers, "SOAPAction: \"http://TrackService.TrackRoad.com/GetRouteList\"");

  curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
  curl_easy_setopt(curl, CURLOPT_HTTPHEADER, headers);
  curl_easy_setopt(curl, CURLOPT_POSTFIELDS, soap.c_str());

  CURLcode res = curl_easy_perform(curl);

  curl_slist_free_all(headers);
  curl_easy_cleanup(curl);

  return (res == CURLE_OK) ? 0 : 1;
}

#import <Foundation/Foundation.h>

int main() {
  @autoreleasepool {
    NSURL *url = [NSURL URLWithString:@"https://trackservice.trackroad.com/TrackService.asmx"];
    NSMutableURLRequest *req = [NSMutableURLRequest requestWithURL:url];
    [req setHTTPMethod:@"POST"];
    [req setValue:@"text/xml; charset=utf-8" forHTTPHeaderField:@"Content-Type"];
    [req setValue:@"\"http://TrackService.TrackRoad.com/GetRouteList\"" forHTTPHeaderField:@"SOAPAction"];

    NSString *soap = @""
      ""
      ""
      ""
      "YOUR_TRACKSERVICEKEY"
      ""
      ""
      ""
      ""
      "2026-01-01T00:00:00Z"
      "2026-01-31T23:59:59Z"
      "dispatcher@company.com"
      "January"
      ""
      ""
      "";

    [req setHTTPBody:[soap dataUsingEncoding:NSUTF8StringEncoding]];

    NSURLSessionDataTask *task =
      [[NSURLSession sharedSession] dataTaskWithRequest:req
      completionHandler:^(NSData *data, NSURLResponse *response, NSError *error) {
        if (error) { NSLog(@"%@", error); return; }
        NSString *text = [[NSString alloc] initWithData:data encoding:NSUTF8StringEncoding];
        NSLog(@"%@", text);
      }];

    [task resume];
    [[NSRunLoop currentRunLoop] run];
  }
  return 0;
}

import Foundation

let url = URL(string: "https://trackservice.trackroad.com/TrackService.asmx")!
var req = URLRequest(url: url)
req.httpMethod = "POST"
req.setValue("text/xml; charset=utf-8", forHTTPHeaderField: "Content-Type")
req.setValue("\"http://TrackService.TrackRoad.com/GetRouteList\"", forHTTPHeaderField: "SOAPAction")

let soap = """


  
    
      YOUR_TRACKSERVICEKEY
    
  
  
    
      2026-01-01T00:00:00Z
      2026-01-31T23:59:59Z
      dispatcher@company.com
      January
    
  

"""

req.httpBody = soap.data(using: .utf8)

let task = URLSession.shared.dataTask(with: req) { data, _, error in
  if let error = error { print(error); return }
  print(String(data: data ?? Data(), encoding: .utf8) ?? "")
}
task.resume()
RunLoop.main.run()

SOAP: response example (shape)#

<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"
               xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xmlns:xsd="http://www.w3.org/2001/XMLSchema">
  <soap:Body>
    <GetRouteListResponse xmlns="http://TrackService.TrackRoad.com/">
      <GetRouteListResult>
        <Routes>
          <RouteSummary>
            <RouteID>12345</RouteID>
            <RouteName>January - North Zone</RouteName>
            <Distance>82.4</Distance>
            <Time>14250</Time>
            <Owner>dispatcher@company.com</Owner>
            <DateCreated>2026-01-12T16:21:00Z</DateCreated>
          </RouteSummary>
        </Routes>
        <Status>1</Status>
        <Errors />
      </GetRouteListResult>
    </GetRouteListResponse>
  </soap:Body>
</soap:Envelope>

Erros comuns#

Erro de autenticação: SessionIDHeader em falta ou inválido. O valor de SessionID deve ser a sua TrackServiceKey.
Formato de data inválido: Forneça datas no formato ISO 8601, por exemplo 2026-01-31T23:59:59Z.
Sem rotas correspondentes: O seu intervalo de filtro, proprietário ou nome da rota pode ser demasiado restritivo.
Problema de serviço ou permissão: A chave pode ser válida, mas estar bloqueada, expirada ou limitada para o âmbito da conta solicitado.

Boas práticas#

Use filtros de data para manter as respostas rápidas e previsíveis, especialmente para ecrãs de histórico de rotas.
Coloque listas de rotas em cache para dashboards carregados com frequência, e atualize sob pedido quando os utilizadores pesquisarem novamente.
Carregue os detalhes da rota apenas quando necessário em vez de obter dados completos da rota para cada linha de resultado.
Documente campos específicos da conta quando a sua implementação suportar filtros adicionais ou propriedades de resposta personalizadas.

Perguntas frequentes#

O que faz a API de Lista de Rotas?

A API de Lista de Rotas devolve uma lista de rotas previamente guardadas, normalmente filtradas por intervalo de datas, proprietário ou nome da rota.

Qual é o equivalente SOAP da API de Lista de Rotas?

O nome do método SOAP é GetRouteList.

Como faço a autenticação?