Prepare-se para usar a API

Começando

Nossa equipe preza por oferecer aos seus clientes serviços confiáveis e de qualidade, visando um alto ganho de produtividade. Pensando nisso, criamos a API Rotas Brasil para permitir que suas aplicações possam integrar diretamente com o nosso sistema realizando os cálculos de custo de suas viagens.

Tenha em poucos segundos (até milissegundos) a distância, tempo e o quanto irá custar sua viagem (incluindo pedágio, combustível e tabela frete).

Para começar é simples, basta realizar o Login ou Cadastrar-se para ganhar 50 créditos e testar qualquer serviço da nossa API. Cada requisição/consulta realizada com sucesso corresponde a 1 crédito.

Com o cadastro realizado, você receberá um Token de acesso à nossa API. É através dele que você fará suas requisições. Seu token está disponível no Perfil ou em qualquer lugar do sistema que estiver "SeuToken" (será substituído pelo mesmo, caso esteja logado).

Caso tenha qualquer dúvida sobre como utilizar a API, você pode entrar em Contato, que iremos te atender da melhor forma possível 😊.

EndPoints

Requisições

Como fazer uma requisição?

Com o objetivo de facilitar a integração com a API do Rotas Brasil, unificamos todas as consultas em um único endpoint. Em requisições do tipo GET será possível efetuar consultas por Coordenadas, Endereços, CEP e Código IBGE. Nas requisições POST será permitido todas as anteriores, além de consultas por Polyline.

EndPoints:

Requisição GET

Nas requisições do tipo GET, basta montar sua Query String com os parâmetros desejados e adicioná-la a URL Base

Para realizar a requisição será utilizado o parâmetro pontos, por meio dele será possível fornecer os endereços de origem, destino e de pontos intermediários(se houver).

Os valores aceitos no parâmetro pontos podem ser:

Coordenadas: Longitude, Latitude;
Endereços: Cidade, Estado;
CEP: CEP;
Código IBGE: CodIBGE.

Você pode optar pelo uso de somente o tipo de um valor ou combina-los de acordo com necessidade.

Exemplo de Query String: ?pontos=Curitiba,pr;20040-070&veiculo=caminhao&eixos=6

Exemplos de requisições: URL BASE + QUERY STRING

Requisição POST

Para requisições do tipo POST, é necessário enviar os parâmetros da mesma forma explicada anteriormente, mas por meio de um formData.

Na requisição POST também é possível realizar consultas utilizando o parâmetro polyline para o envio de polylines de rotas já calculadas previamente.

Nota 1: Esse método de requisição permite consultas por Coordenadas, Endereços, CEP, Código IBGE e Polyline. Para que seja possível realizar as consultas utilizando qualquer forma de entrada em um único endpoint, adicionamos o parâmetro polyline para receber apenas polylines e o parâmetro pontos para os demais.
Nota 2: Caso em uma mesma requisição seja enviado os dois parâmetros (pontos e polyline), será considerado o parâmetro polyline para a realização da consulta.

Parâmetros

Opções

Parâmetros aceitos:

Token Token do usuário em que deseja realizar a consulta. Obrigatório
Pontos Coordenada, nome, CEP ou Código IBGE do endereço. Obrigatório
Veiculo Tipo do veículo no qual deseja consultar os valores dos pedágios. Obrigatório
Eixos Quantidade de eixos do veículo a ser consultado. Obrigatório
Combustivel Preço do combustível desejado para o cálculo do valor gasto de combustível no percurso. Opcional
Consumo Quantos quilômetros o veículo faz por litro de combustível. Opcional
Paradas Caso deseje que os endereços enviados para o cálculo da rota seja exibido na resposta. Opcional
Tabela Tipo da tabela frete que deseja realizar o cálculo do frete mínimo. Opcional ***
Volta Realiza o cálculo de ida e volta da rota. Opcional
UFs Retorna todos os estados que a rota percorre. Opcional
RotaAlternativa Retorna rotas alternativas, caso existir(Não é garantido que retorne). Opcional
Evitar Usado para que a rota seja calculada desviando pedágios ou balsas Opcional
DataTarifa Define as datas das tarifas de acordo com nossa base de históricos de valores Opcional
Detalhes Retorna um objeto com detalhes da rota, como link para visualizar a polyline e imagem estática da rota. Opcional
Nota 1: Caso não seja informado será considerado: tabela = "a"; dataTarifa = data em que a consulta está sendo realizada. Os parâmetros opcionais por padrão são definidos como false.
Nota 2: Ao informar o parâmetro detalhes=true, será retornado um objeto com links para acessar a polyline e imagem estática da rota(png ou jpeg). Importante: será cobrado 1(um) crédito por request do link, tanto para polyline quanto para imagem. Caso o parâmetro seja informado e o link NÃO seja acessado, NÃO será gerado débito a mais, além do da consulta.

Valores dos parâmetros disponíveis:

Campo Exemplo
pontos String. Coordenada, nome, CEP ou Código IBGE do endereço. ponta grossa,parana;19970-000
veiculo String. Valores: auto, caminhao, onibus ou moto. veiculo=auto
eixos Integer. Auto e Ônibus: 2 ≤ Integer ≤ 4. Caminhão 2 ≤ Integer ≤ 10. veiculo=auto&eixo=2
combustivel Float combustivel=3.10
consumo Float consumo=10.00
paradas Boolean paradas=true
tabela String tabela=a
volta Boolean volta=true
ufs Boolean ufs=true
rotaAlternativa Boolean rotaAlternativa=true
evitar String. pedagio ou balsa evitar=pedagio
dataTarifa String. 2021-05-07. Ordem: YYYY-MM-DD dataTarifa=2021-05-07
detalhes Boolean detalhes=true

Respostas

Retornos

Possíveis retornos:

Code Descrição
200 Sucesso Consulta realizada com sucesso
400 Falha nos parâmetros enviados para consulta Mensagem do possível erro de requisição
401 Falha ao autenticar Verifique seu token ou informa a senha se consulta configurada no perfil do usuário
402 Créditos insuficientes O token não possui créditos suficientes para realizar a consulta. Entre em contato com nossa equipe para solicitar mais créditos
500 Erro interno Ocorreu um erro ao realizar essa consulta, tente novamente mais tarde ou entre em contato com nosso suporte

Exemplos de retornos:

Requisição de Ponta Grossa, Paraná para Curitiba, Paraná realizada com sucesso.

{
    "code": 200,
    "mensagem": "Sucesso",
    "descricao": "Consulta realizada com sucesso",
    "saldo": 50,
    "veiculo": "caminhao",
    "eixos": {
        "valor": 2,
        "texto": "2"
    },
    "paradas": [
        {
            "nomeExibicao": "Ponta Grossa, Paraná, BR",
            "nome": "Ponta Grossa",
            "rua": null,
            "distrito": null,
            "bairro": null,
            "cidade": null,
            "estado": "Paraná",
            "latitude": {
                "valor": -25.0891685,
                "texto": "-25.0891685"
            },
            "longitude": {
                "valor": -50.1601812,
                "texto": "-50.1601812"
            }
        },
        {
            "nomeExibicao": "Curitiba, Paraná, BR",
            "nome": "Curitiba",
            "rua": null,
            "distrito": null,
            "bairro": null,
            "cidade": null,
            "estado": "Paraná",
            "latitude": {
                "valor": -25.4295963,
                "texto": "-25.4295963"
            },
            "longitude": {
                "valor": -49.2712724,
                "texto": "-49.2712724"
            }
        }
    ],
    "rotas": [
        {
            "via": "Rodovia do Café Governador Ney Braga, Rodovia do Café Governador Ney Braga",
            "distancia": {
                "valor": 117.41,
                "texto": "117.41"
            },
            "duracao": {
                "texto": "1h34min",
                "horas": 1,
                "minutos": 34
            },
            "ufs": [
                "PR"
            ],
            "valorPedagio": {
                "valor": 40.00,
                "texto": "40.00"
            },
            "valorCombustivel": "Valor do combustível ou consumo não informado",
            "tabelasFrete": [
                {
                    "granelSolido": {
                        "valor": 483.90,
                        "texto": "483.90"
                    },
                    "granelLiquido": {
                        "valor": 493.42,
                        "texto": "493.42"
                    },
                    "frigorificada": {
                        "valor": 574.57,
                        "texto": "574.57"
                    },
                    "conteinerizada": {
                        "valor": 0.00,
                        "texto": "0.00"
                    },
                    "geral": {
                        "valor": 481.48,
                        "texto": "481.48"
                    },
                    "neoGranel": {
                        "valor": 452.03,
                        "texto": "452.03"
                    },
                    "perigosaGranelSolido": {
                        "valor": 658.30,
                        "texto": "658.30"
                    },
                    "perigosaGranelLiquido": {
                        "valor": 679.38,
                        "texto": "679.38"
                    },
                    "perigosaFrigorificada": {
                        "valor": 705.11,
                        "texto": "705.11"
                    },
                    "perigosaConteinerizada": {
                        "valor": 0.00,
                        "texto": "0.00"
                    },
                    "perigosaGeral": {
                        "valor": 582.48,
                        "texto": "582.48"
                    },
                    "perigosaGranelPressurizada": {
                        "valor": 0.00,
                        "texto": "0.00"
                    },
                    "informacoes": {
                        "tipoTabela": "A",
                        "resolucao": "5.949",
                        "data": "20/07/2021",
                        "link": "https://www.in.gov.br/en/web/dou/-/resolucao-n-5.949-de-13-de-julho-de-2021-331886614"
                    }
                }
            ],
            "numPedagios": 2,
            "pedagios": [
                {
                    "praca": "Witmarsum",
                    "concessionaria": "RODONORTE",
                    "rodovia": "BR-376",
                    "km": "573,000",
                    "tarifa": {
                        "valor": 21.6,
                        "texto": "21.6",
                        "dataVigente": "2021-04-24T03:00:00Z"
                    },
                    "distanciaOrigem": {
                        "valor": 47.46,
                        "texto": "47.46"
                    }
                },
                {
                    "praca": "São Luiz Purunã",
                    "concessionaria": "RODONORTE",
                    "rodovia": "BR-277",
                    "km": "132,000",
                    "tarifa": {
                        "valor": 18.4,
                        "texto": "18.4",
                        "dataVigente": "2021-04-24T03:00:00Z"
                    },
                    "distanciaOrigem": {
                        "valor": 72.48,
                        "texto": "72.48"
                    }
                }
            ],
            "link": "https://rotasbrasil.com.br/?alternative=0&return=false&pt0=-50.1601812%C-25.0891685&ptStop0=true&pt1=-49.2712724%C-25.4295963&ptStop1=true&&veiculo=2&eixo=2&precoCombustivel=&consumo=&return=false"
        }
    ]
}
                

Requisição com erro de parâmetros.

{
    "code": 400,
    "mensagem": "Falha nos parâmetros enviados para consulta"
    "descricao": "O parametro pontos não foi informado."
}

                

Requisição não autorizada.

{
    "code": 401,
    "mensagem": "Falha ao autenticar"
    "descricao": "Para realizar a consulta é necessário informar a senha configurada para consultas na API"
}
                

Requisição não autorizada por falta de saldo.

{
    "code": 402,
    "mensagem": "Créditos insuficientes.",
    "descricao": "O token não possui créditos suficientes para realizar a consulta. Entre em contato com nossa equipe para solicitar mais créditos"
}
                

Requisição com erro de parâmetros.

{
    "code": 500,
    "mensagem": "Erro interno"
    "descricao": "Ocorreu um erro ao realizar essa consulta, tente novamente mais tarde ou entre em contato com nosso suporte"
}
                

Autenticação

Segurança

Como fazer uma requisição?

Para realizar uma consulta na API é necessário enviar seu token junto da requisição. Você pode visualizar seu token aqui.

Caso queira reforçar a segurança das consultas, você pode definir uma senha que será exigida em todas as consultas. Basta habilitar essa configuração aqui.

Para aqueles que desejarem habilitar a opção de exigir senha na consulta, disponibilizamos um endpoint especifico para a alteração da senha. O retorno dessa solicitação é uma senha aleatória e pode ser redefinida sempre que desejar

Requisição GET POST

Parâmetros

token Token do usuário em que deseja realizar a consulta. Obrigatório
email E-mail da conta associada ao token Obrigatório
senha Senha da conta associada ao token Obrigatório

Resposta da requisição

{
    "code": 200,
    "mensagem": "Sucesso",
    "descricao": "Consulta realizada com sucesso",
    "token": "SeuToken",
    "senha": "senhaAleatoria"
}
                

Consulta saldo

Créditos

Como fazer uma requisição?

Para consultar seu saldo, basta enviar o seu Token através do parâmetro token . Essa requisição não consumira créditos, lembrando que qualquer consulta realizada nos demais serviços retornam seu saldo com a resposta da requisição.

Requisição GET

Nas requisições do tipo GET, basta montar sua Query String com o parâmetro token e adicioná-la a URL Base

Exemplos de requisições: URL BASE + QUERY STRING

Requisição POST

Para requisições do tipo POST, é necessário enviar o parâmetro token através de um formData.

Testar consulta

Parâmetros

Preencha os campos da forma que desejar realizar sua consulta

Retorno

                                

Perguntas Frequêntes

Dúvidas

O que é um token?

O token é sua chave de acesso para utilizar a API, sem ele não há como realizar consultas. Seu token está localizado na página documentação ou no perfil do usuário.

Como é o sistema de cobrança da API?

Cada consulta na API é equivalente a um crédito.

Exemplos de consultas:

Consulta Parâmetro volta Crédito gasto
São Paulo, SP -> Curitiba, PR false 1
São Paulo, SP -> Ponta Grossa, PR -> Curitiba, PR false 1
São Paulo, SP -> Curitiba, PR -> São Paulo, SP false 1
São Paulo, SP -> Curitiba true 1
São Paulo, SP -> Curitiba, PR -> São Paulo, SP true 1
Possui limite de consultas por tempo?

Atualmente o rate limit é de 5 consultas por segundo. Caso sua aplicação necessite de um rate limit maior, entre em contato com nossa equipe de suporte.