← HomeFleetPay / API

Plan a route and calculate toll charges

Parameters, data structure and responses from the versioned contract.

POST/vale-pedagio/roteirizar

roteirizarValePedagioSandbox Base: https://api.fleetpay.site/v1

Technical descriptions are translated from the versioned contract. Original identifiers and JSON are preserved; data examples are omitted.

Calculates the road route between origin and destination, identifying toll plazas along the way, individual toll charges for the specified axle count, and consolidated costs by route type (planejada, estendida, and customizada).

To specify the path (a particular highway or a route from your route planner), provide pontos_parada — intermediate cities or coordinates in trip order. The operator routes through these points and returns the toll plazas; purchase (/vale-pedagio/comprar) uses the selected route's toll plazas, not its geometry.

Authentication

[
  {
    "oauth2": []
  },
  {
    "chaveApi": []
  }
]

Availability depends on the environment, enabled scopes and provider. This reference does not execute requests or collect credentials.

Parameters

No parameters declared for this operation.

Request Body

Required

`application/json`

CotarVpoRequest ↗

origemstringRequired

Postal code (with or without a hyphen) or departure city name/address.

minLength3

maxLength150

destinostringRequired

Postal code (with or without a hyphen) or destination city name/address.

minLength3

maxLength150

eixosintegerRequired

Total axle count of the commercial vehicle or vehicle combination.

minimum2

maximum10

placastring | nullOptional

Commercial vehicle license plate (Mercosur or legacy Brazilian format).

maxLength10

modalidadestring | nullOptional

Requested route option (planejada: optimized direct route; estendida: route allowing detours; customizada: specific toll plazas).

"planejada" · "estendida" · "customizada"

pontos_paradaarray | nullOptional

Intermediate waypoints, in the order the vehicle visits them, between origem and destino. The operator does not accept a polyline: the route is defined by waypoints. Each waypoint can be a city (cidade, in "City, State" format) or a latitude/longitude pair in decimal degrees (for example, relevant vertices of your own route). If a waypoint includes both a city and coordinates, the city takes precedence. Use this field to route through a specific highway or reproduce a route from your routing engine. Without this field, the operator chooses the route between origin and destination.

VpoPontoParada ↗

maxItems20

tipo_rotastring | nullOptional

Operator's criterion for determining the main route between the points.

"mais_rapida" · "mais_curta"

Responses

200 HTTP Response

Routes and toll charges calculated successfully

`application/json`

CotarVpoResponse ↗

successbooleanOptional

rotasarrayOptional

RotaPedagio ↗

400 HTTP Response

Invalid request

`application/json`

Erro ↗

errorobjectOptional

401 HTTP Response

Unauthenticated (autenticacao): missing, invalid or expired credentials, including an API key used in the wrong environment. A sandbox key is not valid in production, nor a production key in the sandbox; the error message indicates the expected environment.

`application/json`

Erro ↗

errorobjectOptional

403 HTTP Response

Scope not enabled for these credentials

`application/json`

Erro ↗

errorobjectOptional

429 HTTP Response

Request limit exceeded (limite_requisicoes). Wait for the interval specified in the Retry-After header before retrying. This may be a limit forwarded from the provider or FleetPay's own anti-abuse limit, counted per authenticated company and route group, with a short window for bursts and a long window for slower automated traffic. Limits are intentionally generous: genuine integrations, including large batches processed at once, should remain well below them. If yours reaches a limit, contact FleetPay.

`application/json`

Erro ↗

errorobjectOptional

500 HTTP Response

Internal error (erro_interno)

`application/json`

Erro ↗

errorobjectOptional

Complete Operation Definition

{
  "tags": [
    "Vale-Pedágio (VPO)"
  ],
  "summary": "Roteirizar trajeto e calcular tarifas de pedágio",
  "operationId": "roteirizarValePedagio",
  "description": "Calcula o trajeto rodoviário entre origem e destino, identificando as praças de pedágio no percurso,\nvalores tarifários unitários para a quantidade de eixos informada e os custos consolidados por modalidade\nde rota (`planejada`, `estendida` e `customizada`).\n\nPara forçar o trajeto (rodovia específica, rota do seu roteirizador), informe `pontos_parada` — cidades\nou coordenadas intermediárias, na ordem da viagem. A operadora traça a rota por esses pontos e devolve as\npraças; a compra (`/vale-pedagio/comprar`) usa as praças da rota escolhida, não a geometria.\n",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/CotarVpoRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Rotas e tarifas de pedágio calculadas com sucesso",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/CotarVpoResponse"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/Erro400"
    },
    "401": {
      "$ref": "#/components/responses/Erro401"
    },
    "403": {
      "$ref": "#/components/responses/Erro403"
    },
    "429": {
      "$ref": "#/components/responses/Erro429"
    },
    "500": {
      "$ref": "#/components/responses/Erro500"
    }
  },
  "method": "POST",
  "path": "/vale-pedagio/roteirizar",
  "parameters": []
}