Skip to content
/
Pedágio de barreira
Last updated

Pedágio de barreira

Quem é você. Você opera praças de pedágio com cancela física — a cobrança ocorre no ato da passagem, com identificação do veículo por OCR, RFID ou apresentação do transponder. Cancela só libera com pagamento autorizado.

Problema. Motoristas sem dinheiro em espécie ou com transponder inativo causam fila e atrito operacional. Integrar cada adquirente individualmente é caro — e pagamento manual no guichê é lento demais para o fluxo da praça.

Solução Movvia. Você publica a cobrança no momento da passagem com TTL curto. A rede de canais (totem na própria praça, app de carteira do motorista, portal oficial) reserva e confirma em segundos. Você recebe o sinal de pagamento confirmado com nsu, txid e origemLiquidacao para liberar a cancela.

Como encaixa no seu produto

  • Cobrança publicada no instante da identificação do veículo, com TTL configurado no onboarding (típico: 90s para fluxo de cancela; até 48h se tolerar pagamento pós-passagem).
  • Reserva atômica: enquanto um canal estiver tentando pagar, nenhum outro pode interferir — sem cobrança duplicada.
  • Confirmação de pagamento traz metodoPagamento e origemLiquidacao em tempo real, suficiente para automatizar a liberação da cancela.
  • Cobranças não pagas no TTL voltam ao seu fluxo pós-pago tradicional, com histórico das tentativas.

Os 3 fluxos do protocolo via API

Cada passagem na barreira passa pelos mesmos 3 pontos de integração — só o tempo entre eles muda (segundos em vez de dias).

1. Enviar cobrança no momento da passagem

Sua estação de identificação (OCR no pórtico de entrada, leitura de transponder ou guichê) publica a cobrança imediatamente:

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

{
  "referenciaExterna": "BARREIRA-2026-00441",
  "placa": "XYZ9W87",
  "valor": 8.20,
  "tipo": "BARREIRA",
  "praca": {
    "id": "dutra-003",
    "nome": "Praça 3 — Via Dutra KM 132",
    "sentido": "SP-RJ"
  },
  "categoria": 2,
  "categoriaDescricao": "Veículo comercial 2 eixos",
  "capturadoEm": "2026-04-23T11:17:04Z",
  "ttl": 90,
  "cancelaId": "cancela-3-faixa-2"
}

Resposta 201 Created:

{
  "passagemId": "01JVZA1G8K7M2N5P3Q6R9T8X4B",
  "status": "PENDENTE",
  "expiresAt": "2026-04-23T11:18:34Z",
  "criadaEm": "2026-04-23T11:17:04Z"
}

Notas:

  • ttl em segundos. Após esse prazo a cobrança expira automaticamente; configure conforme seu modo de operação (90 para liberação síncrona; 172800 = 48h para pós-pago).
  • cancelaId opcional: se enviado, é incluído nos webhooks subsequentes para você direcionar o sinal de liberação para a cancela correta.
  • valor em reais com 2 decimais (mesma convenção da API Parceiros).

2. Receber pedido de reserva (lock)

Em segundos, um canal autorizado tenta pagar. Você recebe webhook informando o lock — útil para mostrar "processando" no painel da praça e travar tentativa concorrente:

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

{
  "evento": "pe.passagem.reservada",
  "versao": "2",
  "id": "evt_2b3c4d5e6f7a",
  "timestamp": "2026-04-23T11:17:08Z",
  "ecId": "ec_dutra_concessionaria",
  "dados": {
    "passagemId": "01JVZA1G8K7M2N5P3Q6R9T8X4B",
    "referenciaExterna": "BARREIRA-2026-00441",
    "placa": "XYZ9W87",
    "reservaId": "a78bc92d-1f3e-4c45-9012-bd56fa8e7c91",
    "cancelaId": "cancela-3-faixa-2",
    "valor": 8.20,
    "expiresAt": "2026-04-23T11:18:34Z",
    "canal": {
      "tipo": "TOTEM",
      "id": "totem-dutra-003-frente",
      "nome": "Totem Dutra Praça 3"
    }
  }
}

Notas:

  • Para pedágio de barreira, expiresAt da reserva = expiresAt da cobrança (ambos terminam no fim do TTL). Não há renovação.
  • Se o canal não confirmar dentro do TTL, você recebe pe.passagem.expirada — fluxo manual no guichê.
  • cancelaId (se foi enviado no passo 1) está incluído no payload para você correlacionar com a cancela física.

3. Receber pagamento confirmado e liberar a cancela

Confirmação chega tipicamente em segundos. Esse é o sinal para liberar a cancela:

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

{
  "evento": "pe.passagem.paga",
  "versao": "2",
  "id": "evt_4f5a6b7c8d9e",
  "timestamp": "2026-04-23T11:17:13Z",
  "ecId": "ec_dutra_concessionaria",
  "dados": {
    "passagemId": "01JVZA1G8K7M2N5P3Q6R9T8X4B",
    "referenciaExterna": "BARREIRA-2026-00441",
    "reservaId": "a78bc92d-1f3e-4c45-9012-bd56fa8e7c91",
    "cancelaId": "cancela-3-faixa-2",
    "valor": 8.20,
    "valorRepasseLiquido": 7.96,
    "comprovante": {
      "nsu": "000089432101",
      "txid": "TOT20260423111712CD9F8B2A",
      "metodoPagamento": "PIX",
      "origemLiquidacao": "TOTEM",
      "canalId": "totem-dutra-003-frente",
      "pagoEm": "2026-04-23T11:17:12Z"
    },
    "protocoloMovvia": "MV-2026-04-23-00118"
  }
}

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 na praça) ou PARCEIRO (app de carteira/banco/frota)
canalIdID do canal específico dentro da origem
pagoEmTimestamp UTC do pagamento

Regra operacional para liberação síncrona da cancela:

  1. Receber pe.passagem.paga.
  2. Validar x-movvia-signature (HMAC) antes de processar — descarte payloads não assinados.
  3. Verificar que dados.cancelaId corresponde à faixa que está aguardando.
  4. Acionar abertura da cancela. Tempo total típico Movvia → seu sistema → cancela: < 1 segundo após confirmação.

Convenção dos eventos pe.<modulo>.<acao> é a mesma da API Parceiros: envelope {evento, versao, id, timestamp, ecId} + bloco dados específico. Ver Webhooks Parceiros para retry, HMAC e idempotência.

Modelo de receita típico

valorRepasseLiquido é repassado em D+0 — relevante para barreira porque o caixa operacional da praça precisa fechar todo dia. A taxa Movvia varia conforme metodoPagamento (PIX no totem é a mais barata; cartão de crédito é a mais cara) e origemLiquidacao (TOTEM costuma ser plano dedicado).

Regras operacionais

  • TTL curto exige resposta rápida do parceiro/totem. Canais com latência média acima do TTL são despriorizados pela Movvia automaticamente — operação saudável da praça é prioridade.
  • Atomicidade. Cada cobrança de barreira gera no máximo 1 reserva ativa. Não há agrupamento por placa em barreira — diferente de free flow.
  • Estorno. Se a cancela falhar após pe.passagem.paga (ex.: defeito mecânico, motorista forçou), abra um ticket via endpoint de reversão; a Movvia notifica o canal para estorno ao motorista. Esse fluxo é exceção, não rotina.

Próximo passo

Previous page
Next page