LiqiDevelopers

Idempotência

A Liqi suporta chaves de idempotência para proteger suas integrações contra operações duplicadas. Isso é especialmente importante em operações financeiras (TIDC v1 e CaaS), onde uma requisição repetida por timeout ou falha de rede poderia causar efeitos colaterais indesejados.

Como funciona

Ao enviar uma requisição POST, PUT ou PATCH, inclua o header X-Idempotency-Key com um identificador único gerado pelo seu sistema. Se a mesma chave for enviada novamente dentro da janela de retenção, a API retornará a resposta original sem executar a operação novamente.

Bash
curl -X POST "https://api.liqi.com.br/tidc/v1/credit-batches" \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sua-api-key" \
  -H "X-Timestamp: 1708531200" \
  -H "X-Signature: base64..." \
  -H "X-Idempotency-Key: batch-2026-02-20-001" \
  -d '{ "contracts": [...] }'

Regras

RegraDescrição
Formato da chaveString alfanumérica, até 64 caracteres. Recomendamos UUID v4
UnicidadeA chave deve ser única por operação. Reusar chaves para operações diferentes causará conflito
RetençãoA resposta é cacheada por 24 horas. Após esse período, a mesma chave pode ser reutilizada
EscopoA chave é vinculada à sua API Key ou JWT. Chaves de clientes diferentes não conflitam
MétodosSuportado em POST, PUT e PATCH. Ignorado em GET e DELETE

Comportamento detalhado

Primeira requisição

A operação é executada normalmente. A resposta é armazenada junto com a chave de idempotência.

Text
POST /tidc/v1/credit-batches
X-Idempotency-Key: batch-2026-02-20-001

-> 201 Created (operação executada, resposta armazenada)

Requisição repetida (mesma chave)

A operação não é executada novamente. A resposta armazenada é retornada com o header X-Idempotent-Replayed: true.

Text
POST /tidc/v1/credit-batches
X-Idempotency-Key: batch-2026-02-20-001

-> 201 Created (resposta do cache, sem efeito colateral)
   X-Idempotent-Replayed: true

Chave reutilizada com body diferente

Se você enviar a mesma chave de idempotência mas com um body diferente, a API retornará 409 Conflict:

JSON
{
  "statusCode": 409,
  "message": "Idempotency key already used with a different request body",
  "error": "Conflict"
}

Gerando chaves de idempotência

UUID v4 (recomendado)

TypeScript
import { randomUUID } from "crypto";

const idempotencyKey = randomUUID();
// "550e8400-e29b-41d4-a716-446655440000"

Baseada em operação (para deduplicação de negócio)

Se você quer garantir que uma operação específica não será duplicada, use uma chave determinística:

TypeScript
// Garantir que o mesmo lote não é submetido duas vezes
const idempotencyKey = `credit-batch-${batchId}-submit`;

// Garantir que a mesma ordem não é criada duas vezes
const idempotencyKey = `order-${symbol}-${side}-${amount}-${Date.now()}`;

Exemplo completo

TypeScript
import { randomUUID } from "crypto";

async function createCreditBatch(contracts: unknown[]) {
  const idempotencyKey = randomUUID();
  const body = JSON.stringify({ contracts });

  const response = await fetch(
    "https://api.liqi.com.br/tidc/v1/credit-batches",
    {
      method: "POST",
      headers: {
        "Content-Type": "application/json",
        "X-API-Key": process.env.TIDC_API_KEY!,
        "X-Timestamp": Math.floor(Date.now() / 1000).toString(),
        "X-Signature": signPayload(body), // sua função de assinatura
        "X-Idempotency-Key": idempotencyKey,
      },
      body,
    }
  );

  const wasReplayed = response.headers.get("X-Idempotent-Replayed") === "true";

  if (wasReplayed) {
    console.log("Resposta retornada do cache (operação não duplicada)");
  }

  return response.json();
}

Quando usar

CenárioRecomendação
Criar lotes de cessão de crédito (TIDC v1)Obrigatório
Submeter ordens de trading (CaaS)Recomendado
Transferências PIX/TED (CaaS)Obrigatório
Consultar dados (GET)Não necessário
Atualizar status de lotesRecomendado

Próximos passos

  • Paginação — Navegue por resultados paginados
  • Erros — Trate erros corretamente
  • TIDC v1 — Documentação completa da API de cessão de crédito