Principal Integração e API Como evitar cobrança duplicada ao reenviar uma requisição?

Como evitar cobrança duplicada ao reenviar uma requisição?

Última atualização em Nov 10, 2026

A Dotfy não tem um cabeçalho Idempotency-Key. Onde há proteção contra duplicidade, ela vem de um campo do corpo. Sem essa proteção, um timeout é ambíguo: a operação pode ter acontecido. Por isso, consulte antes de reenviar.

O que vale em cada fluxo

  • PIX (POST /api/charges): o correlationID enviado é descartado, então não conte com ele para evitar duplicidade. Guarde o identificador que a resposta devolve e consulte a cobrança antes de criar outra. Se a resposta não chegou, procure a cobrança na listagem antes de criar outra.
  • Cartão (POST /api/card-charges): idempotente por correlationID. Gere o valor antes da primeira chamada e guarde junto do pedido. Em 202 PROCESSING, 500 ou timeout, reenvie a mesma requisição com o mesmo correlationID. Uma recusa (402) não libera o identificador: se o comprador quiser tentar outro cartão, é um pedido novo, com correlationID novo.
  • Internacional: a criação não tem idempotência. Nunca crie uma segunda cobrança porque o comprador não voltou. Depois de um timeout, consulte pelo id que você guardou. Se o POST deu timeout e você não tem o id, não repita a criação às cegas: liste as cobranças recentes do produto e do país e procure a sua pelo customer.email antes de tentar de novo.
  • Pix Automático: repetir com o mesmo contractId e os mesmos dados devolve a assinatura existente. Com dados diferentes, a resposta é 409.

Repetir ou consultar?

  • 429: nada foi criado. Aguarde, com recuo exponencial, e repita.
  • 503 PROVIDER_BUSY na cobrança internacional: nada foi aberto. Repita depois do prazo informado.
  • 500 com code: PROVIDER_INDETERMINATE na cobrança internacional: pode existir cobrança viva. Consulte antes de qualquer nova tentativa.
  • Fora do cartão, em 502, 504 ou timeout de rede o desfecho é desconhecido: consulte antes de repetir.

Do lado do webhook

A mesma entrega pode chegar mais de uma vez. Use o X-Webhook-ID como chave de idempotência, para não entregar um pedido duas vezes.

Outras boas práticas

  • Trate a faixa 2xx inteira como sucesso.
  • Envie startDate e endDate sempre juntos. Com apenas um, o filtro é ignorado em silêncio.
  • Confira a unidade de cada campo. Entrada costuma ser em reais e saída, em centavos, com exceções.
  • Não compartilhe lógica de paginação entre áreas da API, porque o formato muda.

Veja os detalhes em Convenções.