Idempotência

Falhas de rede, timeouts e retries são uma realidade de sistemas distribuídos. A API Dinie suporta chaves de idempotência para que você possa reenviar requisições POST com segurança sem criar recursos duplicados acidentalmente.

Uma operação é idempotente se executá-la múltiplas vezes produz o mesmo resultado que executá-la uma única vez. Por exemplo, GET e DELETE são naturalmente idempotentes -- buscar ou deletar o mesmo recurso duas vezes tem o mesmo efeito. Mas POST (criação) não é naturalmente idempotente -- enviar duas vezes pode criar dois recursos.

O header Idempotency-Key torna requisições POST idempotentes ao associar a requisição a uma chave única. Se a mesma chave for enviada novamente, a API retorna a resposta em cache da primeira requisição em vez de processar uma nova.

Inclua um header Idempotency-Key em requisições POST que criam recursos:

const customer = await dinie.customers.create(
  {
    cpf: "123.456.789-00",
    name: "Joao Silva",
    email: "joao@example.com",
  },
  { idempotencyKey: "partner-onboard-joao-2026-03-04" }
);

Chaves de idempotência são suportadas em todas as requisições POST que criam recursos:

Info: GET, PATCH e DELETE são naturalmente idempotentes e não requerem o header. Você pode reenviar essas requisições com segurança sem nenhum tratamento especial.

1. Você envia uma requisição POST com um header Idempotency-Key
2. A API processa a requisição e armazena a resposta em cache, indexada por (partner_id, idempotency_key)
3. Se você enviar a mesma chave novamente dentro de 24 horas, a API retorna a resposta em cache sem reprocessar
4. Após 24 horas, a resposta em cache expira e a chave pode ser reutilizada

Chaves de idempotência ficam em cache por 24 horas. Após esse período:

• A chave expira e a resposta em cache é descartada
• Enviar a mesma chave vai processar uma nova requisição
• Se precisar reenviar após 24 horas, use uma nova chave de idempotência

Se você enviar a mesma chave de idempotência com um corpo de requisição diferente, a API retorna a resposta em cache da primeira requisição. Ela não compara os corpos das requisições -- a chave sozinha determina a resposta em cache.

Warning: Sempre use chaves de idempotência únicas para operações diferentes. Um bom padrão é combinar um prefixo semântico com um identificador único:

• create-customer-{external_id}
• create-loan-{offer_id}-{timestamp}
• upload-doc-{customer_id}-{doc_type}

Escolha uma estratégia que garanta unicidade em toda a sua aplicação:

Os SDKs geram automaticamente um UUID como chave de idempotência para toda requisição POST, independentemente da configuração de retries. Isso garante que requisições POST nunca criem recursos duplicados, mesmo em cenários de falha de rede.

O SDK gera um UUID único para cada chamada POST. Você não precisa fazer nada:

const dinie = new Dinie({
  clientId: process.env.DINIE_CLIENT_ID,
  clientSecret: process.env.DINIE_CLIENT_SECRET,
});

// O SDK gera automaticamente um Idempotency-Key UUID para esta requisição
const customer = await dinie.customers.create({
  cpf: "123.456.789-00",
  name: "Joao Silva",
  email: "joao@example.com",
});

Passe sua própria chave quando precisar de deduplicação determinística baseada na lógica de negócio. A chave explícita sobrescreve a gerada automaticamente:

// Use uma chave baseada em identificadores de negócio para deduplicação natural
const customer = await dinie.customers.create(
  {
    cpf: "123.456.789-00",
    name: "Joao Silva",
    email: "joao@example.com",
  },
  { idempotencyKey: "create-customer-partner-ref-123" }
);

Use chaves explícitas quando:

• A operação deve ser deduplicada com base em identificadores de negócio (não apenas por requisição)
• Diferentes partes do sistema podem tentar a mesma operação
• Você precisa correlacionar retries com a operação original

1. Sempre use chaves de idempotência para criação de empréstimos (POST /v3/loans). Esta é uma operação financeira onde duplicatas são custosas.
2. Use chaves determinísticas baseadas em identificadores de negócio quando possível. Isso proporciona deduplicação natural mesmo entre tentativas de retry separadas.
3. Armazene a chave de idempotência junto com seu registro interno para correlacionar retries com a operação original.
4. Não reutilize chaves para operações diferentes, mesmo após a janela de 24 horas.