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.
- Você envia uma requisição com
idempotencyKey: "ord_20260424_001". - A Movvia processa e armazena o resultado associado à chave.
- Se você reenviar a mesma requisição com a mesma chave, a Movvia retorna o resultado original sem reprocessar.
- A chave expira após 24 horas.
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_falhacurl -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.
Se você enviar a mesma idempotencyKey com um body diferente (transações distintas), a API retorna 409 Conflict:
{
"erro": "IDEMPOTENCY_CONFLICT",
"mensagem": "Chave já usada com payload diferente."
}| 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.