# Idempotência

Operações de escrita na API Movvia aceitam mecanismos de idempotência para garantir que retentativas não causem processamento duplicado. O comportamento exato varia por persona.

## Parceiros — chave de idempotência em pedidos

Ao criar pedidos, inclua uma chave única no campo `idempotencyKey`. Se a requisição for reenviada com a mesma chave, a API retorna o resultado original sem criar um novo recurso.


```http
POST /gestao-webhooks-api/v1/pedidos
Authorization: Basic {credencial}
x-parceiro-id: {parceiroId}
Content-Type: application/json

{
  "transacoes": ["t_9f2c7e1a"],
  "idempotencyKey": "ord_2026-04-24-cliente-123"
}
```

**Como gerar a chave:** use um identificador único por operação no seu sistema, como `{prefixo}_{id_transacao}_{timestamp}`. A chave deve ser estável entre tentativas do mesmo pedido.

**TTL:** consultar comercial para o prazo de validade da chave em produção.

Reuso da chave
Reenviar uma requisição com a mesma `idempotencyKey` retorna `200 OK` com o recurso original. A operação não é reprocessada.

## Vision Dados — idempotência via externalId

Na ingestão de passagens visuais, a idempotência é garantida pelo campo `externalId`. O par `(concessionariaId, externalId)` é a chave de deduplicação.

- Primeiro envio: `201 Created` — passagem criada.
- Reenvio com mesmo `externalId`: `200 OK` — retorna o registro original sem re-armazenar a imagem.



```bash
# Primeiro envio → 201 Created
curl -X POST .../vision-dados/v1/passagens-visuais \
  -u "$USUARIO:$SENHA" \
  -H "x-concessionaria-id: 42" \
  -F "image=@passagem.jpg;type=image/jpeg" \
  -F 'metadata={"externalId":"passagem-2026-04-24-000123",...};type=application/json'

# Reenvio com mesmo externalId → 200 OK
curl -X POST .../vision-dados/v1/passagens-visuais \
  -u "$USUARIO:$SENHA" \
  -H "x-concessionaria-id: 42" \
  -F "image=@passagem.jpg;type=image/jpeg" \
  -F 'metadata={"externalId":"passagem-2026-04-24-000123",...};type=application/json'
```

O `externalId` é único por concessionária. Concessionárias diferentes podem usar o mesmo valor sem conflito.

## Idempotência no DELETE

O endpoint `DELETE /passagens-visuais/{id}` também é idempotente. Chamar `DELETE` em uma passagem com `status: EXCLUIDA` retorna `202 Accepted` com o `scheduledDeletionAt` original, sem erro.

## Boas práticas

- Sempre inclua uma chave de idempotência em operações financeiras ou que movem dados irreversíveis.
- Não reutilize a mesma chave para operações diferentes — isso pode retornar um resultado inválido para o novo contexto.
- Em caso de timeout ou erro de rede, reenvie a mesma requisição com a mesma chave antes de criar uma nova operação.