{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":[]},"type":"markdown"},"seo":{"title":"Idempotência","description":"Documentação oficial, guias e referência da API Auvo v2.","siteUrl":"https://developers.auvo.com.br","lang":"pt-BR","keywords":"auvo, api, documentação, developers, field service, workforce","meta":[{"name":"og:site_name","content":"Auvo Developers"},{"name":"og:locale","content":"pt_BR"},{"name":"og:locale:alternate","content":"es_ES"},{"name":"og:locale:alternate","content":"en_US"},{"name":"twitter:card","content":"summary_large_image"},{"name":"twitter:site","content":"@auvoapp"}],"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":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PUT"]}," e ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["DELETE"]}," já são idempotentes por padrão HTTP. Para ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," e"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH"]}," em recursos sensíveis (tarefas, OS, tickets), siga as práticas abaixo."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"correlação-por-externalid","__idx":1},"children":["Correlação por ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalId"]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Envie um identificador gerado pelo seu sistema em ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalId"]}," (ex.: ID do"," ","ERP). Antes de criar, chame o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," correspondente filtrando por ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["externalId"]},"."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Se existir, atualize via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PATCH"]},"; se não, crie via ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]},"."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"chave-de-idempotência-por-entrega-webhooks","__idx":2},"children":["Chave de idempotência por entrega (Webhooks)"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Use ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["deliveryId"]}," do payload para deduplicar do seu lado (write-once em tabela"," ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["webhook_deliveries"]},")."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"política-de-retry-segura","__idx":3},"children":["Política de retry segura"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"ts","header":{"controls":{"copy":{}}},"source":"async function postWithSafety(body) {\n  const existing = await findByExternalId(body.externalId);\n  if (existing) return existing;\n  try {\n    return await api.post('/tasks', body);\n  } catch (err) {\n    if (err.status === 409) {\n      return findByExternalId(body.externalId);\n    }\n    throw err;\n  }\n}\n","lang":"ts"},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"em-roadmap","__idx":4},"children":["Em roadmap"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Suporte nativo a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["Idempotency-Key"]}," (padrão Stripe-like) — acompanhe o"," ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/changelog"},"children":["changelog"]},"."]}]}]},"headings":[{"value":"Idempotência","id":"idempotência","depth":1},{"value":"Correlação por externalId","id":"correlação-por-externalid","depth":2},{"value":"Chave de idempotência por entrega (Webhooks)","id":"chave-de-idempotência-por-entrega-webhooks","depth":2},{"value":"Política de retry segura","id":"política-de-retry-segura","depth":2},{"value":"Em roadmap","id":"em-roadmap","depth":2}],"frontmatter":{"title":"Idempotência","description":"Como garantir segurança em retries de POST/PATCH.","seo":{"title":"Idempotência"}},"lastModified":"2026-04-24T13:01:34.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/guides/idempotency","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}