Skip to content
/
Pedágio free flow
Last updated

Pedágio free flow

Quem é você. Você opera uma concessão de rodovia com cobrança por OCR ou RFID, sem cancela física — a cobrança é gerada após a passagem do veículo.

Problema. O motorista precisa estar cadastrado num sistema de pagamento automático ou recebe cobrança postal tardia. Resultado: inadimplência alta e custo de cobrança manual subindo.

Solução Movvia. Você publica cada passagem detectada como cobrança na API. A Movvia distribui para toda a rede de canais de quitação — portais oficiais, totens em rodovia e apps de parceiros (carteiras, bancos). O motorista paga onde é mais conveniente, e você recebe o repasse com identificação do canal e do meio de pagamento.

Como encaixa no seu produto

  • Cada passagem capturada pelo sensor vira uma chamada POST /ec-api/v1/passagens com tipo: "FREEFLOW".
  • A passagem entra no pool da Movvia e fica disponível para qualquer canal autorizado reservar e pagar.
  • Você é notificado quando um canal reserva a passagem (lock para pagamento) e quando o pagamento é confirmado — com NSU, TX ID, método e origem.
  • Passagens não pagas dentro do prazo regular voltam ao seu fluxo de cobrança pós-pago, com a indicação de quais canais tentaram pagar.

Os 3 fluxos do protocolo via API

O ciclo de vida de uma passagem free flow tem três pontos de integração com a sua plataforma. Cada um é descrito abaixo.

1. Enviar passagem detectada

Sua infraestrutura captura a passagem (OCR/RFID + classificação por eixos) e publica para a Movvia:

POST /ec-api/v1/passagens
Authorization: Basic {credencial_ec}
x-ec-id: {ec_id}
Content-Type: application/json
Idempotency-Key: PASS-2026-0009871

{
  "referenciaExterna": "PASS-2026-0009871",
  "placa": "ABC1D23",
  "valor": 12.50,
  "tipo": "FREEFLOW",
  "praca": {
    "id": "imigrantes-km245",
    "nome": "Imigrantes KM 245",
    "sentido": "SUL"
  },
  "categoria": 1,
  "categoriaDescricao": "Veículo de passeio",
  "capturadoEm": "2026-04-23T14:32:10Z",
  "dataVencimento": "2026-05-23T23:59:59Z"
}

Resposta 201 Created:

{
  "passagemId": "01JVZ8F4WH9R2T7K5M3N8P6Q4X",
  "status": "PENDENTE",
  "criadaEm": "2026-04-23T14:32:11Z"
}

Notas:

  • valor em reais com 2 decimais (mesma convenção da API Parceiros).
  • referenciaExterna é seu identificador no ledger da praça — também serve como Idempotency-Key. Reenvio com mesma chave devolve o registro original.
  • passagemId é o ULID Movvia. Use nas consultas e correlacione com referenciaExterna no seu lado.
  • dataVencimento define até quando a passagem fica em pool. Após isso, expira e volta para seu fluxo pós-pago.

2. Receber pedido de reserva (lock)

Quando um canal autorizado quer pagar a passagem, ele primeiro reserva — exclusividade de 15 minutos para confirmar. Você recebe webhook informando que a passagem está locked:

POST {sua_url_webhook}
x-movvia-signature: <hmac-sha256-do-payload-bruto>
Content-Type: application/json

{
  "evento": "pe.passagem.reservada",
  "versao": "2",
  "id": "evt_8a3f1b2c9d4e",
  "timestamp": "2026-04-23T14:35:00Z",
  "ecId": "ec_imigrantes_concessionaria",
  "dados": {
    "passagemId": "01JVZ8F4WH9R2T7K5M3N8P6Q4X",
    "referenciaExterna": "PASS-2026-0009871",
    "placa": "ABC1D23",
    "reservaId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "valor": 12.50,
    "expiresAt": "2026-04-23T14:50:00Z",
    "canal": {
      "tipo": "PARCEIRO",
      "id": "carteira-banco-xyz",
      "nome": "Banco XYZ"
    }
  }
}

Notas:

  • O webhook é assinado com HMAC-SHA256 sobre o body bruto. Valide x-movvia-signature antes de processar (ver HMAC).
  • Enquanto a reserva estiver ATIVA, nenhum outro canal pode pagar a mesma passagem — elimina cobrança duplicada.
  • Se a reserva expirar sem confirmação, você recebe pe.passagem.expirada e a passagem volta ao pool.
  • Use reservaId como chave de correlação para o evento de pagamento (passo 3).

3. Receber pagamento confirmado

Quando o canal confirma o pagamento, você recebe o evento final com identificação completa do meio de quitação:

POST {sua_url_webhook}
x-movvia-signature: <hmac-sha256-do-payload-bruto>
Content-Type: application/json

{
  "evento": "pe.passagem.paga",
  "versao": "2",
  "id": "evt_3c4d5e6f7a8b",
  "timestamp": "2026-04-23T14:38:11Z",
  "ecId": "ec_imigrantes_concessionaria",
  "dados": {
    "passagemId": "01JVZ8F4WH9R2T7K5M3N8P6Q4X",
    "referenciaExterna": "PASS-2026-0009871",
    "reservaId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
    "valor": 12.50,
    "valorRepasseLiquido": 12.13,
    "comprovante": {
      "nsu": "000132547890",
      "txid": "MV20260423143810AB7F2C9D",
      "metodoPagamento": "PIX",
      "origemLiquidacao": "PARCEIRO",
      "canalId": "carteira-banco-xyz",
      "pagoEm": "2026-04-23T14:38:10Z"
    },
    "protocoloMovvia": "MV-2026-04-23-00042"
  }
}

Campos de dados.comprovante:

CampoDescrição
nsuNúmero Sequencial Único do pagamento (gerado pelo adquirente / arranjo de pagamento)
txidIdentificador da transação no canal (PIX EndToEnd ID, autorização do cartão, etc.)
metodoPagamentoPIX, CARTAO_CREDITO, CARTAO_DEBITO ou DINHEIRO
origemLiquidacaoOnde o motorista pagou: PORTAL (portal oficial Movvia), TOTEM (terminal físico em rodovia) ou PARCEIRO (app de carteira/banco/frota)
canalIdID do canal específico dentro da origem (ex.: carteira-banco-xyz, totem-imigrantes-04)
pagoEmTimestamp UTC do pagamento

reservaId permite correlacionar este evento com o pe.passagem.reservada recebido antes — útil para auditoria do tempo entre reserva e confirmação.

Convenção dos eventos pe.<modulo>.<acao> é a mesma da API Parceiros: campos de envelope (evento, versao, id, timestamp, ecId) + bloco dados específico. Ver Webhooks Parceiros para detalhes do mecanismo de retry, HMAC e idempotência — aplicáveis também aos eventos de EC.

Modelo de receita típico

Você recebe valorRepasseLiquido (valor da tarifa menos taxa Movvia) no ciclo de repasse contratado (D+0 ou D+1). A composição da taxa varia por metodoPagamento e origemLiquidacao — pagamento via TOTEM tem taxa diferente de via PARCEIRO. Para concessões reguladas (ANTT/ARTESP), a reconciliação com o ledger usa referenciaExterna + praca.id + categoria.

Regras operacionais

  • Atomicidade da reserva. Uma reserva pode incluir múltiplas passagens da mesma placa. Se qualquer transação ficar indisponível, a reserva inteira falha — você nunca recebe pe.passagem.reservada para passagens parcialmente locked.
  • Idempotência. Reenvio de POST /ec-api/v1/passagens com mesma referenciaExterna retorna o registro original. Webhooks com mesmo passagemId + evento são deduplicados pelo seu lado via reservaId (no caso de paga).
  • Estorno. Se você precisar reverter uma confirmação após receber pe.passagem.paga (ex.: contestação judicial, erro operacional), use o endpoint de reversão — o canal é notificado e responsável pelo estorno ao motorista.

Próximo passo

Previous page
Next page