# Leve pedágio free flow para dentro do seu produto

Uma API, múltiplas concessionárias, pronta para produção. Cadastre placas, receba eventos em tempo real e liquide pelo seu próprio fluxo de cobrança.

[Começar pelo quickstart](/parceiros/tutorials/quickstart)

## Quem é o Parceiro

Você é um Parceiro se **publica cobrança ao usuário final** — o cliente usa seu produto para pagar o pedágio, e a Movvia liquida as passagens capturadas pela rede de concessionárias.

- Você emite a cobrança ao cliente no seu próprio fluxo (pontos, saldo, PIX, cartão).
- A Movvia processa as passagens da rede free flow e entrega eventos assinados no seu endpoint.
- Você confirma o pagamento via API com chave de idempotência.
- Você não precisa de contratos individuais com cada concessionária.
- Se você **emite cobrança como concessionária** (pedágio, estacionamento, prefeitura), o papel correto é Estabelecimento Comercial — veja [estabelecimentos-comerciais](/estabelecimentos-comerciais).


## Como funciona em 3 passos

**Passo 1 — Cadastre as placas**

Envie as placas que você quer monitorar. Toda passagem dessas placas vira evento no seu sistema.


```bash
curl -X POST https://hml.api.pedagioeletronico.com.br/gestao-webhooks-api/v1/placas \
  -H "Authorization: Basic $MV_KEY" \
  -H "x-parceiro-id: $MV_PARCEIRO_ID" \
  -H "Content-Type: application/json" \
  -d '{"placa":"ABC1D23","metadata":{"cliente_id":"ext_123"}}'
```

**Passo 2 — Receba os eventos**

Webhooks assinados com HMAC-SHA256 chegam em tempo real para cada passagem.


```json
{
  "evento": "pe.transacao.recebida",
  "placa": "ABC1D23",
  "valor": 12.50,
  "praca": "KM 245 — Imigrantes"
}
```

**Passo 3 — Liquide pelo seu fluxo**

Cobre do seu cliente como quiser. Confirme o pagamento via API com chave de idempotência.


```bash
curl -X POST https://hml.api.pedagioeletronico.com.br/gestao-webhooks-api/v1/pedidos \
  -H "Authorization: Basic $MV_KEY" \
  -H "x-parceiro-id: $MV_PARCEIRO_ID" \
  -H "Content-Type: application/json" \
  -d '{"transacoes":["t_9f2c7e1a"],"idempotencyKey":"ord_abc123"}'
```

## Casos de uso

Todos os casos usam o mesmo conjunto de endpoints — o que muda é o encaixe no seu produto.

| Vertical | Como encaixa | Modelo de receita típico |
|  --- | --- | --- |
| [Banco / carteira digital](/parceiros/casos-de-uso/banco-carteira) | Passagem vira linha de extrato; cobrança no saldo ou cartão. | Interchange + margem Movvia. |
| [Programa de fidelidade](/parceiros/casos-de-uso/programa-fidelidade) | Resgate de pontos/milhas para quitar pedágio. | Queima de pontos à cotação interna + breakage. |
| [Posto de combustível](/parceiros/casos-de-uso/posto-combustivel) | Pedágio vira moeda do programa de fidelidade; cashback com litros. | Parceiro absorve como benefício; Movvia cobra over volume. |
| [Varejo multi-serviço](/parceiros/casos-de-uso/varejo-multi-servico) | Cliente quita pedágio junto com outros serviços no mesmo app. | Conveniência por transação + spread sobre Movvia. |
| [Seguradora](/parceiros/casos-de-uso/seguradora) | Consulta histórico de passagens antes de emitir/renovar apólice. | Pay-per-query ou pacote mensal por base. |
| [App de mobilidade](/parceiros/casos-de-uso/app-mobilidade) | Motorista não paga do próprio bolso; liquidação direta. | App absorve como benefício ao motorista. |
| [TMS / ERP de frota](/parceiros/casos-de-uso/tms-erp-frota) | Módulo white-label de pedágio dentro da viagem. | Revenue share TMS ↔ Movvia. |
| [Carro conectado](/parceiros/casos-de-uso/carro-conectado) | Veículo detecta passagem e oferece pagamento in-car. | Assinatura do serviço conectado + parceria Movvia. |
| [E-commerce automotivo](/parceiros/casos-de-uso/e-commerce-automotivo) | Histórico de passagens como prova de uso em anúncios. | Pay-per-query ou selo verificado. |
| [Assistente IA veicular](/parceiros/casos-de-uso/assistente-ia-veicular) | Contexto de passagem em linguagem natural + pagamento via tool-use. | Revenue share customizado. |


[Ver todos os casos de uso](/parceiros/casos-de-uso)

## Movvia vs alternativas

|  | Integração direta com concessionária | OSA tradicional (TAG) | Movvia |
|  --- | --- | --- | --- |
| **Cobertura free flow** | 1 de cada vez | Limitada | Rede consolidada via endpoint único |
| **Dispositivo físico** | Não se aplica | TAG obrigatório | Sem TAG — OCR nativo + RFID híbrido |
| **Tempo para integrar** | 6–12 meses | 3–6 meses | Dias |
| **Modelo contratual** | Contrato a contrato | Cliente final obrigatório | Parceiro-liquidante, white-label |
| **Webhooks assinados** | Não | Parcial | HMAC-SHA256, catálogo versionado |
| **Sandbox** | Raro | Limitado | Credenciais sob solicitação |


## Três pilares

**Uma API, múltiplas concessionárias.** Conecte uma vez, receba passagens da rede free flow coberta pela Movvia. Sem contratos individuais.

**Segurança e conformidade por padrão.** HMAC-SHA256, rate limiting, idempotência por chave, audit log. Pronto para LGPD com minimização e retenção configurável.

**Roadmap aberto e previsível.** Catálogo de eventos versionado, sunsets anunciados com meses de antecedência, changelog público. Você nunca acorda com uma breaking change.

## Developer Experience

- **Documentação viva** — OpenAPI 3.1 sempre atualizado, exemplos em múltiplas linguagens, changelog público.
- **Sandbox** — credenciais de homologação sob solicitação. Dados sintéticos.
- **Simulador CLI** — script interativo em Node.js, Python, Go, Java ou Bash que cobre todos os endpoints da v2. Veja [Simulador CLI](/parceiros/tutorials/simulador-cli).
- **Postman Collection** — atualizada em CI. (preview)
- **SDKs Node/Python/Go** — em desenvolvimento. Integração suportada hoje via HTTP direto.
- **Suporte técnico** — Slack Connect para parceiros Partner/Enterprise.


## Preços

Você paga quando transaciona, não quando integra.

| Tier | Para quem | Destaque |
|  --- | --- | --- |
| **Explorer** — gratuito | Avaliar, prototipar, sandbox | Até 1.000 placas em produção supervisionada |
| **Partner** — taxa over volume | Produção recorrente | 2,5% sobre GMV liquidado + rebate sobre float (negociável) |
| **Enterprise** — sob consulta | Volume alto, compliance, isolamento | SLA 99,95% com penalidade contratual |


Qual nível é o seu?
Comece pelo Explorer. Para volumes ou exigências fora do padrão, escreva para [comercial@movvia.com.br](mailto:comercial@movvia.com.br).

## Perguntas frequentes

details
summary
Em quanto tempo consigo uma credencial de sandbox?
Normalmente em minutos úteis após a solicitação. Envie email para [comercial@movvia.com.br](mailto:comercial@movvia.com.br) com nome, empresa e uma linha sobre o caso de uso.

details
summary
Preciso virar uma instituição de pagamento?
Não. A Movvia atua como infraestrutura. Você liquida pelo método que já usa (pontos, saldo, cartão, PIX).

details
summary
Qual o modelo de webhook?
POST assinado com HMAC-SHA256, retry exponencial (até 24h), catálogo de eventos versionado. Detalhes em [Webhooks](/parceiros/guides/webhooks).

details
summary
Como funcionam os limites de rate?
1.000 req/min e 10.000 req/hora por credencial em produção. Limites customizados disponíveis para Enterprise. Detalhes em [Rate limits](/parceiros/guides/rate-limits).

details
summary
Vocês cobrem todas as concessionárias free flow do Brasil?
Cobrimos a rede inicial homologada e estamos em expansão. O status de cobertura é informado a cada parceiro no onboarding.

details
summary
Tem TAG envolvida?
Não para free flow. OCR + RFID híbrido onde suportado. Sem dispositivo obrigatório para o cliente final.

details
summary
Como funcionam estornos e disputas?
Princípio "quem errou, paga." Fluxo automatizado por transaction_id. Documentado no manual de disputas entregue no onboarding.

details
summary
E LGPD?
Minimização de dados, retenção configurável, RoPA compartilhado em contrato. DPO disponível via [comercial@movvia.com.br](mailto:comercial@movvia.com.br).

## Próximos passos

1. Siga o [Quickstart](/parceiros/tutorials/quickstart) — sandbox, primeira placa e primeiro webhook em 20 minutos.
2. Leia os [Guias](/parceiros/guides) para entender autenticação, modos de operação e webhooks.
3. Veja os [Casos de uso](/parceiros/casos-de-uso) para o encaixe no seu produto.
4. Consulte a [Referência da API](/apis/parceiros/openapi) para todos os endpoints e schemas.