Skip to content
Last updated

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.

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.
# 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.