Skip to main content
Operações de escrita (POST/PUT/PATCH) que envolvem movimentação financeira exigem uma chave de idempotência para evitar processamento duplicado em caso de retries de rede.

​
Como funciona

  1. O cliente gera um identificador único (UUID) para cada operação.
  2. Envia o valor no cabeçalho IdempotencyKey.
  3. A Delfinance armazena a resposta associada a essa chave por 24 horas.
  4. Qualquer requisição subsequente com a mesma chave retorna a resposta original, sem executar a operação novamente.

​
Formato da chave

  • Tipo: UUID v4 recomendado.
  • Tamanho: máximo 64 caracteres.
  • Escopo: único por operação (não reutilize para requisições diferentes).

​
Exemplo de uso

curl -X POST https://apisandbox.delbank.com.br/v1/payments \
  --cert ./certificado.crt \
  --key ./chave-privada.key \
  -H "Authorization: Bearer eyJhbGciOi..." \
  -H "Content-Type: application/json" \
  -H "IdempotencyKey: 550e8400-e29b-41d4-a716-446655440000" \
  -d '{
    "valor": 100.00,
    "destinatario": "12345678900"
  }'

import { randomUUID } from 'crypto';

const idempotencyKey = randomUUID();

await axios.post(
  'https://apisandbox.delbank.com.br/v1/payments',
  { valor: 100.0, destinatario: '12345678900' },
  {
    headers: {
      Authorization: `Bearer ${accessToken}`,
      IdempotencyKey: idempotencyKey,
    },
    httpsAgent: agent,
  }
);

import uuid

idempotency_key = str(uuid.uuid4())

requests.post(
    "https://apisandbox.delbank.com.br/v1/payments",
    cert=("./certificado.crt", "./chave-privada.key"),
    headers={
        "Authorization": f"Bearer {access_token}",
        "IdempotencyKey": idempotency_key,
    },
    json={"valor": 100.00, "destinatario": "12345678900"},
)

​
Comportamento

CenárioComportamento
Primeira requisição com a chaveExecuta a operação e armazena a resposta
Requisição repetida com payload idênticoRetorna a resposta armazenada (não reprocessa)
Requisição repetida com payload diferenteRetorna erro 409 Conflict
Requisição após 24 horasChave expirada, operação é executada novamente

​
Endpoints que exigem idempotência

  • POST /v1/payments
  • POST /v1/transfers
  • POST /v1/refunds
  • POST /v1/pix
Endpoints de consulta (GET) são naturalmente idempotentes e não exigem o cabeçalho.

​
Estratégia de retries

1

Gere a chave uma única vez

Antes da primeira tentativa, gere e persista a chave.
2

Reutilize em retries

Em falhas de rede ou timeouts, envie a mesma chave.
3

Aplique backoff exponencial

Aguarde 1s, 2s, 4s, 8s entre tentativas.
4

Limite de tentativas

Máximo de 5 retries. Após isso, escale o erro.
Nunca gere uma nova chave de idempotência em retries — isso pode causar duplicação de operações financeiras.

​
Erros relacionados

CódigoDescrição
400 missing_idempotency_keyCabeçalho ausente em endpoint obrigatório
409 idempotency_conflictChave reutilizada com payload diferente
422 invalid_idempotency_keyFormato inválido (não UUID)