Emitir un vale de peaje complementario por desvío

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

POST/vale-pedagio/{uuid}/complemento

emitirComplementoValePedagioBase 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.

Emite un vale de peaje complementario vinculado a un VPO existente por un desvío autorizado del trayecto o la incorporación de plazas de peaje.

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

uuidpath · stringObligatorio

UUID del vale de peaje obligatorio devuelto al emitir (/vale-pedagio/comprar).

Restricciones

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

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 complementario emitido correctamente

`application/json`

ComplementoVpoResponse ↗

successbooleanOpcional

dataobjectOpcional

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

404 Respuesta HTTP

Vale de peaje de origen no encontrado

`application/json`

Erro ↗

errorobjectOpcional

422 Respuesta HTTP

Saldo insuficiente o error de validación

`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": "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"
}