Idempotência

Toda operação mutável exposta publicamente deve receber Idempotency-Key. Na MuPag isso protege contra duplo clique, retry de rede, timeout no cliente e replay acidental do worker.

Como gerar

• Use UUID v4, ULID ou hash do evento de negócio.
• Reaproveite a mesma chave apenas para a mesma intenção semântica.
• Se o payload mudar, gere nova chave.

Onde aplicar

• POST /v1/charges
• POST /v1/customers
• POST /v1/products
• POST /v1/products/{productId}/plans
• POST /v1/coupons
• POST /v1/checkout-sessions
• POST /v1/subscriptions

O que guardar

Persista a chave, o payload canônico e o identificador de negócio. Isso facilita reconciliar 409 Conflict com o primeiro sucesso.