# 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: ```http 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`:** ```json { "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: ```http POST {sua_url_webhook} x-movvia-signature: 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](/compartilhado/seguranca/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: ```http POST {sua_url_webhook} x-movvia-signature: 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`: | Campo | Descrição | | --- | --- | | `nsu` | Número Sequencial Único do pagamento (gerado pelo adquirente / arranjo de pagamento) | | `txid` | Identificador da transação no canal (PIX EndToEnd ID, autorização do cartão, etc.) | | `metodoPagamento` | `PIX`, `CARTAO_CREDITO`, `CARTAO_DEBITO` ou `DINHEIRO` | | `origemLiquidacao` | Onde o motorista pagou: `PORTAL` (portal oficial Movvia), `TOTEM` (terminal físico em rodovia) ou `PARCEIRO` (app de carteira/banco/frota) | | `canalId` | ID do canal específico dentro da origem (ex.: `carteira-banco-xyz`, `totem-imigrantes-04`) | | `pagoEm` | Timestamp 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..` é a mesma da API Parceiros: campos de envelope (`evento`, `versao`, `id`, `timestamp`, `ecId`) + bloco `dados` específico. Ver [Webhooks Parceiros](/parceiros/guides/webhooks) 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 - [Publicar primeira cobrança](/estabelecimentos-comerciais/tutorials/publicar-primeira-cobranca) — tutorial passo-a-passo do fluxo completo em sandbox. - [Validar webhooks com HMAC](/compartilhado/seguranca/hmac) — assinatura obrigatória de eventos `pe.passagem.*`. - [Idempotência](/compartilhado/seguranca/idempotencia) — como tratar reenvios de webhooks por timeout.