{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-parceiros/sidebars.yaml"},"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 (",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /pedidos"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /pedidos/{id}/confirmar"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /pedidos/{id}/cancelar"]},") aceitam o campo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotencyKey"]},". Com ela, reenviar a mesma requisição em caso de falha de rede não gera duplicatas."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"como-funciona","__idx":1},"children":["Como funciona"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Você envia uma requisição com ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotencyKey: \"ord_20260424_001\""]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A Movvia processa e armazena o resultado associado à chave."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Se você reenviar a mesma requisição com a mesma chave, a Movvia retorna o resultado original sem reprocessar."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["A chave expira após ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["24 horas"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"formato-da-chave","__idx":2},"children":["Formato da chave"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A chave é uma string livre de até 64 caracteres. Use um formato que identifique a operação e o contexto:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"ord_{data}_{seq}         → ord_20260424_001\nconf_{pedidoId}          → conf_ped_a1b2c3d4\ncanc_{pedidoId}_{motivo} → canc_ped_a1b2c3d4_falha\n"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"exemplo-criar-pedido-com-idempotência","__idx":3},"children":["Exemplo: criar pedido com idempotência"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"bash","header":{"controls":{"copy":{}}},"source":"curl -X POST https://hml.api.pedagioeletronico.com.br/gestao-webhooks-api/v1/pedidos \\\n  -H \"Authorization: Basic $MV_KEY\" \\\n  -H \"x-parceiro-id: $MV_PARCEIRO_ID\" \\\n  -H \"Content-Type: application/json\" \\\n  -d '{\n    \"transacoes\": [\"t_9f2c7e1a\"],\n    \"idempotencyKey\": \"ord_20260424_001\"\n  }'\n","lang":"bash"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se a mesma requisição for enviada novamente (timeout, retry de rede), o header ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["x-idempotent-replayed: true"]}," aparece na resposta, e o body é idêntico ao original."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"comportamento-em-conflito","__idx":4},"children":["Comportamento em conflito"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Se você enviar a mesma ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["idempotencyKey"]}," com um body diferente (transações distintas), a API retorna ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["409 Conflict"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"erro\": \"IDEMPOTENCY_CONFLICT\",\n  \"mensagem\": \"Chave já usada com payload diferente.\"\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"regras","__idx":5},"children":["Regras"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Regra"},"children":["Regra"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Detalhe"},"children":["Detalhe"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Escopo"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Por parceiro + operação. A mesma chave pode ser reutilizada em operações distintas (criar vs confirmar)."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["TTL"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["24h após a primeira requisição bem-sucedida."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Reuso"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Após o TTL, a chave pode ser reutilizada. Prefira chaves únicas para auditoria."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Falhas"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Requisições que retornaram erro (5xx) não consomem a chave — pode reenviar com a mesma chave."]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Webhooks também são idempotentes"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["O campo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["id"]}," de cada evento de webhook funciona como chave de idempotência no seu lado. Armazene os IDs processados para descartar reentregas."]}]}]},"headings":[{"value":"Idempotência","id":"idempotência","depth":1},{"value":"Como funciona","id":"como-funciona","depth":2},{"value":"Formato da chave","id":"formato-da-chave","depth":2},{"value":"Exemplo: criar pedido com idempotência","id":"exemplo-criar-pedido-com-idempotência","depth":2},{"value":"Comportamento em conflito","id":"comportamento-em-conflito","depth":2},{"value":"Regras","id":"regras","depth":2}],"frontmatter":{"title":"Idempotência — Parceiros Movvia","description":"Como usar chaves de idempotência na API de Parceiros Movvia para evitar operações duplicadas.","seo":{"title":"Idempotência"}},"lastModified":"2026-04-25T15:17:56.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/parceiros/guides/idempotencia","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}