Conceitos

Idempotência

Nos POST que criam ou mudam dinheiro e notas, o cabeçalho Idempotency-Key é obrigatório. Repetir a mesma chave nunca executa duas vezes.

Operação	Modo
`POST /contacts`, `POST /service-orders`	comum
`POST …/invoice`, `POST …/cancel`	estrito
`POST /webhook-endpoints`, `rotate-secret`, `ping`, `redeliver`, `PATCH`, `DELETE`	não usam a chave

Formato: 1 a 255 caracteres ASCII visíveis, sem espaço. Ex.: pedido-48213-os.
Validade: por integração, 24 horas.
Replay: mesma chave e mesmo corpo devolvem a resposta original com Idempotent-Replayed: true.
Conflito: mesma chave com corpo diferente → 409 IDEMPOTENCY_KEY_CONFLICT.
Guardado: respostas 2xx e 422. Depois de corrigir um 422, use chave nova.
Em andamento: repetir enquanto a primeira roda → 409 IDEMPOTENCY_KEY_IN_PROGRESS. No modo comum, a chave abandonada é retomada após 60 s. No estrito, nunca: consulte a OS e, se a operação não aconteceu, use chave nova.

Referência gerada a partir do contrato OpenAPI 3.1 da API v1 (versão 2026-10-26), conferido contra o código por teste automatizado. Dúvidas: suporte@cuidaro.com.br.