{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-estabelecimentos-comerciais/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Pedágio free flow","description":"APIs públicas da Movvia para parceiros, estabelecimentos comerciais e clientes de dados veiculares.","meta":[{"name":"theme-color","content":"#7E3DEE"},{"name":"apple-mobile-web-app-title","content":"Movvia Docs"},{"name":"application-name","content":"Movvia Docs"}],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"pedágio-free-flow","__idx":0},"children":["Pedágio free flow"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"como-encaixa-no-seu-produto","__idx":1},"children":["Como encaixa no seu produto"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cada passagem capturada pelo sensor vira uma chamada ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /ec-api/v1/passagens"]}," com ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["tipo: \"FREEFLOW\""]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A passagem entra no pool da Movvia e fica disponível para qualquer canal autorizado reservar e pagar."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Você é notificado quando um canal ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["reserva"]}," a passagem (lock para pagamento) e quando o ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["pagamento é confirmado"]}," — com NSU, TX ID, método e origem."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"os-3-fluxos-do-protocolo-via-api","__idx":2},"children":["Os 3 fluxos do protocolo via API"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O ciclo de vida de uma passagem free flow tem três pontos de integração com a sua plataforma. Cada um é descrito abaixo."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-enviar-passagem-detectada","__idx":3},"children":["1. Enviar passagem detectada"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sua infraestrutura captura a passagem (OCR/RFID + classificação por eixos) e publica para a Movvia:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /ec-api/v1/passagens\nAuthorization: Basic {credencial_ec}\nx-ec-id: {ec_id}\nContent-Type: application/json\nIdempotency-Key: PASS-2026-0009871\n\n{\n  \"referenciaExterna\": \"PASS-2026-0009871\",\n  \"placa\": \"ABC1D23\",\n  \"valor\": 12.50,\n  \"tipo\": \"FREEFLOW\",\n  \"praca\": {\n    \"id\": \"imigrantes-km245\",\n    \"nome\": \"Imigrantes KM 245\",\n    \"sentido\": \"SUL\"\n  },\n  \"categoria\": 1,\n  \"categoriaDescricao\": \"Veículo de passeio\",\n  \"capturadoEm\": \"2026-04-23T14:32:10Z\",\n  \"dataVencimento\": \"2026-05-23T23:59:59Z\"\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Resposta ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]},":"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"passagemId\": \"01JVZ8F4WH9R2T7K5M3N8P6Q4X\",\n  \"status\": \"PENDENTE\",\n  \"criadaEm\": \"2026-04-23T14:32:11Z\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Notas:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["valor"]}," em ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["reais com 2 decimais"]}," (mesma convenção da API Parceiros)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenciaExterna"]}," é seu identificador no ledger da praça — também serve como ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]},". Reenvio com mesma chave devolve o registro original."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["passagemId"]}," é o ULID Movvia. Use nas consultas e correlacione com ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenciaExterna"]}," no seu lado."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dataVencimento"]}," define até quando a passagem fica em pool. Após isso, expira e volta para seu fluxo pós-pago."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"2-receber-pedido-de-reserva-lock","__idx":4},"children":["2. Receber pedido de reserva (lock)"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Quando um canal autorizado quer pagar a passagem, ele primeiro ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["reserva"]}," — exclusividade de 15 minutos para confirmar. Você recebe webhook informando que a passagem está locked:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST {sua_url_webhook}\nx-movvia-signature: <hmac-sha256-do-payload-bruto>\nContent-Type: application/json\n\n{\n  \"evento\": \"pe.passagem.reservada\",\n  \"versao\": \"2\",\n  \"id\": \"evt_8a3f1b2c9d4e\",\n  \"timestamp\": \"2026-04-23T14:35:00Z\",\n  \"ecId\": \"ec_imigrantes_concessionaria\",\n  \"dados\": {\n    \"passagemId\": \"01JVZ8F4WH9R2T7K5M3N8P6Q4X\",\n    \"referenciaExterna\": \"PASS-2026-0009871\",\n    \"placa\": \"ABC1D23\",\n    \"reservaId\": \"f47ac10b-58cc-4372-a567-0e02b2c3d479\",\n    \"valor\": 12.50,\n    \"expiresAt\": \"2026-04-23T14:50:00Z\",\n    \"canal\": {\n      \"tipo\": \"PARCEIRO\",\n      \"id\": \"carteira-banco-xyz\",\n      \"nome\": \"Banco XYZ\"\n    }\n  }\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Notas:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["O webhook é assinado com HMAC-SHA256 sobre o body bruto. Valide ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-movvia-signature"]}," antes de processar (ver ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/compartilhado/seguranca/hmac"},"children":["HMAC"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Enquanto a reserva estiver ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ATIVA"]},", ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["nenhum outro canal pode pagar"]}," a mesma passagem — elimina cobrança duplicada."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Se a reserva expirar sem confirmação, você recebe ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pe.passagem.expirada"]}," e a passagem volta ao pool."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reservaId"]}," como chave de correlação para o evento de pagamento (passo 3)."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-receber-pagamento-confirmado","__idx":5},"children":["3. Receber pagamento confirmado"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Quando o canal confirma o pagamento, você recebe o evento final com identificação completa do meio de quitação:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST {sua_url_webhook}\nx-movvia-signature: <hmac-sha256-do-payload-bruto>\nContent-Type: application/json\n\n{\n  \"evento\": \"pe.passagem.paga\",\n  \"versao\": \"2\",\n  \"id\": \"evt_3c4d5e6f7a8b\",\n  \"timestamp\": \"2026-04-23T14:38:11Z\",\n  \"ecId\": \"ec_imigrantes_concessionaria\",\n  \"dados\": {\n    \"passagemId\": \"01JVZ8F4WH9R2T7K5M3N8P6Q4X\",\n    \"referenciaExterna\": \"PASS-2026-0009871\",\n    \"reservaId\": \"f47ac10b-58cc-4372-a567-0e02b2c3d479\",\n    \"valor\": 12.50,\n    \"valorRepasseLiquido\": 12.13,\n    \"comprovante\": {\n      \"nsu\": \"000132547890\",\n      \"txid\": \"MV20260423143810AB7F2C9D\",\n      \"metodoPagamento\": \"PIX\",\n      \"origemLiquidacao\": \"PARCEIRO\",\n      \"canalId\": \"carteira-banco-xyz\",\n      \"pagoEm\": \"2026-04-23T14:38:10Z\"\n    },\n    \"protocoloMovvia\": \"MV-2026-04-23-00042\"\n  }\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Campos de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dados.comprovante"]},":"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Campo"},"children":["Campo"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Descrição"},"children":["Descrição"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nsu"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Número Sequencial Único do pagamento (gerado pelo adquirente / arranjo de pagamento)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["txid"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Identificador da transação no canal (PIX EndToEnd ID, autorização do cartão, etc.)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metodoPagamento"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PIX"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CARTAO_CREDITO"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["CARTAO_DEBITO"]}," ou ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DINHEIRO"]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["origemLiquidacao"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Onde o motorista pagou: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PORTAL"]}," (portal oficial Movvia), ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TOTEM"]}," (terminal físico em rodovia) ou ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PARCEIRO"]}," (app de carteira/banco/frota)"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["canalId"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["ID do canal específico dentro da origem (ex.: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["carteira-banco-xyz"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["totem-imigrantes-04"]},")"]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pagoEm"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Timestamp UTC do pagamento"]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reservaId"]}," permite correlacionar este evento com o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pe.passagem.reservada"]}," recebido antes — útil para auditoria do tempo entre reserva e confirmação."]},{"$$mdtype":"Tag","name":"blockquote","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Convenção dos eventos ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pe.<modulo>.<acao>"]}," é a mesma da API Parceiros: campos de envelope (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["evento"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["versao"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["timestamp"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ecId"]},") + bloco ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dados"]}," específico. Ver ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/parceiros/guides/webhooks"},"children":["Webhooks Parceiros"]}," para detalhes do mecanismo de retry, HMAC e idempotência — aplicáveis também aos eventos de EC."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"modelo-de-receita-típico","__idx":6},"children":["Modelo de receita típico"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Você recebe ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["valorRepasseLiquido"]}," (valor da tarifa menos taxa Movvia) no ciclo de repasse contratado (D+0 ou D+1). A composição da taxa varia por ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metodoPagamento"]}," e ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["origemLiquidacao"]}," — pagamento via TOTEM tem taxa diferente de via PARCEIRO. Para concessões reguladas (ANTT/ARTESP), a reconciliação com o ledger usa ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenciaExterna"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["praca.id"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["categoria"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"regras-operacionais","__idx":7},"children":["Regras operacionais"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pe.passagem.reservada"]}," para passagens parcialmente locked."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Idempotência."]}," Reenvio de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /ec-api/v1/passagens"]}," com mesma ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["referenciaExterna"]}," retorna o registro original. Webhooks com mesmo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["passagemId"]}," + ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["evento"]}," são deduplicados pelo seu lado via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["reservaId"]}," (no caso de ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["paga"]},")."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Estorno."]}," Se você precisar reverter uma confirmação após receber ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"próximo-passo","__idx":8},"children":["Próximo passo"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/estabelecimentos-comerciais/tutorials/publicar-primeira-cobranca"},"children":["Publicar primeira cobrança"]}," — tutorial passo-a-passo do fluxo completo em sandbox."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/compartilhado/seguranca/hmac"},"children":["Validar webhooks com HMAC"]}," — assinatura obrigatória de eventos ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pe.passagem.*"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/compartilhado/seguranca/idempotencia"},"children":["Idempotência"]}," — como tratar reenvios de webhooks por timeout."]}]}]},"headings":[{"value":"Pedágio free flow","id":"pedágio-free-flow","depth":1},{"value":"Como encaixa no seu produto","id":"como-encaixa-no-seu-produto","depth":2},{"value":"Os 3 fluxos do protocolo via API","id":"os-3-fluxos-do-protocolo-via-api","depth":2},{"value":"1. Enviar passagem detectada","id":"1-enviar-passagem-detectada","depth":3},{"value":"2. Receber pedido de reserva (lock)","id":"2-receber-pedido-de-reserva-lock","depth":3},{"value":"3. Receber pagamento confirmado","id":"3-receber-pagamento-confirmado","depth":3},{"value":"Modelo de receita típico","id":"modelo-de-receita-típico","depth":2},{"value":"Regras operacionais","id":"regras-operacionais","depth":2},{"value":"Próximo passo","id":"próximo-passo","depth":2}],"frontmatter":{"title":"Pedágio free flow — Estabelecimentos Comerciais Movvia","description":"Como concessionárias de pedágio free flow publicam passagens, recebem reservas de pagamento e confirmações via API Movvia.","seo":{"title":"Pedágio free flow"}},"lastModified":"2026-04-25T18:15:22.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/estabelecimentos-comerciais/casos-de-uso/pedagio-freeflow","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}