# Disputas e estornos

Princípio central: **quem errou, paga.** A Movvia não distribui o custo do erro igualmente — identifica a causa e atribui a responsabilidade ao responsável.

## Tabela de responsabilidades

| Causa do erro | Quem absorve | Mecanismo |
|  --- | --- | --- |
| Erro de OCR / categoria incorreta | EC (concessionária) | EC solicita estorno via API |
| Erro de sistema da Movvia | Movvia | Estorno automático por `referenciaExterna` |
| Fraude do cidadão | Liquidante | Liquidante absorve (é cliente dele, risco dele) |
| Placa clonada | EC investiga, Movvia executa | EC confirma e solicita estorno |
| Cobrança duplicada (sua) | EC | EC cancela via `DELETE /ec/cobrancas/{id}` antes da liquidação |
| Cobrança duplicada (Movvia) | Movvia | Estorno automático, você é notificado |


## Fluxo de estorno iniciado pelo EC

### 1. Identifique a cobrança

Você precisa do `passagemId` (retornado na criação) ou do `referenciaExterna` (seu ID).


```http
GET /ec-api/v1/passagens?referenciaExterna=PASS-2026-0009871
Authorization: Basic {credencial_ec}
x-ec-id: {ec_id}
```

### 2. Solicite o estorno


```http
POST /ec-api/v1/passagens/{passagemId}/estornar
Authorization: Basic {credencial_ec}
x-ec-id: {ec_id}
Content-Type: application/json

{
  "motivo": "ERRO_OCR",
  "descricao": "Placa lida incorretamente pelo sensor da praça 9f2c.",
  "valorEstorno": 12.50
}
```

Motivos aceitos: `ERRO_OCR`, `CATEGORIA_INCORRETA`, `PLACA_CLONADA`, `COBRANCA_INDEVIDA`, `OUTROS`.

### 3. Aguarde o webhook de confirmação


```json
{
  "evento": "pe.passagem.estornada",
  "passagemId": "cob_9f2c7e1a",
  "referenciaExterna": "PASS-2026-0009871",
  "valorEstornado": 12.50,
  "debitadoDa": "subconta_ec",
  "estornadoEm": "2026-04-24T09:00:00Z"
}
```

O valor é debitado da sua subconta e devolvido ao liquidante, que devolve ao cidadão.

## SLAs de resolução

| Tipo | SLA de análise | SLA de execução |
|  --- | --- | --- |
| Erro de OCR (EC solicita) | Imediato (automático) | Até 2h úteis |
| Fraude / placa clonada | 3 dias úteis | Após confirmação da investigação |
| Erro Movvia | Imediato (automático) | Até 1h |


SLAs com penalidade para erros da Movvia são definidos no contrato enterprise.

## Estorno parcial

Se apenas parte do valor foi cobrado indevidamente (ex.: categoria 1 cobrada, deveria ser categoria 2), o campo `valorEstorno` aceita valor menor que o `valorLiquidado` original.

Cobrança já expirada
Cobranças com status `EXPIRADA` não podem ser estornadas — nunca houve liquidação. Se você gerou uma cobrança indevida que expirou, nenhuma ação é necessária.

## Disputas iniciadas pelo liquidante

O liquidante pode abrir disputa sobre uma cobrança que ele já liquidou (ex.: cidadão alega que não passou). Nesse caso:

1. Você recebe `ec.disputa.aberta` no webhook.
2. Você tem o prazo definido no contrato para apresentar evidência (foto, log de sensor).
3. A Movvia avalia e decide.
4. Se a disputa for procedente, o estorno é executado com débito na sua subconta.



```json
{
  "evento": "ec.disputa.aberta",
  "passagemId": "cob_9f2c7e1a",
  "referenciaExterna": "PASS-2026-0009871",
  "abertaPor": "liq_banco_xyz",
  "motivo": "CIDADAO_CONTESTA",
  "prazoResposta": "2026-04-27T23:59:59Z"
}
```

## Próximo passo

- [Reconciliação](/estabelecimentos-comerciais/guides/reconciliacao) — como estornos aparecem no extrato e afetam a conciliação.