{"templateId":"markdown","sharedDataIds":{},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Idempotência","description":"APIs públicas da Movvia para parceiros, estabelecimentos comerciais e clientes de dados veiculares.","meta":[{"name":"theme-color","content":"#7E3DEE"},{"name":"apple-mobile-web-app-title","content":"Movvia Docs"},{"name":"application-name","content":"Movvia Docs"}],"llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"idempotência","__idx":0},"children":["Idempotência"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"parceiros--chave-de-idempotência-em-pedidos","__idx":1},"children":["Parceiros — chave de idempotência em pedidos"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ao criar pedidos, inclua uma chave única no campo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotencyKey"]},". Se a requisição for reenviada com a mesma chave, a API retorna o resultado original sem criar um novo recurso."]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"http","header":{"controls":{"copy":{}}},"source":"POST /gestao-webhooks-api/v1/pedidos\nAuthorization: Basic {credencial}\nx-parceiro-id: {parceiroId}\nContent-Type: application/json\n\n{\n  \"transacoes\": [\"t_9f2c7e1a\"],\n  \"idempotencyKey\": \"ord_2026-04-24-cliente-123\"\n}\n","lang":"http"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Como gerar a chave:"]}," use um identificador único por operação no seu sistema, como ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{prefixo}_{id_transacao}_{timestamp}"]},". A chave deve ser estável entre tentativas do mesmo pedido."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["TTL:"]}," consultar comercial para o prazo de validade da chave em produção."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Reuso da chave"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Reenviar uma requisição com a mesma ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotencyKey"]}," retorna ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}," com o recurso original. A operação não é reprocessada."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"vision-dados--idempotência-via-externalid","__idx":2},"children":["Vision Dados — idempotência via externalId"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Na ingestão de passagens visuais, a idempotência é garantida pelo campo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalId"]},". O par ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["(concessionariaId, externalId)"]}," é a chave de deduplicação."]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Primeiro envio: ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201 Created"]}," — passagem criada."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reenvio com mesmo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalId"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200 OK"]}," — retorna o registro original sem re-armazenar a imagem."]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"# Primeiro envio → 201 Created\ncurl -X POST .../vision-dados/v1/passagens-visuais \\\n  -u \"$USUARIO:$SENHA\" \\\n  -H \"x-concessionaria-id: 42\" \\\n  -F \"image=@passagem.jpg;type=image/jpeg\" \\\n  -F 'metadata={\"externalId\":\"passagem-2026-04-24-000123\",...};type=application/json'\n\n# Reenvio com mesmo externalId → 200 OK\ncurl -X POST .../vision-dados/v1/passagens-visuais \\\n  -u \"$USUARIO:$SENHA\" \\\n  -H \"x-concessionaria-id: 42\" \\\n  -F \"image=@passagem.jpg;type=image/jpeg\" \\\n  -F 'metadata={\"externalId\":\"passagem-2026-04-24-000123\",...};type=application/json'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalId"]}," é único por concessionária. Concessionárias diferentes podem usar o mesmo valor sem conflito."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"idempotência-no-delete","__idx":3},"children":["Idempotência no DELETE"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O endpoint ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE /passagens-visuais/{id}"]}," também é idempotente. Chamar ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}," em uma passagem com ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["status: EXCLUIDA"]}," retorna ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["202 Accepted"]}," com o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["scheduledDeletionAt"]}," original, sem erro."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"boas-práticas","__idx":4},"children":["Boas práticas"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Sempre inclua uma chave de idempotência em operações financeiras ou que movem dados irreversíveis."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Não reutilize a mesma chave para operações diferentes — isso pode retornar um resultado inválido para o novo contexto."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Em caso de timeout ou erro de rede, reenvie a mesma requisição com a mesma chave antes de criar uma nova operação."]}]}]},"headings":[{"value":"Idempotência","id":"idempotência","depth":1},{"value":"Parceiros — chave de idempotência em pedidos","id":"parceiros--chave-de-idempotência-em-pedidos","depth":2},{"value":"Vision Dados — idempotência via externalId","id":"vision-dados--idempotência-via-externalid","depth":2},{"value":"Idempotência no DELETE","id":"idempotência-no-delete","depth":2},{"value":"Boas práticas","id":"boas-práticas","depth":2}],"frontmatter":{"title":"Idempotência","description":"Como usar chaves de idempotência nas operações de escrita da API Movvia para evitar processamento duplicado em retentativas.","seo":{"title":"Idempotência"}},"lastModified":"2026-04-25T15:17:56.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/compartilhado/seguranca/idempotencia","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}