# Liquidação

Liquidação é o processo de associar passagens a um pedido, cobrar seu cliente e confirmar o pagamento à Movvia. Os três endpoints principais são `POST /pedidos`, `POST /pedidos/{id}/confirmar` e `POST /pedidos/{id}/cancelar`.

## Criar um pedido

Agrupe as passagens que deseja liquidar em um pedido. Use sempre uma `idempotencyKey` única por operação.


```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", "t_3b8d4f2e"],
    "idempotencyKey": "ord_20260424_001"
  }'
```

Resposta:


```json
{
  "pedidoId": "ped_a1b2c3d4",
  "status": "pendente",
  "valor": 25.00,
  "transacoes": ["t_9f2c7e1a", "t_3b8d4f2e"],
  "criadoEm": "2026-04-24T10:00:00Z"
}
```

## Confirmar um pedido

Após cobrar seu cliente com sucesso, confirme o pagamento:


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

Resposta:


```json
{
  "pedidoId": "ped_a1b2c3d4",
  "status": "confirmado",
  "confirnadoEm": "2026-04-24T10:05:00Z"
}
```

## Cancelar um pedido

Cancele se não conseguir cobrar o cliente ou se houver erro no seu fluxo:


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

## Máquina de estados


```
pendente → confirmado
pendente → cancelado
confirmado → (terminal, sem transição)
cancelado → (terminal, sem transição)
```

Pedidos em estado terminal não aceitam novas transições. Tentar confirmar ou cancelar um pedido já confirmado retorna `409 Conflict`.

## Prazo para confirmação

Pedidos não confirmados ou cancelados em até 48h são automaticamente cancelados pela plataforma. Um webhook `pe.pedidos.expirado` é emitido antes da expiração.

Boas práticas
- Confirme o pedido no mesmo fluxo em que cobra o cliente, não em um job assíncrono.
- Sempre use `idempotencyKey` distinta para criação e confirmação do mesmo pedido.
- Armazene o `pedidoId` para reconciliação antes de confirmar.