# Idempotência

Operações de escrita (`POST /pedidos`, `POST /pedidos/{id}/confirmar`, `POST /pedidos/{id}/cancelar`) aceitam o campo `idempotencyKey`. Com ela, reenviar a mesma requisição em caso de falha de rede não gera duplicatas.

## Como funciona

1. Você envia uma requisição com `idempotencyKey: "ord_20260424_001"`.
2. A Movvia processa e armazena o resultado associado à chave.
3. Se você reenviar a mesma requisição com a mesma chave, a Movvia retorna o resultado original sem reprocessar.
4. A chave expira após **24 horas**.


## Formato da chave

A chave é uma string livre de até 64 caracteres. Use um formato que identifique a operação e o contexto:


```
ord_{data}_{seq}         → ord_20260424_001
conf_{pedidoId}          → conf_ped_a1b2c3d4
canc_{pedidoId}_{motivo} → canc_ped_a1b2c3d4_falha
```

## Exemplo: criar pedido com 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_20260424_001"
  }'
```

Se a mesma requisição for enviada novamente (timeout, retry de rede), o header `x-idempotent-replayed: true` aparece na resposta, e o body é idêntico ao original.

## Comportamento em conflito

Se você enviar a mesma `idempotencyKey` com um body diferente (transações distintas), a API retorna `409 Conflict`:


```json
{
  "erro": "IDEMPOTENCY_CONFLICT",
  "mensagem": "Chave já usada com payload diferente."
}
```

## Regras

| Regra | Detalhe |
|  --- | --- |
| **Escopo** | Por parceiro + operação. A mesma chave pode ser reutilizada em operações distintas (criar vs confirmar). |
| **TTL** | 24h após a primeira requisição bem-sucedida. |
| **Reuso** | Após o TTL, a chave pode ser reutilizada. Prefira chaves únicas para auditoria. |
| **Falhas** | Requisições que retornaram erro (5xx) não consomem a chave — pode reenviar com a mesma chave. |


Webhooks também são idempotentes
O campo `id` de cada evento de webhook funciona como chave de idempotência no seu lado. Armazene os IDs processados para descartar reentregas.