Comprar un vale de peaje obligatorio

Parámetros, estructura de datos y respuestas del contrato versionado.

POST/vale-pedagio/comprar

comprarValePedagioBase de Pruebas: https://api.fleetpay.site/v1

Las descripciones técnicas se traducen del contrato versionado. Se conservan los identificadores y el JSON originales; se omiten los ejemplos de datos.

Completa la compra y emisión del Vale-Pedágio Obrigatório ante ANTT y la operadora acreditada.

El importe total (peajes + tarifa de servicio de la modalidad) se debita de inmediato de la Cuenta Operativa Swap de la empresa contratante o cargadora.

Autenticación

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

La disponibilidad depende del entorno, los permisos habilitados y el proveedor. Esta referencia no ejecuta solicitudes ni recibe credenciales.

Parámetros

No hay parámetros declarados para esta operación.

Cuerpo de la Solicitud

Obligatorio

`application/json`

EmitirVpoRequest ↗

transportador_documentostringObligatorio

CPF o CNPJ del transportista contratado (solo números).

maxLength20

transportador_rntrcstringObligatorio

RNTRC del transportista (FleetPay lo verifica en la ANTT; prevalece el RNTRC de la ANTT).

maxLength20

transportador_nomestring | nullOpcional

Nombre del transportista (opcional; si se omite, se utiliza el nombre de la ANTT).

maxLength150

placastringObligatorio

Matrícula del vehículo (con tag en la operadora e incluido en la flota del RNTRC).

maxLength10

eixosintegerObligatorio

Cantidad de ejes.

minimum2

maximum10

operadorastring | nullOpcional

Operadora de peaje.

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

modalidadestringObligatorio

Modalidad de la ruta.

"planejada" · "estendida" · "customizada"

valor_pedagionumberObligatorio

Peaje de la ruta cotizada (rotas[n].valor_total).

minimum0.01

vigencia_iniciostring · dateObligatorio

Inicio de vigencia (AAAA-MM-DD).

vigencia_fimstring · dateObligatorio

Fin de vigencia (AAAA-MM-DD).

pracasarrayObligatorio

Obligatorio para sem_parar. Plazas de la ruta elegida en la cotización (rotas[n].pracas), con el id de cada una. Puedes reenviar los objetos de la cotización sin cambios.

minItems1

numero_ciotstring | nullOpcional

Número de CIOT de la operación de transporte.

maxLength50

referencia_externastring | nullOpcional

Tu referencia (pedido, viaje).

maxLength100

origem_cidadestring | nullOpcional

Ciudad de origen.

origem_ufstring | nullOpcional

Estado de origen.

maxLength2

destino_cidadestring | nullOpcional

Ciudad de destino.

destino_ufstring | nullOpcional

Estado de destino.

maxLength2

desvio_autorizado_porstring | nullOpcional

En el complemento: quién autorizó el desvío.

"embarcador" · "motorista"

emuladoboolean | nullOpcional

Solo homologación. Con true, la emisión ocurre realmente en la operadora (viaje, número ANTT, recibo, cancelación), pero no se debita ni se devuelve ningún importe de la Cuenta Operativa. En producción, la solicitud se rechaza (422).

Respuestas

201 Respuesta HTTP

Vale de peaje emitido y registrado correctamente en la ANTT

`application/json`

EmitirVpoResponse ↗

successbooleanOpcional

dataobjectOpcional

ValePedagioEmitido ↗

400 Respuesta HTTP

Solicitud inválida

`application/json`

Erro ↗

errorobjectOpcional

401 Respuesta HTTP

Sin autenticación (autenticacao): credencial ausente, inválida o vencida, incluida una clave API utilizada en el entorno incorrecto. La clave de homologación no es válida en producción, ni la de producción en homologación; el mensaje de error indica el entorno esperado.

`application/json`

Erro ↗

errorobjectOpcional

403 Respuesta HTTP

Ámbito no habilitado para esta credencial

`application/json`

Erro ↗

errorobjectOpcional

422 Respuesta HTTP

Saldo insuficiente en la Cuenta Operativa o error de validación de la operadora

`application/json`

Erro ↗

errorobjectOpcional

429 Respuesta HTTP

Límite de solicitudes excedido (limite_requisicoes). Espera el intervalo indicado en el encabezado Retry-After antes de reintentar. Puede provenir del proveedor o del límite antiabuso de FleetPay, calculado por empresa autenticada y grupo de rutas, con una ventana corta para ráfagas y otra larga para tráfico automatizado lento. Los límites son amplios deliberadamente: las integraciones reales, incluidos lotes grandes procesados de una vez, deberían quedar muy por debajo. Si tu integración alcanza un límite, contacta con FleetPay.

`application/json`

Erro ↗

errorobjectOpcional

500 Respuesta HTTP

Error interno (erro_interno)

`application/json`

Erro ↗

errorobjectOpcional

Definición Completa de la Operación

{
  "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": []
}