# Reconciliação

A reconciliação garante que o que você publicou, o que foi liquidado, o que foi estornado e o que você recebeu formam um quadro consistente entre seu sistema e a Movvia.

## Campo-âncora: referenciaExterna

Toda cobrança publicada carrega `referenciaExterna` — campo definido por você, imutável após a criação. É o elo entre a Movvia e o seu sistema de origem.

Use `referenciaExterna` para:

- Buscar o status atual de uma cobrança específica.
- Cruzar o extrato Movvia com o ledger interno.
- Identificar cobranças liquidadas que ainda não geraram repasse (dentro do ciclo).


## Fluxo de reconciliação diária

### 1. Puxe o extrato do dia


```http
GET /ec-api/v1/extrato?desde=2026-04-23&ate=2026-04-23
Authorization: Basic {credencial_ec}
x-ec-id: {ec_id}
```

Cada linha do extrato contém:


```json
{
  "tipo": "CREDITO",
  "referenciaExterna": "PASS-2026-0009871",
  "passagemId": "cob_9f2c7e1a",
  "valor": 12.50,
  "liquidanteId": "liq_banco_xyz",
  "ocorridoEm": "2026-04-23T14:35:22Z",
  "cicloRepasse": "2026-04-23"
}
```

Tipos possíveis: `CREDITO` (liquidação), `DEBITO` (estorno), `REPASSE` (transferência para sua conta bancária).

### 2. Cruce com o seu ledger

Para cada linha de `CREDITO`, verifique se a `referenciaExterna` existe no seu sistema com status equivalente a liquidada.

Divergências comuns:

| Situação | Causa provável | Ação |
|  --- | --- | --- |
| CREDITO na Movvia, não encontrado no seu sistema | Webhook de liquidação não processado | Busque a cobrança por `referenciaExterna` e atualize o status local |
| No seu sistema como liquidada, sem CREDITO na Movvia | Liquidação pendente no ciclo | Aguarde o fechamento do ciclo ou consulte o status da cobrança |
| DEBITO sem estorno no seu sistema | Estorno da Movvia automático | Registre o estorno localmente com o `passagemId` |


### 3. Confirme os repasses


```http
GET /ec-api/v1/repasses?desde=2026-04-01&ate=2026-04-30
Authorization: Basic {credencial_ec}
x-ec-id: {ec_id}
```

Para cada repasse `CONFIRMADO`, verifique se o depósito bancário correspondente foi recebido na conta cadastrada.

Para ver as cobranças que compõem um repasse:


```http
GET /ec-api/v1/repasses/{repasseId}/passagens
Authorization: Basic {credencial_ec}
x-ec-id: {ec_id}
```

## Paginação

O extrato pode ter muitas linhas. Use os parâmetros `page` e `pageSize`:


```http
GET /ec-api/v1/extrato?desde=2026-04-01&pageSize=500&page=2
```

Limite máximo por página: 1000 linhas.

## Automatizando a reconciliação

Webhook como trigger
Em vez de puxar o extrato periodicamente, configure webhooks para `pe.passagem.paga`, `pe.passagem.estornada` e `pe.repasse.confirmado`. Seu sistema reage a eventos em vez de polear a API.

Isso reduz latência (você sabe da liquidação em segundos) e o número de chamadas à API.

## Próximo passo

- [Disputas e estornos](/estabelecimentos-comerciais/guides/disputas-estornos) — como estornos afetam o extrato e o repasse.
- [Publicar primeira cobrança](/estabelecimentos-comerciais/tutorials/publicar-primeira-cobranca) — validar o fluxo completo em sandbox.