Idempotência

O que é idempotência?

Idempotência garante que uma operação produza o mesmo resultado independentemente de quantas vezes seja executada, desde que os mesmos parâmetros sejam usados. Em pagamentos, isso é essencial para evitar cobranças duplicadas em cenários como:

Timeouts — a requisição foi enviada mas a resposta não chegou
Retries automáticos — o SDK ou seu cliente tentou novamente após um erro
Falhas de rede — a conexão caiu antes de receber a confirmação
Double-submit — o usuário clicou duas vezes no botão “Pagar”

`idempotencyKey` como cidadão de primeira classe

No pagamentos.dev, a idempotencyKey é um campo obrigatório em todas as operações de mutação — criar, atualizar e cancelar. Ela é passada diretamente no payload da requisição, junto com valor e metodoPagamento:

const cobranca = await pg.cobrancas.create({
  idempotencyKey: crypto.randomUUID(), // ← sempre uma chave única!
  valor: 1000,
  metodoPagamento: 'pix',
  cliente: {
    nome: 'João Silva',
    documento: '123.456.789-00'
  }
})

A idempotencyKey é repassada ao provedor de pagamento de acordo com o mecanismo suportado por cada um:

Provedor	Mecanismo	Suporte
Mercado Pago	Header `X-Idempotency-Key`	✅ Completo
Woovi	Campo `correlationID` no body	✅ Completo
AbacatePay	PIX é assíncrono, chave é ignorada	⚠️ Sem suporte

Como funciona na prática

Gere a chave antes de chamar a API

A chave deve ser gerada no cliente (frontend ou serviço que inicia a requisição) e armazenada para uso em retentativas:

import { randomUUID } from 'node:crypto'

async function criarCobranca(valor: number) {
  // 1. Gere e armazene a chave ANTES de chamar a API
  const idempotencyKey = randomUUID()

  try {
    const cobranca = await pg.cobrancas.create({
      idempotencyKey,
      valor,
      metodoPagamento: 'pix',
      cliente: {
        nome: 'João Silva',
        email: 'joao@email.com'
      }
    })

    // 2. Salve a chave junto com o resultado
    await salvarTransacao({ cobranca, idempotencyKey })
    return cobranca

  } catch (error) {
    // 3. Em caso de erro, retente com a MESMA chave
    //    O provedor reconhecerá a chave e retornará o
    //    resultado original, sem criar duplicatas.
    const cobranca = await pg.cobrancas.create({
      idempotencyKey, // ← mesma chave!
      valor,
      metodoPagamento: 'pix',
      cliente: {
        nome: 'João Silva',
        email: 'joao@email.com'
      }
    })

    await salvarTransacao({ cobranca, idempotencyKey })
    return cobranca
  }
}

Em operações de update e cancel

// Update com idempotência
await pg.cobrancas.update('cob-123', {
  idempotencyKey: randomUUID(),
  valor: 2000
})

// Cancel com idempotência
await pg.cobrancas.cancel('cob-123', {
  idempotencyKey: randomUUID()
})

Boas práticas

1. Sempre gere uma chave única por operação

Use crypto.randomUUID() (disponível em Node.js, Bun e navegadores modernos) para gerar chaves. Nunca reutilize a mesma chave para operações diferentes.

// ✅ Correto
const cobranca = await pg.cobrancas.create({
  idempotencyKey: crypto.randomUUID(),
  valor: 1000,
  metodoPagamento: 'pix'
})

// ❌ Errado — mesma chave para operações diferentes
const chaveRepetida = 'chave-fixa'
await pg.cobrancas.create({ idempotencyKey: chaveRepetida, ... })
await pg.clientes.create({ idempotencyKey: chaveRepetida, ... })

2. Armazene a chave para retentativas

Salve a idempotencyKey no seu banco de dados junto com a transação. Se a requisição falhar por timeout, você pode retentar com a mesma chave com segurança.

// Salve junto com a transação
await db.transacoes.insert({
  idempotencyKey,
  cobrancaId: cobranca.id,
  status: cobranca.status,
  criadoEm: new Date()
})

// Consulte antes de criar (se você mesmo gerencia idempotência)
const existente = await db.transacoes.findByKey(idempotencyKey)
if (existente) {
  return existente.cobrancaId // já processamos esta operação
}

3. Trate erros de forma idempotente

Em caso de timeout ou erro de rede, retente a operação com a mesma chave. O provedor (Woovi/Mercado Pago) detectará a chave repetida e retornará o resultado original.

async function criarComRetry(dados: CreateInput, maxRetries = 3) {
  const idempotencyKey = randomUUID()

  for (let tentativa = 1; tentativa <= maxRetries; tentativa++) {
    try {
      return await pg.cobrancas.create({ ...dados, idempotencyKey })
    } catch (error) {
      if (tentativa === maxRetries) throw error
      if (!isErroRetryavel(error)) throw error
      await sleep(1000 * tentativa) // backoff exponencial
    }
  }
}

Referência

A idempotencyKey está disponível nos seguintes tipos de input:

Tipo	Campo
`ClienteCreateInput`	`idempotencyKey?: string`
`ClienteUpdateInput`	`idempotencyKey?: string` (via `Partial`)
`CobrancaCreateInput`	`idempotencyKey?: string`
`CobrancaUpdateInput`	`idempotencyKey?: string`
`CobrancaCancelInput`	`idempotencyKey?: string`
`CheckoutCreateInput`	`idempotencyKey?: string`

A idempotencyKey é opcional em todos os tipos, mas fortemente recomendada para operações de criação e atualização. Sem ela, retentativas podem gerar duplicatas.

Fundamentos

Métodos de Pagamento

Funcionalidades

O que é idempotência?

`idempotencyKey` como cidadão de primeira classe

Como funciona na prática

Gere a chave antes de chamar a API

Em operações de update e cancel

Boas práticas

1. Sempre gere uma chave única por operação

2. Armazene a chave para retentativas

3. Trate erros de forma idempotente

Referência

​O que é idempotência?

​idempotencyKey como cidadão de primeira classe

​Como funciona na prática

​Gere a chave antes de chamar a API

​Em operações de update e cancel

​Boas práticas

​1. Sempre gere uma chave única por operação

​2. Armazene a chave para retentativas

​3. Trate erros de forma idempotente

​Referência

O que é idempotência?

`idempotencyKey` como cidadão de primeira classe

Como funciona na prática

Gere a chave antes de chamar a API

Em operações de update e cancel

Boas práticas

1. Sempre gere uma chave única por operação

2. Armazene a chave para retentativas

3. Trate erros de forma idempotente

Referência