← HomeFleetPay / API

Purchase a mandatory toll voucher

Parameters, data structure and responses from the versioned contract.

POST/vale-pedagio/comprar

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

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

Completes the purchase and issuance of the mandatory toll voucher (Vale-Pedágio Obrigatório) with ANTT and the accredited operator.

The total amount (toll charges + the service fee for the selected method) is debited immediately from the contracting company's or shipper's Swap Operational Account.

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`

EmitirVpoRequest ↗

transportador_documentostringRequired

Contracted carrier's CPF or CNPJ (digits only).

maxLength20

transportador_rntrcstringRequired

Carrier's RNTRC (FleetPay checks with ANTT; ANTT's RNTRC takes precedence).

maxLength20

transportador_nomestring | nullOptional

Carrier name (optional; defaults to ANTT's name when absent).

maxLength150

placastringRequired

Vehicle license plate (with an operator tag and listed in the RNTRC fleet).

maxLength10

eixosintegerRequired

Axle count.

minimum2

maximum10

operadorastring | nullOptional

Toll operator.

"sem_parar" · "conectcar" · "veloe" · "move_mais"

modalidadestringRequired

Route option.

"planejada" · "estendida" · "customizada"

valor_pedagionumberRequired

Quoted route toll amount (rotas[n].valor_total).

minimum0.01

vigencia_iniciostring · dateRequired

Validity start date (YYYY-MM-DD).

vigencia_fimstring · dateRequired

Validity end date (YYYY-MM-DD).

pracasarrayRequired

Required for sem_parar. Toll plazas from the selected quoted route (rotas[n].pracas), including each plaza's id. You may resend the quote objects unchanged.

minItems1

numero_ciotstring | nullOptional

CIOT number for the transport operation.

maxLength50

referencia_externastring | nullOptional

Your reference (order, trip).

maxLength100

origem_cidadestring | nullOptional

Origin city.

origem_ufstring | nullOptional

Origin state.

maxLength2

destino_cidadestring | nullOptional

Destination city.

destino_ufstring | nullOptional

Destination state.

maxLength2

desvio_autorizado_porstring | nullOptional

For a supplementary voucher: who authorized the detour.

"embarcador" · "motorista"

emuladoboolean | nullOptional

Sandbox only. When true, issuance actually takes place with the operator (trip, ANTT number, receipt, cancellation), but no amount is debited from or refunded to the Operational Account. In production, the request is rejected (422).

Responses

201 HTTP Response

Toll voucher issued and successfully registered with ANTT

`application/json`

EmitirVpoResponse ↗

successbooleanOptional

dataobjectOptional

ValePedagioEmitido ↗

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

422 HTTP Response

Insufficient Operational Account balance or operator validation error

`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": "Comprar e emitir Vale-Pedágio Obrigatório (VPO)",
  "operationId": "comprarValePedagio",
  "description": "Efetiva a compra e emissão do Vale-Pedágio Obrigatório perante a ANTT e a operadora credenciada.\n\nO valor total (tarifas de pedágio + tarifa de serviço da modalidade) é **debitado instantaneamente\nda Conta Operacional Swap** da empresa contratante/embarcadora.\n",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/EmitirVpoRequest"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Vale-Pedágio emitido e registrado com sucesso na ANTT",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/EmitirVpoResponse"
          }
        }
      }
    },
    "400": {
      "$ref": "#/components/responses/Erro400"
    },
    "401": {
      "$ref": "#/components/responses/Erro401"
    },
    "403": {
      "$ref": "#/components/responses/Erro403"
    },
    "422": {
      "description": "Saldo insuficiente na Conta Operacional ou erro de validação da operadora",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/Erro429"
    },
    "500": {
      "$ref": "#/components/responses/Erro500"
    }
  },
  "method": "POST",
  "path": "/vale-pedagio/comprar",
  "parameters": []
}