import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Repetir pedidos com segurança (Idempotency-Key)

Abrir um dossiê dispara uma consulta paga e consome cota. Se a sua chamada deu timeout ou a conexão caiu, você não sabe se o dossiê foi aberto — e repetir o POST poderia abrir outro. O header Idempotency-Key resolve isso: com ele, repetir o mesmo pedido devolve o dossiê que já foi aberto.

Como usar

Envie Idempotency-Key em POST /kyc/v1/dossiers com um identificador único por pedido, de 16 a 128 caracteres (um UUID serve). O header é opcional.

curl -s -i -X POST "$ZABIT_API/kyc/v1/dossiers" \
  -H "x-api-key: $ZABIT_KEY" \
  -H "content-type: application/json" \
  -H "Idempotency-Key: 5f0c8a52-6a0e-4c9c-8d37-0f6a1b2c3d4e" \
  -d '{"document": "12345678909", "subtype": "kyc", "name": "Maria Exemplo"}'

Gere a chave uma vez por pedido de negócio (por exemplo, ao enfileirar o cadastro do cliente no seu sistema) e guarde-a junto com o pedido. Se precisar repetir, reutilize a mesma.

O que acontece ao repetir

Situação	Resposta
Mesma chave, mesmo corpo, dossiê ainda em processamento	202 com o dossiê que já foi aberto e o header Idempotency-Replayed: true.
Mesma chave, mesmo corpo, dossiê já terminado	200 com o dossiê e Idempotency-Replayed: true.
Mesma chave, corpo diferente	422 com error.code = idempotency_key_conflict. Use outra chave para um pedido diferente.
Duas requisições simultâneas com a mesma chave	Uma abre o dossiê; a outra recebe 409 com error.code = idempotency_key_in_flight. Repita com a mesma chave.
Chave com menos de 16 ou mais de 128 caracteres	400 com error.code = invalid_idempotency_key.

Numa repetição, nenhum dossiê novo é aberto e nenhuma cota é consumida.

Pontos de atenção:

• A chave vale por workspace.
• Para receber o dossiê numa repetição, a chave de API precisa ter permissão para consultar dossiês. Sem ela, a resposta é 403.
• O corpo é comparado nos campos que você controla (document, subtype, name, profile_code, reporting_entity_id). O documento é comparado pelos dígitos: o mesmo CPF com e sem pontuação é o mesmo pedido.
• Sem o header, cada chamada abre um dossiê novo.

Exemplo: repetir depois de um timeout

import uuid
import requests

chave = str(uuid.uuid4())  # gere uma vez por pedido e guarde com ele
corpo = {"document": "12345678909", "subtype": "kyc"}
headers = {"x-api-key": "zbt_SUA_CHAVE", "Idempotency-Key": chave}

for tentativa in range(3):
    try:
        r = requests.post("https://api.v3.zabit.com.br/kyc/v1/dossiers",
                          json=corpo, headers=headers, timeout=30)
    except requests.RequestException:
        continue  # timeout ou rede: repete com a MESMA chave e o MESMO corpo
    if r.status_code == 409:
        continue  # idempotency_key_in_flight: repete com a mesma chave
    break

import { randomUUID } from "node:crypto";

const chave = randomUUID(); // gere uma vez por pedido e guarde com ele
const corpo = { document: "12345678909", subtype: "kyc" };

for (let tentativa = 0; tentativa < 3; tentativa++) {
  try {
    const r = await fetch("https://api.v3.zabit.com.br/kyc/v1/dossiers", {
      method: "POST",
      headers: { "x-api-key": "zbt_SUA_CHAVE", "content-type": "application/json", "Idempotency-Key": chave },
      body: JSON.stringify(corpo),
      signal: AbortSignal.timeout(30_000),
    });
    if (r.status === 409) continue; // idempotency_key_in_flight: repete com a mesma chave
    break;
  } catch {
    // timeout ou rede: repete com a MESMA chave e o MESMO corpo
  }
}

Veja também: Erros · Início rápido.