← HomeFleetPay / API

Issue an additional toll voucher for a detour

Parameters, data structure and responses from the versioned contract.

POST/vale-pedagio/{uuid}/complemento

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

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

Issues a supplementary toll voucher linked to an existing VPO due to an authorized route deviation or additional toll plazas.

Authentication

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

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

Parameters

uuidpath · stringRequired

Mandatory toll voucher UUID returned at issuance (/vale-pedagio/comprar).

Constraints

{
  "type": "string",
  "format": "uuid"
}

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

Supplementary toll voucher issued successfully

`application/json`

ComplementoVpoResponse ↗

successbooleanOptional

dataobjectOptional

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

404 HTTP Response

Original toll voucher not found

`application/json`

Erro ↗

errorobjectOptional

422 HTTP Response

Insufficient balance or 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": "Emitir Vale-Pedágio complementar por desvio de rota",
  "operationId": "emitirComplementoValePedagio",
  "description": "Emite um Vale-Pedágio complementar vinculado a um VPO existente em decorrência de desvio\nautorizado de trajeto ou acréscimo de praças de pedágio.\n",
  "parameters": [
    {
      "$ref": "#/components/parameters/VpoUuid"
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/EmitirVpoRequest"
        }
      }
    }
  },
  "responses": {
    "201": {
      "description": "Vale-Pedágio complementar emitido com sucesso",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/ComplementoVpoResponse"
          }
        }
      }
    },
    "401": {
      "$ref": "#/components/responses/Erro401"
    },
    "403": {
      "$ref": "#/components/responses/Erro403"
    },
    "404": {
      "description": "Vale-Pedágio de origem não encontrado",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "422": {
      "description": "Saldo insuficiente ou erro de validação",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/Erro"
          }
        }
      }
    },
    "429": {
      "$ref": "#/components/responses/Erro429"
    },
    "500": {
      "$ref": "#/components/responses/Erro500"
    }
  },
  "method": "POST",
  "path": "/vale-pedagio/{uuid}/complemento"
}