{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-estabelecimentos-comerciais/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Pedágio de barreira","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-de-barreira","__idx":0},"children":["Pedágio de barreira"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["nsu"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["txid"]}," e ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["origemLiquidacao"]}," para liberar a cancela."]},{"$$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":["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)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reserva atômica: enquanto um canal estiver tentando pagar, nenhum outro pode interferir — sem cobrança duplicada."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Confirmação de pagamento traz ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metodoPagamento"]}," e ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["origemLiquidacao"]}," em tempo real, suficiente para automatizar a liberação da cancela."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Cobranças não pagas no TTL voltam ao seu fluxo pós-pago tradicional, com histórico das tentativas."]}]},{"$$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":["Cada passagem na barreira passa pelos mesmos 3 pontos de integração — só o tempo entre eles muda (segundos em vez de dias)."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"1-enviar-cobrança-no-momento-da-passagem","__idx":3},"children":["1. Enviar cobrança no momento da passagem"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Sua estação de identificação (OCR no pórtico de entrada, leitura de transponder ou guichê) publica a cobrança imediatamente:"]},{"$$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: BARREIRA-2026-00441\n\n{\n  \"referenciaExterna\": \"BARREIRA-2026-00441\",\n  \"placa\": \"XYZ9W87\",\n  \"valor\": 8.20,\n  \"tipo\": \"BARREIRA\",\n  \"praca\": {\n    \"id\": \"dutra-003\",\n    \"nome\": \"Praça 3 — Via Dutra KM 132\",\n    \"sentido\": \"SP-RJ\"\n  },\n  \"categoria\": 2,\n  \"categoriaDescricao\": \"Veículo comercial 2 eixos\",\n  \"capturadoEm\": \"2026-04-23T11:17:04Z\",\n  \"ttl\": 90,\n  \"cancelaId\": \"cancela-3-faixa-2\"\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\": \"01JVZA1G8K7M2N5P3Q6R9T8X4B\",\n  \"status\": \"PENDENTE\",\n  \"expiresAt\": \"2026-04-23T11:18:34Z\",\n  \"criadaEm\": \"2026-04-23T11:17:04Z\"\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":["ttl"]}," em segundos. Após esse prazo a cobrança expira automaticamente; configure conforme seu modo de operação (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["90"]}," para liberação síncrona; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["172800"]}," = 48h para pós-pago)."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelaId"]}," opcional: se enviado, é incluído nos webhooks subsequentes para você direcionar o sinal de liberação para a cancela correta."]},{"$$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":"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":["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:"]},{"$$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_2b3c4d5e6f7a\",\n  \"timestamp\": \"2026-04-23T11:17:08Z\",\n  \"ecId\": \"ec_dutra_concessionaria\",\n  \"dados\": {\n    \"passagemId\": \"01JVZA1G8K7M2N5P3Q6R9T8X4B\",\n    \"referenciaExterna\": \"BARREIRA-2026-00441\",\n    \"placa\": \"XYZ9W87\",\n    \"reservaId\": \"a78bc92d-1f3e-4c45-9012-bd56fa8e7c91\",\n    \"cancelaId\": \"cancela-3-faixa-2\",\n    \"valor\": 8.20,\n    \"expiresAt\": \"2026-04-23T11:18:34Z\",\n    \"canal\": {\n      \"tipo\": \"TOTEM\",\n      \"id\": \"totem-dutra-003-frente\",\n      \"nome\": \"Totem Dutra Praça 3\"\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":["Para pedágio de barreira, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiresAt"]}," da reserva = ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["expiresAt"]}," da cobrança (ambos terminam no fim do TTL). Não há renovação."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Se o canal não confirmar dentro do TTL, você recebe ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pe.passagem.expirada"]}," — fluxo manual no guichê."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["cancelaId"]}," (se foi enviado no passo 1) está incluído no payload para você correlacionar com a cancela física."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"3-receber-pagamento-confirmado-e-liberar-a-cancela","__idx":5},"children":["3. Receber pagamento confirmado e liberar a cancela"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Confirmação chega tipicamente em segundos. Esse é o sinal para liberar a cancela:"]},{"$$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_4f5a6b7c8d9e\",\n  \"timestamp\": \"2026-04-23T11:17:13Z\",\n  \"ecId\": \"ec_dutra_concessionaria\",\n  \"dados\": {\n    \"passagemId\": \"01JVZA1G8K7M2N5P3Q6R9T8X4B\",\n    \"referenciaExterna\": \"BARREIRA-2026-00441\",\n    \"reservaId\": \"a78bc92d-1f3e-4c45-9012-bd56fa8e7c91\",\n    \"cancelaId\": \"cancela-3-faixa-2\",\n    \"valor\": 8.20,\n    \"valorRepasseLiquido\": 7.96,\n    \"comprovante\": {\n      \"nsu\": \"000089432101\",\n      \"txid\": \"TOT20260423111712CD9F8B2A\",\n      \"metodoPagamento\": \"PIX\",\n      \"origemLiquidacao\": \"TOTEM\",\n      \"canalId\": \"totem-dutra-003-frente\",\n      \"pagoEm\": \"2026-04-23T11:17:12Z\"\n    },\n    \"protocoloMovvia\": \"MV-2026-04-23-00118\"\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 na praça) 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"]}]},{"$$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":["Regra operacional para liberação síncrona da cancela:"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Receber ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["pe.passagem.paga"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Validar ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-movvia-signature"]}," (HMAC) antes de processar — descarte payloads não assinados."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Verificar que ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["dados.cancelaId"]}," corresponde à faixa que está aguardando."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Acionar abertura da cancela. Tempo total típico Movvia → seu sistema → cancela: < 1 segundo após 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: envelope ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{evento, versao, id, timestamp, 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 retry, HMAC e idempotência."]}]},{"$$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":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["valorRepasseLiquido"]}," é repassado em D+0 — relevante para barreira porque o caixa operacional da praça precisa fechar todo dia. A taxa Movvia varia conforme ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["metodoPagamento"]}," (PIX no totem é a mais barata; cartão de crédito é a mais cara) e ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["origemLiquidacao"]}," (TOTEM costuma ser plano dedicado)."]},{"$$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":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Estorno."]}," Se a cancela falhar após ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]}]},{"$$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 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 ",{"$$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 no fluxo de cancela."]}]}]},"headings":[{"value":"Pedágio de barreira","id":"pedágio-de-barreira","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 cobrança no momento da passagem","id":"1-enviar-cobrança-no-momento-da-passagem","depth":3},{"value":"2. Receber pedido de reserva (lock)","id":"2-receber-pedido-de-reserva-lock","depth":3},{"value":"3. Receber pagamento confirmado e liberar a cancela","id":"3-receber-pagamento-confirmado-e-liberar-a-cancela","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 de barreira — Estabelecimentos Comerciais Movvia","description":"Como concessionárias de pedágio de barreira publicam cobranças no ato, recebem reservas e confirmações de pagamento via API Movvia.","seo":{"title":"Pedágio de barreira"}},"lastModified":"2026-04-25T18:15:22.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/estabelecimentos-comerciais/casos-de-uso/pedagio-barreira","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}