A requisição por um serviço do web service é feita utilizando a tecnologia REST. Para utilizar os serviços do web service é necessário um token. Com ele é possível realizar a autenticação para concluir a requisição. O token pode ser obtido entrando em contato com o setor responsável pelo site Vá de Ônibus na Fetranspor. Um token possui uma validade (de um dia à vários meses) definida pela Fetranspor e após o término da sua validade as requisições não serão mais concluídas. Cabe ao cliente requisitar um novo token à Fetranspor.
As requisições(buscas) são criadas com o formato de uma URL. Podemos dividir esta URL em 3 partes: URL base, serviço, parâmetros.
É a primeira parte da string que formará a URL:
Com esta URL base, você estará sempre utilizando esta versão em específico da API.
Para utilizar sempre a versão mais recente utilize apenas VdoWS no lugar de VdoWS1.0. Para mais detalhes, por favor consulte a página Como utilizar uma versão específica(ou sempre a mais recente) do Web Service.
Nesta segunda parte da URL indicamos qual serviço do web service desejamos utilizar. Os serviços disponíveis desta versão são:
Note que os nomes são todos em letras minúsculas.
A terceira e última parte da URL é formada pelos parâmetros. A partir dos parâmetros são passadas as informações da busca como local de origem e local de destino para calcular uma rota, por exemplo. Todos os parâmetros deverão ser passados sem acentos e devem respeitar maiúsculas e minúsculas. Note que o token sempre deverá ser passado por parâmetro, pois sem ele a autenticação não poderá ser realizada e a busca não será concluída. Para passar os parâmetros deve-se seguir o seguinte padrão, que é o utilizado normalmente pelo GET do protocolo HTTP:
Segue abaixo o exemplo de uma URL:
http://api.vadeonibus.com.br/VdoWS1.0/vdoconsulta/obteritinerarioxy?token=seutoken&id=19
Como vimos, a URL do exemplo acima começa com o endereço base: http://api.vadeonibus.com.br/VdoWS1.0/vdoconsulta. Logo depois, indicamos qual serviço desejamos utilizar, que neste caso é o obteritinerarioxy. Este serviço irá retornar os pontos (X, Y) que formam o itinerário. Mas como dizer ao web service qual itinerário desejamos buscar? Basta passar o id do itinerário como parâmetro. Note que é necessário passar também o token como parâmetro.
Todos os serviços do web service do Vá de Ônibus retornam um texto(String) no formato JSON. Cada serviço tem seu próprio tipo de retorno em JSON com campos diferentes, que são detalhados nas suas respectivas páginas da documentação.